通过 API 运行

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

身份验证

Authorization: Bearer YOUR_API_KEY

请参阅 API Keys 了解如何创建和管理密钥。

端点

POST https://api.fetchhive.com/v1/agent/invoke 如果你希望 Fetch Hive 为你生成 cURL 示例,请打开 Agents,然后使用 More -> Get Code。如果你已经在某个具体智能体的编辑器中,请改为点击编辑器控制栏中的 Get Code。

请求

使用以下请求结构:

字段	类型	必填	说明
`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 字符串:

[
  "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 计数。文档附件会通过系统的 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 事件。如果客户端先断开连接,Fetch Hive 会将其视为静默取消,不会创建失败的智能体运行、计费用量或报告提供商错误事件,除非提供商已经完成并提交了用量。

流式响应

流可能包含一个 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,
      "cached_read_tokens": 0,
      "cache_write_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,
      "cached_read_tokens": 0,
      "cache_write_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。

下一步

工件引用

对于调用方管理的会话，可在 known_artifact_refs 中发送最多 50 个属于当前账户或工作区的 Asset UUID。当前轮次选中的 UUID 放入 artifact_refs；attachments 与 artifact_refs 合计最多五项。每个活动引用也必须包含在 known_artifact_refs 中。持久线程从已保存的对话中获取工件。外部文档和图片 URL 继续使用 attachments；不支持外部音频。流式响应可发送 artifact 事件，非流式响应包含 artifacts。

快速开始

Live Chat

提示词

工作流

Hive Agents

智能体

知识库

实验

您的工作区

监控

用户跟踪

资源

通过 API 运行

通过 API 运行

身份验证

端点

请求

基本示例

响应

流式响应

非流式响应

多轮对话

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

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

下一步

工件引用

​通过 API 运行

​身份验证

​端点

​请求

​基本示例

​响应

​流式响应

​非流式响应

​多轮对话

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

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

​下一步

​工件引用

通过 API 运行

身份验证

端点

请求

基本示例

响应

流式响应

非流式响应

多轮对话

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

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

下一步

工件引用