API 参考

HeartBeatAgents REST API 完整参考：身份验证、调用智能体以及记忆相关端点。

HeartBeatAgents API 允许你通过单一 HTTP 端点以编程方式调用任意智能体。每个智能体都拥有自己的端点 URL 和 API 密钥，可在智能体设置页面生成。该 API 可与任意 HTTP 客户端配合使用：cURL、Python、JavaScript、Zapier、Make、n8n，或你自己编写的代码。

端点 URL

每个智能体都有一个唯一的调用端点：

{YOUR_URL}/api/v1/agents/{AGENT_ID}/invoke

身份验证

所有请求都需要以 Bearer 令牌的形式传递 API 密钥，该密钥可在智能体设置页面的 Agent API 部分生成。

Authorization: Bearer hb_agent_YOUR_KEY

API 密钥的作用范围限定于单个智能体。每个智能体可以拥有多个有效密钥，因此你可以在不中断服务的情况下轮换凭证。一旦密钥泄露，请立即在智能体设置页面将其吊销。

调用智能体（同步）

设置 wait: true 可在一次调用中获取智能体的回复。该请求会阻塞，直到智能体处理完成。

cURL

curl -X POST {YOUR_URL}/api/v1/agents/{AGENT_ID}/invoke \
  -H "Authorization: Bearer hb_agent_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello agent!", "wait": true}'

Python

import requests

response = requests.post(
    "{YOUR_URL}/api/v1/agents/{AGENT_ID}/invoke",
    headers={"Authorization": "Bearer hb_agent_YOUR_KEY"},
    json={"message": "Hello agent!", "wait": True},
    timeout=300,
)
print(response.json()["response"])

JavaScript

const response = await fetch(
  "{YOUR_URL}/api/v1/agents/{AGENT_ID}/invoke",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hb_agent_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message: "Hello agent!", wait: true }),
  }
);
const { status, response: reply } = await response.json();
console.log(reply);

调用智能体（异步：发起并轮询）

省略 wait 或将其设置为 false 即可进行非阻塞调用。调用会立即返回 202 状态码和一个对话 ID。

第一步：发起调用（立即返回 202）

curl -X POST {YOUR_URL}/api/v1/agents/{AGENT_ID}/invoke \
  -H "Authorization: Bearer hb_agent_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello agent!"}'

第二步：轮询结果

curl {YOUR_URL}/api/v1/agents/{AGENT_ID}/invoke/{CONVERSATION_ID}/status \
  -H "Authorization: Bearer hb_agent_YOUR_KEY"

状态值： "pending" | "running" | "completed" | "failed"

请求体

message（字符串，必填）：发送给智能体的消息。
wait（布尔值，可选）：设置为 true 以启用同步模式。默认值为 false（异步）。

可靠性设置

三个开关，均位于设置 → Invoke API 下，都会在下一次请求时立即生效，无需重启：

幂等重试：开启后，调用方可以在 POST /invoke 请求中传入 Idempotency-Key 头。使用相同密钥的重试会返回最初那次调度的结果，而不会再触发一次新的运行；这对任何自带重试策略的 HTTP 自动化工具（n8n、Zapier、Make）都很重要。
Webhook 投递：开启后，POST /invoke 会接受一个 callback_url 字段。任务完成时，平台会向该 URL 发送一个已签名的 JSON 请求体，并在 X-HBA-Signature 头中附带可供验证的 HMAC-SHA256 签名。关闭该开关会强制所有调用方转为使用轮询 API。
Retry-After 提示：开启后，异步 202 响应，以及仍在运行的智能体的 /status 响应，都会带有 Retry-After 响应头和对应的 JSON 字段，遵循该提示的客户端会自动退避，而不是按固定间隔轮询。在长时间运行的智能体上，这能将 /status 轮询负载降低约 30 倍。

记忆相关端点

每个智能体都拥有自己的长期记忆，可在多次对话之间持续保留。底层模型请参见核心概念。

GET /agents/:id/memory

搜索某个智能体的记忆。支持按记忆类型过滤，并可通过 query 参数进行语义搜索。

GET {YOUR_URL}/api/v1/agents/{AGENT_ID}/memory?type=semantic&query=customer+preferences&limit=5
Authorization: Bearer hb_agent_YOUR_KEY

// 响应 200
{
  "data": [
    {
      "id": "mem_001",
      "type": "semantic",
      "content": "Customer prefers email communication over Slack",
      "confidence": 0.92,
      "source_conversation": "conv_xyz789",
      "created_at": "2026-02-08T09:00:00Z"
    }
  ],
  "total": 1
}

DELETE /agents/:id/memory/:memoryId

删除某条特定的记忆记录。

DELETE {YOUR_URL}/api/v1/agents/{AGENT_ID}/memory/mem_001
Authorization: Bearer hb_agent_YOUR_KEY

// 响应 204 No Content