AI 智能体 API

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

基础 URL — https://api.youraiconnector.com/v1
身份验证 — 您的 API 密钥（请参阅身份验证）
错误与分页 — 请参阅错误与分页

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

如果您是第一次接触智能体概念，请先阅读 AI 智能体。

智能体的组成部分

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

组件	说明	设置位置
配置	指令、规则、目标、个性、语言、AI 等级、预约和跟进行为	`PUT /agents/{agentId}` 或更具体的 `PUT /agents/{agentId}/bot-config`
知识	常见问题解答 (FAQ) 和知识源（平台为您读取的页面和文档）	FAQ API 和 `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`

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

智能体对象

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

{
  "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 读取您需要的那个。

查询参数

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

cURL

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

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

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)

{
  "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	每个工作日的活跃时间 — 请参阅设置活跃时间。
`ai_speed`	string	`fast`、`fast_thinker`、`balanced` 或 `thorough`。
`anthropic_model`	string	`standard`、`economy`、`max` 或 `mini`。
`scrape_urls`	string[]	用于读取并构建 Agent 指令的页面。

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

cURL

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

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

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)

{
  "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

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

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

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

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

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

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)

{ "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。

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。您遗漏的天数将保留其原有设置，任何非工作日的键都会被拒绝——因此拼写错误不会导致静默失败。

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)

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

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

暂停或恢复 Agent

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

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

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)

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

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

复制 Agent

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

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

响应 (201)

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

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

删除 Agent

DELETE /agents/{agentId}

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

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

响应 (200)

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

已阻止 (409)

{
  "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 优化生成的任何重写内容，都会作为未发布草稿保留，直到您发布它们为止。在此之前，在线 Agent 将继续使用其当前配置进行回复。

发布草稿

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

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

响应 (200)

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

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

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

放弃草稿

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

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。两者中至少有一个必须包含文本。

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)

{ "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

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)

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

替换标签规则

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

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 将停止应用该标签。标签本身以及任何已经带有该标签的联系人均不受影响。

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` 则从零开始设计整个集合。

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)

{ "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 附加单个知识源。请发送其中一种。附加已存在的知识源不会有任何改变。

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)

{
  "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 列表是在请求体中传递的。

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。

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

工具

自定义函数

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

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 上管理函数本身 — 请参阅自定义函数以了解它们是什么。

MCP 服务器

MCP 服务器是一组现成的工具包，您的 Agent 可以自行发现并调用 — 请参阅将 MCP 服务器连接到您的机器人。服务器在账户上注册一次，然后关联到需要使用它们的任何 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` 可清除所有限制。

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)

{
  "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 和活动的关联。

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） — 一种预保存测试，不会存储任何内容。

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)

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

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

将服务器附加到 Agent

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

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)

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

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

媒体库

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

列出媒体

GET /agents/{agentId}/media-library

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

响应 (200)

{
  "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 语音备忘录。其他文件类型将被忽略。

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 清除限制）。

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)

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

删除媒体项目

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

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` 仅写入从未回复的联系人的消息。

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。

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。除非您另有说明，否则新规则默认处于启用状态。

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)

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

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

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

AI 智能体 API 错误

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

{
  "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 — 及其重试指南列在错误与分页中。

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

AI 智能体 API #

智能体的组成部分 #

智能体对象 #

列出智能体 #

创建 Agent #

获取 Agent #

更新 Agent #

更新机器人设置 #

设置活跃时间 #

暂停或恢复 Agent #

复制 Agent #

删除 Agent #

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

发布草稿 #

放弃草稿 #

使用 AI 优化智能体 #

标签规则 #

添加标签规则 #

替换标签规则 #

删除标签规则 #

使用 AI 生成标签集 #

知识源 #

附加知识源 #

分离知识源 #

常见问题解答 (FAQs) #

工具 #

自定义函数 #

MCP 服务器 #

注册服务器 #

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

测试连接 #

将服务器附加到 Agent #

媒体库 #

列出媒体 #

上传媒体 #

更新媒体项目 #

删除媒体项目 #

生成跟进消息 #

将对话路由至代理 #

列出代理的入口点 #

创建入口点 #

AI 智能体 API 错误 #

相关内容 #

AI 智能体 API

智能体的组成部分

智能体对象

列出智能体

创建 Agent

获取 Agent

更新 Agent

更新机器人设置

设置活跃时间

暂停或恢复 Agent

复制 Agent

删除 Agent

草稿：在生效前审查更改

发布草稿

放弃草稿

使用 AI 优化智能体

标签规则

添加标签规则

替换标签规则

删除标签规则

使用 AI 生成标签集

知识源

附加知识源

分离知识源

常见问题解答 (FAQs)

工具

自定义函数

MCP 服务器

注册服务器

列出、更新和删除服务器

测试连接

将服务器附加到 Agent

媒体库

列出媒体

上传媒体

更新媒体项目

删除媒体项目

生成跟进消息

将对话路由至代理

列出代理的入口点

创建入口点

AI 智能体 API 错误

相关内容