> ## 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.

# 通过 API 运行

> 使用你的工作区 API 密钥、智能体 ID 和消息,通过公开 API 调用智能体

# 通过 API 运行

当你想从自己的应用或服务中向智能体发送消息时,请使用公开的智能体调用端点。在 Fetch Hive 中,你可以从 agents 侧边栏的 **More** -> **Get Code**,或从智能体编辑器中的 **Code Snippet** 复制请求结构。

## 身份验证

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

请参阅 [API Keys](../workspace/api-keys) 了解如何创建和管理密钥。

## 端点

`POST https://api.fetchhive.com/v1/agent/invoke`

如果你希望 Fetch Hive 为你生成 cURL 示例,请打开 **Agents**,然后使用 **More** -> **Get Code**。如果你已经在某个具体智能体的编辑器中,请改为点击 **Code Snippet**。

## 请求

使用以下请求结构:

| 字段            | 类型      | 必填 | 说明                                                                                                                                  |
| ------------- | ------- | -- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `agent`       | string  | 是  | 智能体 ID                                                                                                                              |
| `message`     | string  | 是  | 你想发送给智能体的消息                                                                                                                         |
| `streaming`   | boolean | 否  | 是否以事件流形式返回响应                                                                                                                        |
| `thread_id`   | string  | 否  | 标识会话线程的任意字符串。Fetch Hive 会在首次使用时创建一个新线程,并在后续使用相同值的调用中恢复该线程。                                                                          |
| `messages`    | array   | 否  | 调用方提供的先前对话回合。作为上下文使用,不会持久化到数据库。每一项格式为:`{ "content": string, "role": "user" \| "assistant" \| "system", "attachments"?: array }`。    |
| `attachments` | array   | 否  | 附加到当前 `message` 的 HTTPS 文件 URL。每一项可以是一个 URL 字符串,也可以是带有 `file_url` 的对象。受支持的文档文件按扩展名包括 CSV、XLSX、PDF、DOCX,以及 text/Markdown。也可以在此处传递图像。 |
| `metadata`    | object  | 否  | 由调用方定义的扁平元数据,用于审计和日志筛选。不会添加到智能体提示词中。                                                                                                |

`metadata` 必须是扁平且仅包含标量的:字符串、数字、布尔值或 `null`。嵌套对象和数组会在运行开始前返回校验错误。

`attachments` 项可以是简单的 URL 字符串:

```json theme={null}
[
  "https://example.com/customer-brief.pdf",
  "https://uploads.fetchhive.com/uploads/grme67114iieusl54m3u4swipr3v"
]
```

当你想提供元数据时,也可以使用以下对象形式:

```json theme={null}
{
  "file_url": "https://example.com/customer-brief.pdf",
  "file_name": "customer-brief.pdf",
  "file_type": "application/pdf"
}
```

仅接受 `https://` URL。每条消息最多允许 5 个附件,按 `attachments` 计数。文档附件会通过系统的 `read_file` 工具以 `<available_files>` 清单形式向智能体公开;智能体会在依赖文档内容之前调用 `read_file`。如果附件 URL 或类型无效,Fetch Hive 会返回 `422` 校验错误,而不会打开流。该错误使用标准的 `error_code`、`error` 和 `message` 字段;`error` 和 `message` 会在可用时按已认证账户的语言进行本地化。

支持的文档附件:

* CSV:`text/csv`、`.csv`
* XLSX:`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`、`.xlsx`
* PDF:`application/pdf`、`.pdf`
* DOCX:`application/vnd.openxmlformats-officedocument.wordprocessingml.document`、`.docx`
* 按扩展名识别的 Text 和 Markdown:`.txt`、`.md`、`.markdown`

对于没有扩展名的 URL,例如 Fetch Hive 媒体库 URL,直接传递该 URL。Fetch Hive 会将该 URL 添加到 `read_file` 的允许列表中,文件工具会在抓取文件时检测其实际类型。

应用内的代码片段展示的是相同的请求体结构:

```json theme={null}
{
  "agent": "AGENT_UUID",
  "message": "Your message here",
  "streaming": true,
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise"
  }
}
```

## 基本示例

```bash theme={null}
curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "Summarize the latest AI infrastructure trends",
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    },
    "attachments": [
      "https://example.com/customer-brief.pdf"
    ],
    "streaming": true
  }' \
  --compressed
```

这与产品中显示的 cURL 代码片段一致。当前的调用对话框显示 **cURL**,而 **Python** 和 **TypeScript** 仍显示 **Coming Soon**。

将 `metadata` 用于希望在日志中查看或筛选的审计字段,例如客户 ID、套餐名称、地区或实验名称。它会与运行一起存储,并在日志中的 **User metadata** 下显示。请参阅[调用元数据](../user-tracking/invoke-metadata)了解示例和日志筛选详情。

## 响应

如果 `streaming` 为 `true`,该路由会返回事件流,而不是一个最终的 JSON 对象。如果在流打开后提供商出现故障,该路由会在关闭流之前发送一个最终的 `error` 事件。如果客户端先断开连接,Fetch Hive 会将其视为静默取消,不会创建失败的智能体运行、计费用量或报告提供商错误事件,除非提供商已经完成并提交了用量。

### 流式响应

流可能包含一个 summary 事件、reasoning 数据块、response 数据块、tool 事件、最终的 usage 事件或一个 error 事件。当所有成功事件都存在时,事件按以下顺序到达:`summary` → `reasoning` → `response` → `tool` → `usage`。如果提供商在流过程中失败,可能会收到 `error` 事件而非 `usage` 事件。

Summary 事件(仅在启用自动摘要的线程上发出):

```json theme={null}
{
  "type": "summary",
  "summary_text": "The conversation covered AI infrastructure trends. The user asked about evals and tool routing...",
  "original_token_count": 15234,
  "context_limit": 200000,
  "model": "gpt-4.1",
  "provider": "openai"
}
```

当累计的线程历史超过自动摘要阈值时,此事件在流开始时触发。它表示先前的对话在发送给模型之前已被压缩为摘要——智能体保留了上下文,但原始历史已被压缩。`original_token_count` 是压缩前的 token 数量;`context_limit` 是模型的总上下文窗口。你可以将其展示给用户作为 "conversation summarized" 提示,也可以忽略它——无论如何,你的应用行为都不会受到影响。

Reasoning 事件:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "reasoning",
  "response": "Looking at the latest model releases..."
}
```

Response 事件:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "response",
  "response": "Teams are standardizing around evals, routing, and observability.",
  "done": false
}
```

Tool 事件:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "tool",
  "tool_id": "tool_123",
  "tool": "google_search",
  "tool_input": {
    "query": "latest AI infrastructure trends 2026"
  },
  "observation": {
    "results": []
  }
}
```

最终 usage 事件:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "usage",
  "usage": {
    "duration": 4.79230260848999,
    "input_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "output_tokens": {
      "total_tokens": 170,
      "reasoning_tokens": 64
    },
    "total_tokens": 194
  },
  "stop_reason": "completed"
}
```

Error 事件:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "error",
  "id": "msg_019d52846ea37682b03522fd0695cc43",
  "error": "openai provider stream error: HTTP 400: invalid request",
  "message": "openai provider stream error: HTTP 400: invalid request",
  "provider": "openai",
  "error_type": "provider_stream_error",
  "status_code": 502
}
```

### 非流式响应

如果 `streaming` 为 `false`,该路由会返回单个 JSON 响应,其中包含生成的输出、使用数据,以及可用于在 **Logs** 中检查该运行的请求 ID。提供商执行失败会返回 `502 Bad Gateway` 和 `error` 消息。

确切的输出字段可能因提供商而异,但响应包含你需要的运行元数据。例如:

```json theme={null}
{
  "request_id": "req_019d528660dd7e22b15e5b13a1931c50",
  "model": "gpt-5-nano-2025-08-07",
  "duration": 4.641960144042969,
  "response": "Teams are moving from simple wrappers to systems with evals, tool routing, and tighter cost controls.",
  "reasoning": "The request asks for a short summary of current infrastructure trends.",
  "usage": {
    "input_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "output_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}
```

如果智能体使用了工具,非流式响应中还可以包含工具执行详情。

## 多轮对话

调用端点支持两种多轮对话方式。

### 持久化线程(由 Fetch Hive 管理历史)

传入 `thread_id`——你选择的任意字符串——Fetch Hive 会在首次调用时自动创建该线程,并在每次使用相同值的后续调用中恢复该线程。消息历史存储在 Fetch Hive 中,并自动包含在上下文中。

```bash theme={null}
# First turn
curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "What are the main AI infrastructure trends right now?",
    "streaming": true,
    "thread_id": "user-456-support-session"
  }'

# Second turn — same thread_id resumes the conversation
curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "Which of those trends have the most enterprise adoption?",
    "streaming": true,
    "thread_id": "user-456-support-session"
  }'
```

你可以使用任意字符串作为 `thread_id`——用户 ID、会话 ID、工单号或对你的用例有意义的任何其他标识符。

### 无状态历史(由调用方管理历史)

如果你更愿意自行管理对话状态,请在 `messages` 数组中传入先前的回合。Fetch Hive 会将提供的历史用作上下文,但不会持久化。

```bash theme={null}
curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "Which of those trends have the most enterprise adoption?",
    "streaming": true,
    "messages": [
      {
        "content": "What are the main AI infrastructure trends right now?",
        "role": "user",
        "attachments": [
          {
            "file_url": "https://example.com/market-data.csv",
            "file_name": "market-data.csv",
            "file_type": "text/csv"
          }
        ]
      },
      { "content": "Teams are focusing on evals, tool routing, and observability.", "role": "assistant" }
    ]
  }'
```

如果先前的助手回合生成了一个文件,请通过 `messages[].attachments` 在相关的历史消息上将该文件传回。Fetch Hive 使用当前和历史消息中结构化的附件 URL 来附加面向提供商的 `read_file` 工具,并为后续回合授权访问;仅在纯文本中提到的 URL 不会被视为文件工具附件。

当你已经在自行维护聊天状态、并且不需要 Fetch Hive 存储对话历史时,使用 `messages`。

## 下一步

* [日志](./logs)
* [使用聊天测试](./testing-with-chat)
* [使用 Python SDK 运行](./run-with-python-sdk)
* [使用 Node.js SDK 运行](./run-with-nodejs-sdk)
* [使用 Ruby SDK 运行](./run-with-ruby-sdk)
* [使用 PHP SDK 运行](./run-with-php-sdk)