---
title: API 参考
summary: HeartBeatAgents REST API 完整参考：身份验证、调用智能体以及记忆相关端点。
date: 2026-09-11
---

# 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

```bash
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

```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

```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）

```bash
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!"}'
```

### 第二步：轮询结果

```bash
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 倍。

## 记忆相关端点

每个智能体都拥有自己的长期记忆，可在多次对话之间持续保留。底层模型请参见[核心概念](/zh/docs/guides/core-concepts)。

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

## 相关内容

- [核心概念](/zh/docs/guides/core-concepts)：智能体、对话和记忆作为独立于该 API 的概念
- [自托管](/zh/docs/guides/self-hosting)：将 `{YOUR_URL}` 暴露到你自己网络之外，以便 Webhook 和回调能够到达