计划资格：适用于 Advanced、Enterprise 和部分 Legacy 计划. 测试对所有用户可用，但发布需符合计划资格.

“Make HTTP requests” 操作允许您的 AI 代理在对话中调用外部 API. 这可让 AI 代理根据联系人的请求检索实时数据或触发外部系统中的操作. 例如，它可以查询订单状态、检索账户信息或在其他系统中创建记录. 在本文中，您将了解如何配置 HTTP 请求操作并在 AI 代理中进行测试.

AI 代理:

分析联系人的消息，以判断其是否符合您在操作说明中定义的意图.
收集任何所需信息.
发送 HTTP 请求.
解析 API 响应.
以自然的方式回复联系人.

添加 Make HTTP requests 操作

开启该操作并点击“Add action”按钮以开始配置您的 HTTP 请求.

定义操作执行时机

在 Action name 字段中为该操作输入描述性名称.

在 When and how should this action be performed? 字段中，描述：

AI 代理何时应使用此操作
它将检索或发送的内容
需要处理的任何条件或结果

示例：

当联系人询问订单时，使用此操作检索其订单状态. 如果 API 返回 404 错误，请告知联系人找不到该订单.

AI 代理使用此描述来决定何时触发请求.

AI 代理可能需要的信息（可选）

在调用 API 之前，请在此部分定义所需输入.

这些是 AI 必须收集的结构化变量. 只有在所有必需输入可用后才会触发请求.

如果某个值：

已在对话中提到 → AI 会使用该值.
缺失 → AI 会向联系人询问.

在此创建的变量可用于 API 配置. 联系人变量（例如 $contact.email）会自动可用，无需手动添加.

字段设置

字段	说明
名称	在 API 请求中使用的变量标识符. - 每个操作唯一 - 仅限字母、数字和下划线 - 区分大小写 - 最多 30 个字符在引用时使用：$agent.variable_name 示例：$agent.order_id
格式	定义期望的数据类型： - 文本（默认） - 数字 - 布尔值 - 日期选择正确的格式以减少歧义并提高可靠性.
描述	解释该值代表的含义，并帮助 AI 清晰地提问。示例：来自确认邮件的 8 位订单 ID.
数组（可选）	启用此项以收集多个值而非单个值. 每个项都遵循所选格式。在预期出现以下情况时使用： - 多个产品 ID - 多个追踪编号 • 多项选择

API 配置

定义 AI 代理应如何调用您的 API.

您可以配置：

方法
URL
查询参数
请求头
JSON 正文（适用于 POST、PUT、PATCH）

引用变量

您可以使用 $ 在 URL、参数、请求头或正文中插入变量.

有两种类型：

联系人变量 — 现有的联系人字段
- $contact.email
AI 代理变量 — 在 AI 代理可能需要的信息 下定义的字段
- $agent.order_id

变量在请求运行时会被实际值替换. 如果缺少必需的 AI 代理变量，AI 将在触发 API 调用前询问该变量.

AI 如何处理 API 响应

示例正文：

{
  "order_id": "$agent.order_id",
  "email": "$contact.email"
}

AI 代理会自动解析 API 的 JSON 响应并生成自然回复.

示例 API 响应：

{
  "status": "shipped",
  "eta": "2025-12-12"
}

AI 回复：“好消息！您的订单已发货，预计将于 2025 年 12 月 12 日送达。”

测试

您可以在发布前在 Test AI Agent 面板中测试您的 HTTP 请求操作.

如何测试

开始一个符合操作条件的测试对话.
当检测到意图且所需输入可用时，AI 代理会执行 HTTP 请求.
执行事件会出现在测试面板中：
1. {AI Agent name} 已执行 {Action name}
2. 2xx 响应显示为成功
3. 所有其他状态码显示为失败
点击事件以查看：
1. Response 选项卡（默认）— 完整的 API 响应正文
2. Request 选项卡 — 完整的 cURL 请求负载
3. 用于调试的复制选项
在接收 API 响应后，AI 代理会根据返回的数据生成回复.

重要说明

执行事件仅出现在 测试 AI 代理 面板中. 它们不会出现在收件箱或联系人活动中.
如果缺少必需的输入，AI 代理会在触发请求前询问缺失的信息.

最佳实践

在操作描述中保持精确. 模糊的指令会导致模糊的触发条件.
清晰地定义必需输入. 如果 AI 必须询问某些信息，请明确提示.
在说明中处理错误情况.
始终在发布前进行测试.
避免重复实现已经由工作流程处理的逻辑，除非这是刻意设计的。

限制

每个 AI 代理最多 10 个 HTTP 请求操作.
每个操作的最大限制：
- 20 个数据输入字段
- 50 个参数
- 50 个请求头
AI 代理会根据您书面的描述确定何时调用 API. 书写不当的说明可能导致意外触发.
API 响应处理是自动的. 无法手动映射响应字段 — AI 会根据上下文解释 JSON.
HTTP 请求执行事件仅出现在测试 AI 代理面板中，不会出现在联系人活动中。
语音 AI 代理可以触发 Make HTTP requests 操作. 但是，返回的 API 响应不会传回给语音 AI 代理用于生成回复，这意味着语音对话无法根据 API 结果动态响应.

常见问题与故障排除

我可以触发多个 API 端点吗？

是的. 您可以为每个 AI 代理配置最多 10 个独立的 HTTP 请求操作.

我可以将联系人数据传入 API 吗？

是的. 在 URL、请求头、参数或正文中使用 $contact.field_name.

如果缺少必需数据会怎样？

AI 代理会在触发请求前向联系人询问缺失信息.

AI 会等待 API 响应吗？

是的. AI 代理会等待响应、解析响应，并根据返回的数据自然回复.

AI 代理操作：Make HTTP requests