> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoke

> 通过公开 API 启动带回调交付的 Hive Agent 运行

当你的应用需要在 dashboard 之外启动 Hive Agent 运行时,使用公开 API。该 API 会异步启动运行,立即返回标识符,并在运行结束后发送已签名回调。

Hive Agent 调用不会流式返回,也不会在 HTTP 响应中等待最终答案。打开 [日志](./logs) 查看状态、追踪、成本、节点输出、部分结果、回调尝试和最终响应。

## Endpoint

```http theme={null}
POST /v1/stream/hive_agent/invoke
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 请求体

```json theme={null}
{
  "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`。

```json theme={null}
{
  "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 示例

```bash theme={null}
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`。

```json theme={null}
{
  "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](../workflows/async-and-webhooks) 了解验证流程。

## 查找结果

打开 **Hive Agents** > **Logs**,按 Hive Agent 名称、目标、状态或 request ID 搜索。打开运行后,可以查看节点工作、验证反馈、来源处理、预算事件、trace spans 和最终响应。

运行详情也会显示回调交付尝试和重试状态。此版本的 Hive Agent 公开调用不提供同步等待或 streaming 选项。