# AI 智能体 API

**AI 智能体 (AI Agent)** 是您机器人的大脑：它包含指令、个性、语言、知识和工具。您只需构建一次智能体，然后将流量指向它即可。本指南涵盖了您可以通过 API 对智能体执行的所有操作——创建、配置、赋予知识和工具、审查草稿以及将对话路由至智能体。

- **基础 URL** — `https://api.youraiconnector.com/v1`
- **身份验证** — 您的 API 密钥（请参阅 [身份验证](authentication.md)）
- **错误与分页** — 请参阅 [错误与分页](errors-and-pagination.md)

以下所有示例均展示了 cURL 中的 `?apiKey=` 查询形式，以及 JavaScript 和 Python 中的 `X-API-Key` 标头——两者均适用于所有端点。

如果您是第一次接触智能体概念，请先阅读 [AI 智能体](../ai-agents/ai-agents.md)。


---

## 智能体的组成部分

有四个部分是分开管理的，在开始之前了解它们各自的作用很有帮助：

| 组件 | 说明 | 设置位置 |
|---|---|---|
| **配置** | 指令、规则、目标、个性、语言、AI 等级、预约和跟进行为 | `PUT /agents/{agentId}` 或更具体的 `PUT /agents/{agentId}/bot-config` |
| **知识** | 常见问题解答 (FAQ) 和知识源（平台为您读取的页面和文档） | [FAQ API](faqs.md) 和 `POST /agents/{agentId}/kb-sources` |
| **工具** | 智能体在对话中可能调用的自定义函数和 MCP 服务器 | `POST /agents/{agentId}/custom-functions` 和 `POST /agents/{agentId}/mcp-servers` |
| **路由** | 哪些渠道和对话实际会触达此智能体 | 入口点 — `PUT /entry-points/channel-defaults` 和 `POST /agents/{agentId}/entry-points` |

> **在您路由到智能体之前，新智能体不会回答任何人。** 创建智能体并不会将其放置在任何渠道上。这是大多数集成容易忽略的一步——请参阅本页面末尾的 [将对话路由至智能体](#routing-conversations-to-an-agent)。

---

## 智能体对象

完整的智能体文档非常庞大——通常有几百 KB，主要包含其 FAQ 列表、知识源以及从您的网站读取的任何页面内容。因此，当您请求列表时，返回的是每个智能体的简短**摘要行**：

```json
{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}
```

| 字段 | 类型 | 描述 |
|---|---|---|
| `id` | string | 智能体的唯一标识符。 |
| `name` | string \| null | 智能体名称，显示在仪表板中。 |
| `active` | boolean \| null | 智能体当前是否被允许回复。 |
| `language` | string \| null | 智能体回复时使用的语言。 |
| `goal` | string \| null | 智能体的工作目标，缩短为前 200 个字符（末尾的省略号表示已被截断）。 |
| `tags` | array \| null | 智能体的标记规则。 |
| `anthropic_model` | string \| null | AI 质量等级：`standard`、`economy`、`max` 或 `mini`。 |
| `ai_speed` | string \| null | 智能体在回复前应用的推理程度：`fast`、`fast_thinker`、`balanced` 或 `thorough`。 |
| `enable_bookings` | boolean \| null | 智能体是否可以预约。 |
| `enable_follow_ups` | boolean \| null | 智能体是否发送跟进消息。 |
| `faq_refs_count` | integer | 此智能体知识库中的 FAQ 数量。 |
| `kb_source_refs_count` | integer | 链接到此智能体的知识源数量。 |
| `created_at` | integer \| null | 创建时间，纪元毫秒数。 |
| `last_modified_at` | integer \| null | 最后更改时间，纪元毫秒数。 |

完整文档添加了所有其他内容：`instructions`、`rules`、`personality`、`availability`、`follow_up_config`、链接的 FAQ 和知识源列表、生成的文本块以及任何运行状态（`tag_generation`、`optimize_run`）。

> 部分响应还包含 `substrate_campaign_id`。这是旧账户中保留的内部记录；您无需对其进行任何操作，在较新的账户中，它为 `null` 或不存在。

---

## 列出智能体

`GET /agents` — 账户中的每个智能体，按最新创建顺序排列。

此端点**不分页**。默认情况下，每个 Agent 都会返回其完整配置，这非常庞大：单个 Agent 可达 580 KB，拥有 64 个 Agent 的账户可超过 3 MB。传入 `view=summary` 可获取每个 Agent 的简短行，然后使用 [获取 Agent](#get-an-agent) 读取您需要的那个。

**查询参数**

| 参数 | 描述 |
|---|---|
| `view` | 设置为 `summary` 可获取简短行。任何其他值都会返回 `400`。省略此参数则返回完整文档。 |
| `fields` | 仅在与 `view=summary` 一起使用时生效。以逗号分隔的摘要键列表，例如 `id,name,active`。`id` 始终包含在内；未知的名称将被忽略。 |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]
```

**响应** (`200`)

```json
{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}
```

---

## 创建 Agent

`POST /agents` — 实际上只需要 `name`；随其发送您已知的任何配置。新 Agent 默认处于活动状态。

**请求字段**（除 `name` 外均为可选）

| 字段 | 类型 | 描述 |
|---|---|---|
| `name` | string | Agent 名称。 |
| `active` | boolean | 是否可以立即回复。默认为 `true`。 |
| `language` | string | Agent 回复所使用的语言。 |
| `instructions` | string | 指导其如何与联系人对话的主要指令。 |
| `rules` | string | 它必须始终遵守的硬性规则。 |
| `goal` | string | 它应努力实现的结果。 |
| `personality` | string | 语气和个性。 |
| `availability` | object | 每个工作日的活跃时间 — 请参阅 [设置活跃时间](#set-active-hours)。 |
| `ai_speed` | string | `fast`、`fast_thinker`、`balanced` 或 `thorough`。 |
| `anthropic_model` | string | `standard`、`economy`、`max` 或 `mini`。 |
| `scrape_urls` | string[] | 用于读取并构建 Agent 指令的页面。 |

**从您的网站构建 Agent。** 包含 `scrape_urls`，平台将读取这些页面并为您编写指令。响应会告知您该生成过程是否已开始，以便您了解是否需要轮询 Agent 以获取进度。

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);
```

**Python**

```python
res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])
```

**响应** (`201`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}
```

当平台开始根据您提供的页面编写指令时，`agent_generation_queued` 为 `true`。

`400` 表示主体不是 JSON 对象、字段被拒绝，或者 Agent 超过了您套餐允许的配置大小。`403` 表示账户不允许使用您发送的某项设置 — 例如其账户提供商未授予的 AI 层级。

---

## 获取 Agent

`GET /agents/{agentId}`

传入 `fields` 并附带以逗号分隔的列表，仅获取您需要的内容，例如 `fields=name,active,goal`。`id` 始终包含在内，Agent 上不存在的名称将被忽略，而不是被拒绝。省略此参数可获取完整文档。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]
```

如果 Agent 在您的账户中不存在，则返回 `404`。

---

## 更新 Agent

`PUT /agents/{agentId}` — 仅发送您想要更改的字段；其他所有内容保持不变。

嵌套设置可以使用点号键逐个叶子节点进行寻址，因此 `"availability.monday"` 只会更改周一的设置，而不会影响一周中其余的时间。

**注意**

- 若要更改 Agent 预订的可预订事件类型，请发送 `event_id`（事件的 ID，或使用 `null` 清除它）。发送带有数组的 `event_ids` 可同时链接多个事件——第一个将成为主要事件，而 `[]` 会取消所有链接。`event_id` 和 `event_ids` 是互斥的，且 `event` 字段本身不能直接写入。
- `enable_bookings` 必须是布尔值，`booking_provider` 必须是 `default`、`zenchef` 或 `formitable` 之一。
- 所有权和身份字段会被忽略，内部运行状态（生成和优化进度）也是如此。
- **此处不设置路由。** 请使用 `PUT /entry-points/channel-defaults` 将 Agent 设置为频道的应答者，使用 `POST /agents/{agentId}/entry-points` 设置关键字和评论规则，并使用 `PATCH /agents/{agentId}/active` 来暂停或恢复它。

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'
```

**JavaScript**

```javascript
await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});
```

**Python**

```python
requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)
```

**响应** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

空请求体将返回 `400` 以及 `"No fields to update"`。

---

## 更新机器人设置

`PUT /agents/{agentId}/bot-config` —— 仅更改对话设置的精简方式。

Agent 没有单独的机器人部分：其设置直接位于 Agent 上，因此这里的字段名称与您发送给 `PUT /agents/{agentId}` 的名称相同。此端点作为一种安全、专注的方式存在，用于更改其中的少数几个字段。至少需要一个字段。

| 字段 | 描述 |
|---|---|
| `instructions` | 指导 Agent 如何与联系人交谈的主要说明。 |
| `rules` | 它必须始终遵守的硬性规则。 |
| `goal` | 它在每次对话中应努力实现的结果。 |
| `personality` | 语气和个性描述。 |
| `language` | Agent 回复时使用的语言。 |
| `ai_speed` | `fast`、`fast_thinker`、`balanced` 或 `thorough`。 |
| `anthropic_model` | `standard`、`economy`、`max` 或 `mini`。 |
| `max_messages` | 每次对话中 Agent 的最大消息数。 |
| `alert_human_when` | Agent 何时应提醒人类团队成员。 |
| `ai_transparency` | Agent 是否披露其为人工智能。 |

> **此处的字段名称必须是普通名称** —— 字母、数字、下划线和连字符。此端点不接受点号路径（与 `PUT /agents/{agentId}` 不同），因此 `bot.goal` 会被拒绝并返回 `400`。

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'
```

长文本会占用您套餐允许的配置大小，因此非常大的指令集可能会被拒绝并返回 `400`。

---

## 设置活跃时间

`PUT /agents/{agentId}/active-hours` —— Agent 自动回复的时间段。在这些时间窗口之外，它将保持静默。

发送一个以工作日（`monday` 到 `sunday`）为键的 `availability` 对象。每一天接受单个时间窗口或时间窗口列表，格式为 24 小时制 `HH:MM`。您遗漏的天数将保留其原有设置，任何非工作日的键都会被拒绝——因此拼写错误不会导致静默失败。

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'
```

**响应** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

错误的工作日键会返回 `400`：`"Invalid availability keys: funday. Allowed keys: monday through sunday."`

---

## 暂停或恢复 Agent

`PATCH /agents/{agentId}/active` — 开启或关闭 Agent。暂停的 Agent 会保留其所有配置，但会立即停止回复；恢复后会立即生效。

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});
```

**响应** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }
```

`active` 必须是布尔值 — 任何其他值都会返回带有 `"active (boolean) is required"` 的 `400`。

---

## 复制 Agent

`POST /agents/{agentId}/duplicate` — 创建一个保留其配置的副本。在您为其指定通道或入口点（Entry Point）之前，该副本不会发送任何内容。

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"
```

**响应** (`201`)

```json
{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }
```

复制品会像从头创建一样计入您套餐的 Agent 配额，因此当账户达到上限时，系统会返回 `403` 并拒绝该操作。

---

## 删除 Agent

`DELETE /agents/{agentId}`

如果 Agent 仍连接在某些若移除后会导致功能停止的组件（如广播、入口点或旧账户中的营销活动）上，删除操作将被拒绝。响应会列出阻碍删除的组件，以便您先将其分离后再重试。

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"
```

**响应** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

**已阻止** (`409`)

```json
{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}
```

---

## 草稿：在生效前审查更改

在编辑器中所做的编辑，以及由 [使用 AI 优化](#optimize-an-agent-with-ai) 生成的任何重写内容，都会作为**未发布草稿**保留，直到您发布它们为止。在此之前，在线 Agent 将继续使用其当前配置进行回复。

### 发布草稿

`POST /agents/{agentId}/publish-draft` — 将草稿移至在线配置，并在同一步骤中清除草稿。

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"
```

**响应** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }
```

`published_keys` 会列出从草稿移动到在线 Agent 的设置，以便您查看更改内容。

> **在调用此接口前，请检查草稿是否存在。** 发布一个没有草稿的 Agent 是不支持的操作，目前会返回一个带有通用消息的 `500`，而不是具体的错误消息。若要丢弃草稿，请使用下方的 discard。

### 放弃草稿

`POST /agents/{agentId}/discard-draft` — 丢弃草稿并保持当前生效的配置不变。在没有草稿时调用是安全的；不会发生任何操作。

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"
```

---

## 使用 AI 优化智能体

`POST /agents/{agentId}/optimize` — 根据您的反馈（例如“它总是提供折扣”、“回答太长了”）重写智能体的配置，并将重写后的内容**保存为草稿**，而不是直接生效。

发送 `user_feedback`（简单的指令），或者在针对特定的错误回复进行反馈时，发送 `thumbs_down_feedback` 并附带相关的 `thumbs_down_message`。两者中至少有一个必须包含文本。

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'
```

**响应** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

该任务在后台运行，调用会立即返回。使用 `GET /agents/{agentId}` 读取智能体并观察 `optimize_run.status`；一旦状态变回 `Draft`，重写后的内容就会作为智能体的草稿等待处理。请审阅它，然后选择发布或放弃。

每个智能体同一时间只能运行一个任务 — 如果在任务进行中进行第二次调用，将返回 `409`。此操作会消耗 AI 点数。

---

## 标签规则

标签规则由一个标签及其适用场景的描述组成。在对话过程中，智能体会读取该描述，并在符合条件时为联系人打上标签，这就是触发标签驱动自动化的方式。

**规则对象**

| 字段 | 必填 | 描述 |
|---|---|---|
| `name` | 是 | 要应用的标签，例如 `hot-lead`。 |
| `description` | 否 | 智能体应何时应用该标签，以其遵循的指令形式编写。 |
| `webhook` | 否 | 智能体应用此标签时调用的 URL。 |
| `ai_can_remove` | 否 | 智能体是否也可以移除该标签。默认为 `false`。 |
| `tag_id` | 否 | 关联此规则的账户中现有标签的 ID。如果没有此 ID，规则将链接到同名标签，如果不存在则会创建一个 — 因此后续每个规则都可以通过标签 ID 进行寻址。 |

### 添加标签规则

`POST /agents/{agentId}/tags`

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'
```

**响应** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }
```

### 替换标签规则

`PUT /agents/{agentId}/tags/{tagId}` — 该规则通过路径中的标签 ID 找到并**整体替换**，而不是合并，因此请发送完整的规则，而不是仅发送您要更改的部分。它所指向的标签会被保留，即使您省略了 `tag_id`，因此编辑操作无法将规则与其标签分离。

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'
```

### 删除标签规则

`DELETE /agents/{agentId}/tags/{tagId}` — Agent 将停止应用该标签。标签本身以及任何已经带有该标签的联系人均不受影响。

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"
```

当 Agent 不存在**或**没有该标签的规则时，两个端点都会返回 `404`。

### 使用 AI 生成标签集

`POST /agents/{agentId}/tags/generate` — 通过读取 Agent 自身的指令和目标，设计出一整套规则（标签名称以及每个标签背后的“应用条件……”描述）。

| 字段 | 描述 |
|---|---|
| `mode` | `merge`（默认值）保留 Agent 上已有的规则并进行添加。`replace` 则从零开始设计整个集合。 |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'
```

**响应** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }
```

该工作在后台运行。请读取 Agent 并观察 `tag_generation.status`；规则本身会存入 Agent 的 `tags` 中。每个 Agent 一次只能运行一个任务（否则会返回 `409`），并且会消耗 AI 点数。

---

## 知识源

知识源是平台为您读取的页面和文档。将知识源附加到 Agent 后，它便能根据这些内容进行回答。

**源 ID 的来源。** 使用知识库端点添加内容 — `POST /kb-sources/url` 用于页面，`POST /kb-sources/file` 用于文档，`POST /kb-sources/bulk-import` 用于整个站点。这些端点会返回一个 `source_id`，您可以使用 `GET /kb-sources/{sourceId}` 进行轮询，直到其准备就绪。`POST /kb-sources/url` 也接受 `autoLinkToAgentId`，它会在导入完成后立即将源附加到 Agent，因此您可以跳过下方的附加调用。

### 附加知识源

`POST /agents/{agentId}/kb-sources` — 发送 `kb_source_ids` 并附带一个列表，即可在一次调用中附加整套知识源（在爬取站点后通常需要这样做），或者使用 `kb_source_id` 附加单个知识源。请发送其中一种。附加已存在的知识源不会有任何改变。

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'
```

**响应** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}
```

### 分离知识源

`DELETE /agents/{agentId}/kb-sources/{kbSourceId}` 用于单个，或使用 `POST /agents/{agentId}/kb-sources/bulk-remove` 配合 `kb_source_ids` 用于多个。批量删除是一个 `POST`，因为 ID 列表是在请求体中传递的。

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'
```

源本身不会被删除，并将继续可供您的其他 Agent 使用。取消关联未关联的内容不会产生任何影响。

### 常见问题解答 (FAQs)

常见问题解答在各自的端点上进行管理，并从那里链接到 Agent：使用 `POST /faqs/{faqId}/link` 配合 `{ "agent_id": "ag7HkQ2ZpLxR3mNb" }`，使用 `POST /faqs/{faqId}/unlink` 再次将其移除。一个常见问题解答可以被任意数量的 Agent 共享。请参阅 [FAQs API](faqs.md)。

> 常见问题解答仅由与其链接的 Agent 使用 — 仅创建一个常见问题解答本身是不够的。

---

## 工具

### 自定义函数

`POST /agents/{agentId}/custom-functions` 允许 Agent 在对话期间调用您的自定义函数之一。只有属于同一账户的函数才能被关联，关联一个已经关联的函数不会产生任何影响。

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'
```

`DELETE /agents/{agentId}/custom-functions/{customFunctionId}` 将其取消关联。函数本身不会被删除，并将继续可供您的其他 Agent 使用。

在 `/custom-functions` 上管理函数本身 — 请参阅 [自定义函数](../ai-automation/custom-functions.md) 以了解它们是什么。

### MCP 服务器

MCP 服务器是一组现成的工具包，您的 Agent 可以自行发现并调用 — 请参阅 [将 MCP 服务器连接到您的机器人](../ai-automation/mcp-servers.md)。服务器在账户上注册一次，然后关联到需要使用它们的任何 Agent。

> MCP 服务器需要您套餐中的 **自定义函数** 功能。如果没有该功能，账户级别的 `/mcp-servers` 端点将返回 `403`。将已注册的服务器关联到 Agent 不受此限制。

#### 注册服务器

`POST /mcp-servers`

| 字段 | 必填 | 描述 |
|---|---|---|
| `name` | 是 | 服务器的标签。 |
| `url` | 是 | 服务器地址。必须可通过公网访问。 |
| `auth_type` | 否 | `header`（默认值）用于静态认证头，或 `oauth2`。 |
| `auth_header_name` | 否 | 发送凭据的请求头。默认为 `Authorization`。 |
| `auth_header_value` | 否 | 凭据本身。绝不会在任何响应中返回。 |
| `enabled` | 否 | 服务器是否对 Agent 可用。默认为 `true`。 |
| `enabled_tools` | 否 | 工具名称白名单。`null` 表示服务器提供的所有工具均已启用。 |
| `tool_policies` | 否 | 按工具名称设置的限制（以工具名称为键）——包括工具触发频率、结果缓存以及只读覆盖。传入 `null` 可清除所有限制。 |

```bash
curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'
```

**响应** (`201`)

```json
{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}
```

保存时，平台会连接到服务器并缓存其提供的工具列表。**即使无法连接服务器，配置仍可保存**，此时 `last_error` 中会显示原因且工具列表为空——这样您可以先注册，稍后再修复连接问题。

当 `auth_type` 为 `oauth2` 时，注册将以 `oauth_connected: false` 状态保存且不包含任何工具：因为此时尚无令牌。授权 OAuth 服务器需要通过浏览器登录，且需在仪表板中完成，而非通过 API。

#### 列出、更新和删除服务器

- `GET /mcp-servers` — 获取所有已注册的服务器，按最新时间排序，位于 `servers` 下。
- `PUT /mcp-servers/{serverId}` — 仅发送您想要更改的内容。更改 URL 或认证字段会重新测试连接并刷新缓存的工具列表。
- `DELETE /mcp-servers/{serverId}` — 删除注册信息，并取消其与所有已启用该服务器的 Agent 和活动的关联。

```bash
curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"
```

**密钥绝不会返回。** 响应中会携带 `auth_header_value_set`（一个表示值已存储的 `true`/`false` 标志）来代替凭据，而 OAuth 令牌和客户端密钥将保留在服务器端。其他所有信息均会返回：`name`、`url`、`enabled`、`auth_type`、`auth_header_name`、`tools`、`enabled_tools`、`tool_policies`、`oauth_connected`、`tools_cached_at`、`last_connected_at`、`last_error`、`created_at`、`updated_at`。

#### 测试连接

`POST /mcp-servers/test-connection` — 连接到服务器并列出其工具。有两种调用方式：

- 使用 `server_id` — 测试**已保存**的配置并刷新其缓存的工具列表；
- 使用内联 `url`（加上 `auth_header_name` / `auth_header_value`） — 一种预保存测试，不会存储任何内容。

```bash
curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'
```

**响应** (`200`)

```json
{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}
```

连接失败**不是** HTTP 错误 — 您会收到一个包含 `success: false` 和描述错误原因的 `error` 的 `200`，以便您将其显示在操作员正在编辑的字段旁边。

#### 将服务器附加到 Agent

注册服务器并不会让任何 Agent 获得访问权限。请进行附加操作：

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'
```

**响应** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }
```

`DELETE /agents/{agentId}/mcp-servers/{mcpServerId}` 可将其再次分离。服务器本身不会被删除，且对您的其他 Agent 依然可用。附加或分离已处于该状态的内容不会产生任何影响。

---

## 媒体库

媒体库存储 Agent 在对话期间可能发送的文件——例如菜单、价目表或产品照片。一个 Agent 最多可持有 **50 个项目**。

### 列出媒体

`GET /agents/{agentId}/media-library`

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"
```

**响应** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}
```

存储在 Agent 上的项目优先，其次是构建该 Agent 的营销活动中仍存储的任何旧项目；`media_home`（`agent` 或 `campaign`）用于区分两者。在每个组内，最新的项目排在最前面。

> **`media_url` 将在 7 天后过期。** 这是文件上传时创建的下载链接——如果遇到旧链接，请将其视为过期而非损坏，并重新读取列表以获取新链接。

### 上传媒体

`POST /agents/{agentId}/media-library` —— 文件以 base64 格式内联上传，最大支持 **10 MB**。调用将在文件存储后返回，因此请比普通请求预留稍长的时间。请注意，此主体使用 camelCase 字段名称。

| 字段 | 必填 | 描述 |
|---|---|---|
| `base64Data` | 是 | 文件内容，base64 编码，不带 data-URL 前缀。 |
| `mimeType` | 是 | 文件的 MIME 类型。 |
| `fileName` | 是 | 原始文件名，用于命名存储的文件。 |
| `title` | 否 | 库中显示的简短标签。 |
| `description` | 否 | “Agent 何时应发送此内容”的指令。 |
| `sendMessage` | 否 | Agent 发送该项目时使用的首选措辞。截断至 500 个字符。 |
| `maxSendsPerConversation` | 否 | 在一次对话中可发送给同一联系人的次数。默认为 `1`。 |
| `sendAsVoiceNote` | 否 | 仅限音频上传 —— 将文件存储为 WhatsApp 语音备忘录。其他文件类型将被忽略。 |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'
```

系统会自动执行两项操作：将动画 GIF 转换为视频，以便其在所有渠道上播放；平台会编写一段关于文件实际内容的简短摘要，以便 Agent 知道何时适用。

`400` 涵盖了缺少字段、不支持的文件类型、文件为空或过大以及达到 50 个项目的限制。 `403` 表示该账户的媒体库已关闭。

### 更新媒体项目

`PATCH /agents/{agentId}/media-library/{itemId}` —— 仅限元数据。文件本身无法替换；请上传新项目并删除旧项目。此主体使用 snake_case：`title`、`description`、`send_message`、`max_sends_per_conversation`（一个非负整数，或使用 `null` 清除限制）。

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'
```

**响应** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}
```

### 删除媒体项目

`DELETE /agents/{agentId}/media-library/{itemId}` —— 删除项目及其存储的文件。删除已不存在的项目会成功并返回 `deleted: false`，因此该调用可以安全重试。

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"
```

---

## 生成跟进消息

`POST /agents/{agentId}/template-generation` —— 根据 Agent 的用途，为您编写 Agent 的跟进消息（即当对话静止时发送的提醒）。

| 字段 | 描述 |
|---|---|
| `type` | `all`（默认值）写入整个集合。`cold_only` 仅写入从未回复的联系人的消息。 |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'
```

此操作有两种返回方式，`target` 字段会告知您具体是哪一种：

- **`target: "agent"` 带有 `200`** — 消息是在通话期间写入的，结果位于 `data` 中。请从代理的 `follow_up_config` 中读取它们。这是常见情况。
- **`target: "campaign"` 带有 `202`** — 工作已排队至 `campaign_id` 中命名的营销活动。请持续关注该营销活动的 `template_generation_status`，直到其完成。 |

`cold_only` 需要一个外呼营销活动，如果代理没有配置该活动，则会拒绝并返回 `409` (`reason: "cold_only_requires_campaign"`)。`403` 表示账户未开启自动跟进功能。此功能会消耗 AI 点数，如果返回 `400` 且带有 `"Insufficient credits."`，则表示账户点数不足。 |

---

## 将对话路由至代理

代理仅会应答由**入口点 (Entry Point)** 发送给它的对话。在渠道拥有入口点之前，来自陌生人的第一条消息虽然会被存储，但不会被任何代理获取，也不会有助手进行回复。

| 您想要执行的操作 | 调用 |
|---|---|
| 将代理设置为整个渠道的应答者 | `PUT /entry-points/channel-defaults` 带有 `{ "channel": "instagram", "agent_id": "AGENT_ID" }` |
| 添加更具体的规则（关键词、评论、新关注者） | `POST /agents/{agentId}/entry-points` |
| 查看指向某个代理的规则 | `GET /agents/{agentId}/entry-points` |
| 让某个渠道处于无人应答状态 | `DELETE /entry-points/channel-defaults?channel=instagram` |

### 列出代理的入口点

`GET /agents/{agentId}/entry-points` — 发送对话至此代理的路由规则，按最新顺序排列。当前规则和已停用规则都会返回；已停用的规则会带有 `enabled: false`。

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"
```

若要获取整个账户的渠道默认设置（包括特意设置为无人应答的渠道），请改为读取 `GET /entry-points/channel-defaults`。

### 创建入口点

`POST /agents/{agentId}/entry-points` — 路径中的代理始终具有最高优先级，因此无法为 URL 中指定的代理以外的其他代理创建规则。

| `type` | 功能描述 |
|---|---|
| `channel_default` | 代理应答所列渠道上的所有新联系人。建议优先使用 `PUT /entry-points/channel-defaults` 来实现此目的，因为它会自动为您停用之前的应答者，而在此处创建第二个默认设置则不会。 |
| `keyword` | 当第一条消息包含 `match_config.keywords` 中的关键词时，代理接管对话。至少需要一个关键词。 |
| `instagram_comment` / `facebook_comment` | 代理回复您帖子下的评论。匹配的渠道必须列在 `channels` 中。 |
| `instagram_follower` | 代理向新关注者发送问候。 |

`channels` 是必需的，用于说明规则涵盖哪些渠道 — 例如 `whatsapp`、`whatsapp_web`、`instagram`、`messenger`、`telegram`、`sms`、`email`、`chat_widget` 或 `custom_channel`。除非您另有说明，否则新规则默认处于启用状态。

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'
```

**响应** (`201`)

```json
{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }
```

**当多条规则适用时，哪条规则胜出：** 正在进行的对话或手动分配会保留其现有的代理；否则，关键词规则优于评论规则，评论规则优于关注者规则，渠道默认设置是最后手段。这些规则是否已在账户上生效，由 `GET /entry-points/routing-status` 报告。

这是简要版本。[入口点 API](entry-points.md) 指南涵盖了完整的梯队、评论和关注者规则、每个 WhatsApp 号码对应一个代理，以及更改或删除规则的相关内容。请参阅[入口点](../ai-agents/entry-points.md)了解概念，并参阅[渠道 API](channels.md)以连接渠道本身。

---

## AI 智能体 API 错误

智能体端点返回标准的错误封装：

```json
{
  "success": false,
  "error": "Agent not found"
}
```

| 状态 | 在智能体端点上发生的情况 |
|---|---|
| `400` | 缺少必填字段或字段无效 — 例如更新主体为空、值超出允许列表（`ai_speed`、`anthropic_model`、`booking_provider`、`mode`、`type`）、`availability` 中包含非工作日键、`bot-config` 上使用了点号字段名，或路径中的 ID 格式错误。 |
| `403` | 账户不允许使用您发送的设置、您已达到套餐的智能体限制，或者此端点所需的功能（媒体库、跟进、MCP 服务器的自定义函数）已关闭。超出您套餐允许配置大小的更改将被 `400` 拒绝。 |
| `404` | 未找到智能体、标签规则、媒体项或 MCP 服务器 — 它们要么不存在，要么属于其他账户。 |
| `409` | 有操作正在进行或受阻：优化或标签生成正在运行、智能体仍连接到广播、入口点或营销活动，或者在没有外发营销活动的情况下请求了 `cold_only`。 |

每个端点都可能返回的共享代码 — `401`, `403`（您的套餐不包含 API 访问权限）, `429`（速率限制）和 `500` — 及其重试指南列在 [错误与分页](errors-and-pagination.md) 中。

> **关于探索器的说明。** `/agents` 端点已包含在发布的 OpenAPI 规范中，因此您可以在 [API 参考](reference.md) 中浏览其确切字段并运行实时请求。账户级别的 `/mcp-servers` 端点也包含在规范中，您也可以在那里进行探索。


---

## 相关内容

- [AI 智能体](../ai-agents/ai-agents.md) — 用通俗语言解释什么是智能体。
- [入口点](../ai-agents/entry-points.md) — 对话如何路由到智能体。
- [常见问题解答 API](faqs.md) — 构建并链接您的智能体用于回答问题的知识库。
- [渠道 API](channels.md) — 连接智能体进行回复的渠道。
- [将 MCP 服务器连接到您的机器人](../ai-automation/mcp-servers.md) · [自定义函数](../ai-automation/custom-functions.md)
- [API 参考](reference.md) — 完整的交互式端点探索器。