调用智能体
POST /v1/agent/invoke
从你自己的应用或服务向智能体发送一条消息。
身份验证
在Authorization 请求头中发送工作区 API 密钥。
请求体
在编辑器中打开智能体并点击 Code Snippet，可以在 Fetch Hive 中查看当前的公开请求结构。Webhook 触发器
POST /v1/agent/webhooks/{agent_id}
当外部服务需要在不使用工作区 API 密钥的情况下启动智能体运行时，使用智能体 webhook 触发器。请求必须在 X-Fetch-Hive-Webhook-Secret 中包含智能体 webhook 密钥。如果第三方工具无法设置自定义请求头，可以退而使用 ?secret=YOUR_WEBHOOK_SECRET。
智能体 webhook 触发器始终使用回调投递。包含 async.callback_url；Fetch Hive 返回 202，带有 request_id 和 run_status: "running"，随后向回调 URL 投递 agent.completed、agent.failed 或 agent.awaiting_approval。
message 是必填项。thread_id 可选，可以重复使用以恢复由调用方管理的线程。metadata 遵循与普通智能体调用相同的扁平且仅含标量的规则，并会出现在日志筛选中。
在 webhook 请求体中加入 response_format 即可获得 JSON。它与调用接口上的 JSON 输出 字段是同一个对象，仅对本次调用生效。省略时，回调返回文本。
agent.completed 中的 data.response 仍是 JSON 文本，并新增 data.output_json，即解析后的对象。agent.awaiting_approval 和 agent.failed 不会包含 output_json。
agent.failed，错误信息在 data.error 中。
Fetch Hive 使用与入站触发器认证相同的 webhook 密钥对出站回调进行签名。
回调 data 在 agent.completed 时包含 response，在 agent.failed 时包含 error；使用顶层的 event_type 和 request_id 来表示终态和关联。agent.awaiting_approval 包含 pending_tool_approvals 和控制台 review_url。审批后继续的运行，其后续 agent.completed 会包含 resumed_from_run_id。参见工具审批。
metadata 必须是扁平对象。键必须是非空字符串,值必须是字符串、数字、布尔值或 null。数组和嵌套对象会在运行启动前被拒绝。
attachments 项可以是简单的 URL 字符串：
https:// URL。每条消息最多允许五个附件。文档附件通过系统 read_file 工具以 <available_files> 清单的形式暴露给智能体；智能体在依赖文档内容前会先调用 read_file。如果附件 URL 或类型无效,Fetch Hive 会返回 422 Unprocessable Entity,而不会打开流。
受支持的文档附件：
- CSV:
text/csv,.csv - XLSX:
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,.xlsx - PDF:
application/pdf,.pdf - DOCX:
application/vnd.openxmlformats-officedocument.wordprocessingml.document,.docx - 按扩展名识别的文本和 Markdown:
.txt,.md,.markdown
read_file 的允许名单,文件工具在抓取文件时会检测真实类型。
有效示例：
thread_id 进行持久会话时：
messages 进行由调用方管理的（无状态）历史时：
messages[].attachments 在相应的历史消息中将该文件传回。Fetch Hive 使用当前消息和历史消息中结构化的附件 URL 来为后续轮次授权 read_file 访问；仅在纯文本中提到的 URL 不会被视为文件工具附件。
单次调用的自动批准
只有当工作区所有者或管理员在“设置 → API 密钥”中打开“允许此密钥自动批准操作”后，使用该 API 密钥的请求才能发送tool_approval: "auto_approve"。这次调用不会更改代理已保存的设置，也不会写入策略。
没有该权限的密钥、已登录编辑器的令牌，以及 webhook，都会在任何模型调用、预检或计费之前返回 403：
error_code，消息为 Auto-approve is not available for this workspace.
破坏性操作仍然会询问。拒绝规则仍然会阻止操作。这次调用启动的子代理会收到相同的 tool_approval 和同一把 API 密钥。代理启动的工作流不会继承该字段。
成功响应会回显 tool_approval，值为 auto_approve 或 policy。如果某个操作因为例外而执行，响应还会包含 auto_approved_tool_calls：[{ "summary": string, "tool_name": string }]。流式调用把这两个字段放在最终的 usage 事件上。
JSON 输出
response_format 属于这一次调用。省略它时，代理返回文本。发送 schema 时，同一个代理返回 JSON。
type 为 json_schema 或 text。schema 根必须是对象。文档不超过 100000 字节。省略 strict 或设为 true 时，每个对象节点会带上 additionalProperties: false。strict: false 会保留你发送的 schema。
旧客户端可以改发 is_json_schema_response_format: true 和 json_schema。两种都出现时，以 response_format 为准。
模型不支持 JSON Schema 时，调用在开始前返回 422 json_schema_unsupported。schema 不是对象，或超过 100000 字节时，返回 422 json_schema_invalid。
schema 只约束最终回答。工具调用照常进行。若回答不符合 schema，Fetch Hive 会再要一次回答。再次失败返回 422 json_schema_output_invalid。线程里保存的消息是 JSON 文本。
非流式响应的 response 仍是该 JSON 文本，并附加解析后的对象 output_json。流式调用仍按今天的方式发送文本增量。最后的 usage 事件包含 output_json。若修复改写了已流出的文本，以 output_json 为准。
response_format 同样适用于智能体 webhook 触发器。此时回调的 agent.completed 会包含 output_json。
响应
如果streaming 为 true，Fetch Hive 返回事件流。如果在流打开后提供商失败,Fetch Hive 会在关闭流前发送一个最终的 error 事件。如果客户端先断开连接,Fetch Hive 会将其视为静默取消,不会创建失败的智能体运行、计费用量或报告提供商错误事件,除非提供商已经完成并提交了用量。
推理事件示例：
status 和 run_id 始终存在。thread_id 是你发送的值，或为 null。仅当 status 为 awaiting_approval 时才包含 pending_tool_approvals。仅当本轮有策略拒绝时才包含 denied_tool_calls。stop_reason 保持提供商的值。参见工具审批。
错误事件示例：
streaming 为 false，Fetch Hive 返回一条 JSON 响应。提供商执行失败时返回 502 Bad Gateway，带有 error 消息。
pending_tool_approvals 形状，并且 response 文本包含 [Waiting for approval: …]。