调用专家

调用一个袋袋专家（AI Agent），通过 SSE 流式获取完整回复，包括文本输出、工具调用和 token 用量。

POST https://api.profy.cn/v1/agents/run

认证

string

必填

Bearer sk-pro-xxxx（API Key）或 Bearer <access_token>（OAuth）

string

API Key 调用必填。稳定的终端用户 id，用来隔离会话、文件和记忆。不带返回 400，原文以 Missing required header: X-Profy-End-User-Id 开头。OAuth 调用不需要这个头。计费仍记在 Key 主人身上。

请求体

人格、子任务和可委托专家的默认值在创作者中心。profy-skills 不会自动加载。这个接口不接受 instructions。

string | object

必填

专家标识。最小写法是字符串。对象写法用 id 指向同一位专家，并可带 model 与 tools。 model 只写模型名。tools 只管这一轮的扩展工具，不管整个工具箱。不写这个字段时，扩展关掉，web_search 和 web_fetch 仍然开着。写出数组后，只有列出来的类型开着；空数组会把扩展、web_search、web_fetch 一起关掉。每一项都是 {"type": ...}，不能写字符串。允许的 type：imagegen、video、music、audio、generate_3d、postprocess_3d、generate_world、schedule、knowledge、obsidian_knowledge、memory、delegation、distill、evolution、web_search、web_fetch、mcp。mcp 必须带 server_label，并且 transport.type 为 http、transport.server_url 为远程地址；它只是再挂一个这一轮的 HTTP 服务，不会拆掉专家上已经配好的 MCP。read、bash、skill 不论写不写都在。插件走 environment.plugins，不走这份名单。顶层 expert_identifier 仍可作为 agent 的别名，并且优先于 agent.id。顶层 model 是 agent.model 的别名，对象里的 model 优先。 rules 写出时替换这一轮的 identity / soul / agent / guard。不写则用创作者中心的原文。空数组表示这一轮不带这些规则。type 只能是这四个，每种最多一次。 subagents 写出时替换这一轮的子任务名单，并打开派生子任务。不写则用专家上的名单，还要看 Key 主人有没有打开多任务。agents 每一项要有 name、description、system_prompt、tools，model 可选。 expert_partner 写出时替换这一轮可委托的专家名单。不写则用平台按白名单和 @ 提及拼出的名单。空数组表示这一轮不委托任何人。每一项必填 identifier，可选 name、brief（或 description）、needs_sandbox、mentioned。写进名单不等于获得使用权，真正委托时仍会校验这个专家你能不能用。

object

可选。type 取 profy_hosted（平台沙箱）、self_hosted（调用方自己的桌面）或 none（不提供 shell）。不传时按 profy_hosted。其它值（包括 openai_hosted）返回 400。 skills 每一项是 {"type":"built_in","name":"docx"} 或 {"type":"customize","name":"..."}。 profy-skills 只有写进这个数组才会加载。built_in 按名字加载包里的一个技能，name 为 "*" 时加载整包。不写 skills，这一轮就没有产品技能包。 customize 在 profy_hosted 读 Key 主人或专家技能库里的同名技能，在 self_hosted 读本机 ~/.agents/skills/<name>/SKILL.md。不写这个字段时，用户、专家、工作区技能仍会出现在发现列表里。专家上标记为内置包或自进化的技能会带上全文；其余技能只有在这里写成 customize，或通过 skill_names 点名，才会预取全文。 plugins 每一项是 {"type":"built_in","id":"profy-sites"}，对应已安装插件。 capability_directories 只在 self_hosted 使用，列出本机技能或插件目录。路径不能包含 ..。

string | array

必填

发给专家的内容。字符串，或 { role, content } 消息数组。缺了返回 Missing required field: input。message 仍可作为别名。

boolean

必须为 true 或省略。false 返回 400。这个接口只返回 SSE。

string

会话 ID，用于多轮对话。首次调用无需传入，响应头 X-Session-Id 中会返回新的 session_id。

string[]

附件文件 ID 列表，最多 20 个。ID 由上传文件接口返回。平台会把这些文件放进这次会话的目录（/home/user/workspace/<expert_identifier>/<session_id>/），专家可以用 read / grep 读取。只接受文件 ID，不接受 URL —— 平台不会去下载你提供的任意链接，所以你不需要把私有文档暴露成公开可读的链接。

object[]

HITL 续跑。非空时 input 可以不写。session_id 必须是发出 approval.required 的那一轮。每一项必填 tool_call_id、tool_name、decision。Ask 的答案放在 modified_parameters.result。可选 result、original_parameters、rejection_reason、is_error。toolCallId 这类 camelCase 同样接受。

请求示例

from profy import Profy

async with Profy(api_key="sk-pro-your-key") as client:
    result = await client.agents.run(
        "my-expert",
        "帮我分析一下这段代码的性能问题",
        session_id="existing-session-id",  # 可选
        model="deepseek-v3",               # 可选
    )
    print(result.text)
    print(f"工具调用: {[t.name for t in result.tool_calls]}")

import { Profy } from "@profy-ai/sdk";

const client = new Profy({ apiKey: "sk-pro-your-key" });

const result = await client.agents.run(
  "my-expert",
  "帮我分析一下这段代码的性能问题",
  {
    sessionId: "existing-session-id",
    model: "deepseek-v3",
  }
);

console.log(result.text);
console.log("工具调用:", result.toolCalls.map(t => t.name));

curl -N https://api.profy.cn/v1/agents/run \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "X-Profy-End-User-Id: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-expert",
    "input": "Create tree.py and run it.",
    "stream": true
  }'

需要在这一轮改模型或专属工具时，把可选项写进同一个请求：

curl -N https://api.profy.cn/v1/agents/run \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "X-Profy-End-User-Id: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "id": "my-expert",
      "model": "gpt-6-astra",
      "tools": [
        { "type": "knowledge" },
        { "type": "web_search" },
        {
          "type": "mcp",
          "server_label": "openai_docs",
          "transport": { "type": "http", "server_url": "https://developers.openai.com/mcp" }
        }
      ]
    },
    "environment": { "type": "profy_hosted" },
    "input": "Create tree.py and run it.",
    "stream": true
  }'

响应格式

响应为 SSE（Server-Sent Events）流，事件使用层级点分命名（对标 OpenAI Responses API）。响应头中包含 X-Session-Id，用于后续多轮对话。

event: run.in_progress
data: {"type":"run.in_progress","model_name":"deepseek-v3","session_id":"ses_abc123","event_id":2}

SSE 事件类型

每条 data 都带递增的 event_id 和与 event: 行相同的 type。文本和思维链把内部的 content 改名为 delta。完整词表见 SSE 事件。未映射的内部事件保持原 type。

生命周期事件

事件	说明	关键字段
`run.created`	请求已受理，正在准备	`stage`, `message`
`run.in_progress`	一轮推理开始。一次运行里可以出现多次	`session_id`, `model_name`, `turn_id`, `capabilities`
`run.completed`	运行正常结束	`content`, `summary`, `finish_reason`
`run.failed`	运行失败	`error`, `error_code`, `failure_class`

输出事件

事件	说明	关键字段
`output.text.delta`	文本增量	`delta`
`output.thinking.delta`	思维链增量	`delta`
`output.thinking.status`	思考阶段	`status`：`thinking` 或 `done`

工具调用事件

事件	说明	关键字段
`tool_call.created`	模型决定调用工具（`status=pending`）	`tool_call_id`, `tool_name`, `parameters`
`tool_call.in_progress`	工具开始执行	`tool_call_id`, `tool_name`
`tool_call.completed`	工具执行结束。结果在 `tool_call.result`，不在这条事件上	`tool_call_id`, `tool_name`, `parameters`
`tool_call.failed`	工具执行失败	`tool_call_id`, `tool_name`, `parameters`
`tool_call.arguments.delta`	参数流式增量	`tool_call_id`, `tool_name`, `args_chunk`, `index`
`tool_call.result`	工具返回值	`tool_call_id`, `tool_name`, `result`, `is_error`
`tool_call.denied`	权限门拒绝，工具没有执行	`tool_call_id`, `tool_name`, `layer`, `reason`
`approval.required`	需要人工回答才能继续。用 `tool_confirmations` 续跑	`tool_call_id`, `questions`, `title`

用量事件

事件	说明	关键字段
`usage.token`	本轮 token 用量，计费以这条为准	`prompt_tokens`, `completion_tokens`, `total_tokens`
`usage.budget_exhausted`	预算耗尽，运行终止	`total_tokens_used`, `token_budget`
`usage.trial_exhausted`	试用次数耗尽	内部字段原样透出

流式解析示例

from profy import Profy

async with Profy(api_key="sk-pro-your-key") as client:
    async for chunk in client.agents.run_stream("my-expert", "你好"):
        match chunk.type:
            case "run.in_progress":
                print(f"会话: {chunk.raw.get('session_id')}")
            case "output.text.delta":
                print(chunk.delta, end="", flush=True)
            case "tool_call.created":
                print(f"\n调用工具: {chunk.raw.get('tool_name')}")
            case "run.completed":
                print("\n--- 完成 ---")
            case "run.failed":
                print(f"\n错误: {chunk.raw.get('error')}")

import { Profy } from "@profy-ai/sdk";

const client = new Profy({ apiKey: "sk-pro-your-key" });

for await (const chunk of client.agents.runStream("my-expert", "你好")) {
  switch (chunk.type) {
    case "run.in_progress":
      console.log(`会话: ${chunk.raw.session_id}`);
      break;
    case "output.text.delta":
      process.stdout.write(chunk.delta ?? "");
      break;
    case "tool_call.created":
      console.log(`\n调用工具: ${chunk.raw.tool_name}`);
      break;
    case "run.completed":
      console.log("\n--- 完成 ---");
      break;
  }
}

curl -N -X POST https://api.profy.cn/v1/agents/run \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "X-Profy-End-User-Id: user-123" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"agent":"my-expert","input":"你好","stream":true}'

计费

按 token 用量计费（计费单位 token_split），积分从 API Key 所属账户扣除，而不是从 X-Profy-End-User-Id 指定的终端用户扣除——终端用户 ID 只用于会话隔离与用量归因，不是计费主体。计算方式：ceil(输入tokens × 输入费率 ÷ 1e6) + ceil(输出tokens × 输出费率 ÷ 1e6)（输入与输出分别取整后相加）。各模型的费率是运营数据，以模型选择器 / 模型列表接口的当前值为准；算法固定，完整说明见计费公式。本次调用的实际消耗从 usage.token 事件读取——这是权威值，不要用自己的 tokenizer 估算后当账单用。

错误码

HTTP 状态码	说明
`400`	请求参数缺失或无效
`401`	认证失败（API Key 无效或 Token 过期）
`403`	专家访问被拒绝（未购买或试用次数耗尽）
`404`	`attachment_file_ids` 中有 ID 不存在或不属于你
`500`	内部错误。响应体是 `{ code, message, data: null }`
`502`	智能体运行时上游错误
`503`	连不上智能体运行时
`504`	智能体运行时超时

下一步

上传文件

把文件交给专家读取

对话补全

OpenAI 兼容的对话补全接口

Python SDK

Python SDK 完整指南

开始使用

认证与密钥

API 能力指南

SDK

集成

Cookbook

参考

认证

请求体

请求示例

响应格式

SSE 事件类型

生命周期事件

输出事件

工具调用事件

用量事件

流式解析示例

计费

错误码

下一步

上传文件

对话补全

Python SDK

​认证

​请求体

​请求示例

​响应格式

​SSE 事件类型

​生命周期事件

​输出事件

​工具调用事件

​用量事件

​流式解析示例

​计费

​错误码

​下一步

上传文件

对话补全

Python SDK

认证

请求体

请求示例

响应格式

SSE 事件类型

生命周期事件

输出事件

工具调用事件

用量事件

流式解析示例

计费

错误码

下一步