Invoke

当你的应用需要在 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",
  "search_location_country": "US",
  "unattended": true,
  "budget_policy": "stop",
  "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 能创建有用的工作节点。 search_location_country 为可选项,默认 US。传入 ISO 3166-1 alpha-2 国家/地区代码可为本次运行本地化网络搜索工具。 unattended 为可选项,默认 false。Dashboard 的 Start Run 始终为有人值守。当代码或 API 运行无人看守时,将 unattended 设为 true。无人值守运行不会因澄清或预算审批而暂停:目标含糊时 planner 会选择默认解释,这些选择会显示为 Assumptions made。如果花费本应需要审批,运行会失败而不是等待。 budget_policy 仅在 unattended 为 true 时生效。stop（默认）会在花费需要审批时使运行失败,失败码为 budget_exceeded。proceed_to_cap 会越过 budget hint,仍在 hard cap 处停止。有人值守运行请省略 budget_policy。 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",
    "unattended": true,
    "budget_policy": "stop",
    "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 选项。

Fetch Hive API

REST API

Endpoint

请求体

响应

cURL 示例

回调 payload

查找结果

​Endpoint

​请求体

​响应

​cURL 示例

​回调 payload

​查找结果

Endpoint

请求体

响应

cURL 示例

回调 payload

查找结果