通过 API 运行

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

身份验证

Authorization: Bearer YOUR_API_KEY

请参阅 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, "image_urls"?: array }`。
`attachments`	array	否	附加到当前 `message` 的 HTTPS 文件 URL。每一项可以是一个 URL 字符串,也可以是带有 `file_url` 的对象。受支持的文档文件按扩展名包括 CSV、XLSX、PDF、DOCX,以及 text/Markdown。也可以在此处传递图像。
`image_urls`	array	否	当前 `message` 上 HTTPS 图像附件的向后兼容简写。用于仅图像的集成,尤其是图像 URL 没有扩展名时。
`metadata`	object	否	由调用方定义的扁平元数据,用于审计和日志筛选。不会添加到智能体提示词中。

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

[
  "https://example.com/customer-brief.pdf",
  "https://uploads.fetchhive.com/uploads/grme67114iieusl54m3u4swipr3v"
]

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

{
  "file_url": "https://example.com/customer-brief.pdf",
  "file_name": "customer-brief.pdf",
  "file_type": "application/pdf"
}

仅接受 https:// URL。每条消息最多允许 5 个附件,attachments 和 image_urls 合并计算。文档附件会通过系统的 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 的允许列表中,文件工具会在抓取文件时检测其实际类型。应用内的代码片段展示的是相同的请求体结构:

{
  "agent": "AGENT_UUID",
  "message": "Your message here",
  "streaming": true,
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise"
  }
}

基本示例

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 下显示。请参阅调用元数据了解示例和日志筛选详情。

响应

如果 streaming 为 true,该路由会返回事件流,而不是一个最终的 JSON 对象。如果在流打开后提供商出现故障,该路由会在关闭流之前发送一个最终的 error 事件。

流式响应

流可能包含一个 summary 事件、reasoning 数据块、response 数据块、tool 事件、最终的 usage 事件或一个 error 事件。当所有成功事件都存在时,事件按以下顺序到达:summary → reasoning → response → tool → usage。如果提供商在流过程中失败,可能会收到 error 事件而非 usage 事件。 Summary 事件(仅在启用自动摘要的线程上发出):

{
  "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 事件:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "reasoning",
  "response": "Looking at the latest model releases..."
}

Response 事件:

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

Tool 事件:

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

最终 usage 事件:

{
  "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 事件:

{
  "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 消息。确切的输出字段可能因提供商而异,但响应包含你需要的运行元数据。例如:

{
  "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 中,并自动包含在上下文中。

# 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 会将提供的历史用作上下文,但不会持久化。

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。

​通过 API 运行

​身份验证

​端点

​请求

​基本示例

​响应

​流式响应

​非流式响应

​多轮对话

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

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

​下一步