跳转到主要内容
当你的应用需要在 dashboard 之外启动 Hive Agent 运行时,使用公开 API。该 API 会异步启动运行,立即返回标识符,并在运行结束后发送已签名回调。 Hive Agent 调用不会流式返回,也不会在 HTTP 响应中等待最终答案。打开 日志 查看状态、追踪、成本、节点输出、部分结果、回调尝试和最终响应。

​
Endpoint

POST /v1/stream/hive_agent/invoke
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

​
请求体

{
  "hive_agent": "agent_task_uuid",
  "objective": "Research competitors and summarize verified findings",
  "sources": {
    "website_urls": [],
    "asset_ids": [],
    "knowledge_base_ids": [],
    "knowledge_base_item_ids": []
  },
  "metadata": {},
  "async": {
    "enabled": true,
    "callback_url": "https://example.com/hive-agent-callback"
  }
}
hive_agent 是 dashboard 中的 Hive Agent ID。API key 必须属于与该 Hive Agent 相同的 workspace。只有通过此 endpoint 调用你在工作区中创建的客户 Hive Agent。 objective 应足够具体,让 planner 能创建有用的工作节点。 sources 是可选项,但当运行需要可靠上下文时建议提供。可以传入已存在于 workspace 中的网站 URL、asset ID、knowledge base ID 或 knowledge base item ID。 使用 GET /v1/public/workspaces/{workspace_id}/knowledge_bases 列出 knowledge bases,使用 GET /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/items 列出 items,使用 GET /v1/public/workspaces/{workspace_id}/assets 列出 assets。先用 POST /v1/public/workspaces/{workspace_id}/assets 上传文件,再把返回的 asset.id 传入 sources.asset_ids。 metadata 是可选的调用方元数据,用于你自己的关联,例如 customer ID 或 job ID。 async.callback_url 是必填项。运行完成、失败或取消后,Fetch Hive 会把终态回调发送到这个 HTTPS URL。async.enabled 必须为 true。

​
响应

当运行已排队等待执行时,Fetch Hive 返回 202 Accepted。 
{
  "run_id": "agent_task_run_uuid",
  "request_id": "req_018c9f8ea1b2c3d4e5f6g7h8i9j0k1l2",
  "status": "pending",
  "webhook_secret": "whsec_..."
}
如果之后需要在 logs 中找到该运行,请保存 request_id。请保存 webhook_secret,用于在回调接收端验证 X-Fetch-Hive-Signature。初始状态通常是 pending; runtime 会在来源准备、计划、执行、验证和编写过程中更新状态。

​
cURL 示例

curl https://api.fetchhive.com/v1/stream/hive_agent/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hive_agent": "agent_task_uuid",
    "objective": "Research competitors and summarize verified findings",
    "sources": {
      "website_urls": ["https://example.com"],
      "asset_ids": [],
      "knowledge_base_ids": [],
      "knowledge_base_item_ids": []
    },
    "metadata": {
      "customer_id": "cus_123"
    },
    "async": {
      "enabled": true,
      "callback_url": "https://example.com/hive-agent-callback"
    }
  }'

​
回调 payload

当运行进入终态时,Fetch Hive 会向 async.callback_url 发送已签名 JSON payload。event_type 为 hive_agent.completed、hive_agent.failed 或 hive_agent.cancelled。 
{
  "event_type": "hive_agent.completed",
  "request_id": "req_018c9f8ea1b2c3d4e5f6g7h8i9j0k1l2",
  "data": {
    "run_id": "agent_task_run_uuid",
    "hive_agent_id": "agent_task_uuid",
    "hive_agent_name": "Competitor Research",
    "status": "completed",
    "success": true,
    "objective": "Research competitors and summarize verified findings",
    "final_response": {},
    "error_message": null,
    "metadata": {
      "customer_id": "cus_123"
    },
    "sources": []
  }
}
回调使用与其他 Fetch Hive 出站 webhook 相同的签名 headers:X-Fetch-Hive-Signature、X-Fetch-Hive-Timestamp 和 X-Fetch-Hive-Webhook-Id。请参阅 Callback Delivery and Webhook Triggers 了解验证流程。

​
查找结果

打开 Hive Agents > Logs,按 Hive Agent 名称、目标、状态或 request ID 搜索。打开运行后,可以查看节点工作、验证反馈、来源处理、预算事件、trace spans 和最终响应。 运行详情也会显示回调交付尝试和重试状态。此版本的 Hive Agent 公开调用不提供同步等待或 streaming 选项。