AI 智能体
AI 智能体是一个多步骤助手。它会读取对话、制定计划、调用工具（您的 AI 工具、MCP 工具和知识库搜索）、查看结果，并再次调用模型，直到得出答案。创建 AI 聊天补全节点只进行一次模型调用并回复；而 AI 智能体节点可以在您设定的限制内，持续进行多次模型和工具调用，然后再作答。
当一个请求需要多个步骤时，请使用智能体，例如“找到客户的订单、查看其配送状态并提供新的送达日期”。如果只需要根据说明和知识库给出直接回答，AI 节点更简单、成本也更低。
基本组成
| 部分 | 说明 | 设置位置 |
|---|---|---|
| AI Harness | 运行智能体循环的引擎：MonoChat 自有的、某个智能体 SDK，或托管的智能体服务。 | 设置 › 自动化 › AI 运行框架 |
| 模型 | 智能体用来思考的 AI 模型：一个主模型、一个可选的备用模型和一个可选的快速模型。托管 Harness 则改用其自身提供商的模型。 | AI 智能体节点 |
| 工具 | AI 范围、AI 工具函数和 MCP 工具。 | AI 智能体节点 |
| 执行预算 | 对每次运行的模型调用、工具调用、令牌、时长和重试次数的限制。 | AI 智能体节点 |
| 运行 | 智能体的一次执行。每次运行都会记录在 AI 智能体运行记录中。 | 由节点或 API 创建 |
AI 运行框架
设置 › 自动化 › AI 运行框架列出了您的智能体可以运行在其上的 Harness：既有 MonoChat 向每个工作区提供的，也有您使用自己的凭据添加的。
| Harness | 运行位置 | 使用的模型 | 添加者 |
|---|---|---|---|
| MonoChat Native | MonoChat 内部 | 您的 AI 模型 | MonoChat |
| OpenAI Agents SDK | MonoChat 内部 | 您的 AI 模型 | MonoChat |
| Claude Agent SDK | MonoChat 智能体运行器 | 您的 AI 模型 | MonoChat |
| pi | MonoChat 智能体运行器 | 您的 AI 模型 | MonoChat |
| OpenAI Agents API | OpenAI 的云端 | Harness 允许的模型 | 您，使用您的 OpenAI API 密钥（MonoChat 也可能提供一个） |
| Claude Managed Agents | Anthropic 的云端 | Harness 允许的模型 | 您，使用您的 Anthropic API 密钥（MonoChat 也可能提供一个） |
| 自定义端点 | 您自己的服务器 | 您的 AI 模型（可选） | 您，使用您的端点和密钥 |
在 MonoChat 上运行的 Harness 由 MonoChat 提供；您的工作区只能添加使用自己凭据的 Harness。Claude Agent SDK 和 pi 需要 MonoChat 的智能体运行器：在未设置该运行器的地方，使用它们的运行会失败，并提示 “This harness is not available on this server.”
无论使用哪种 Harness，MonoChat 始终保持掌控：使用您的 AI 模型的 Harness 的每一次模型调用都会经过 MonoChat（因此计费和预算都会生效），每一次工具调用都会在您的工作区中运行您的函数、MCP 工具和 AI 范围，并且预算在每种 Harness 上都会强制执行。
添加 Harness
- 前往设置 › 自动化 › AI 运行框架，点击 +（创建）。
- 输入名称，并可选择填写描述。
- 选择 Harness。每个选项都会说明它的运行位置。
- 在凭据下，输入该 Harness 所需的内容：
- OpenAI Agents API、Claude Managed Agents：API 密钥。
- 自定义端点：端点和 API 密钥。
- 对于托管 Harness，请填写允许的模型：输入提供商的模型名称（例如 OpenAI 或 Anthropic 的模型 ID）。使用添加模型最多可添加 10 个模型。该 Harness 上的智能体只能从此列表中选择。
- 点击保存。
编辑 Harness 时，无法更改 Harness 类型，并且密钥字段显示为 API 密钥（留空则保留已保存的密钥）。
首次使用此类型的 Harness 时，MonoChat 会在该 Anthropic 账户中创建一个智能体和一个环境，并在之后重复使用它们。
自定义端点
自定义端点 Harness 会将运行发送到您自己的服务，例如自托管的智能体。对于每次运行，MonoChat 会向 <Endpoint>/runs 发送一个 POST 请求，并附带 Authorization: Bearer <API Key>。请求体包含运行 ID、说明、输入、对话消息、预算、模型别名（agent-main、agent-fallback、agent-fast），以及三个带有本次运行令牌的 URL：
- 模型网关（兼容 OpenAI 的
…/v1和兼容 Anthropic 的基础 URL），它会调用节点的 AI 模型并强制执行预算， - 一个暴露本次运行所用工具的 MCP 服务器，
- 一个事件 URL，您的服务通过它报告结果（
completed并附带result，或failed并附带error）。
运行结束时，该运行的令牌即失效。
AI 智能体节点
使用 AI 智能体节点将智能体添加到流程中，它位于流程设计器的混合节点下。有关如何添加和连接节点，请参阅流程。
字段
| 分区 | 字段 | 描述 |
|---|---|---|
| 名称 | 画布上显示的节点名称。 | |
| AI Harness | 必填。运行该智能体的 Harness。 | |
| 说明 | 智能体的系统指令：其角色、语气、规则，以及可以做和不可以做的事情。 | |
| 任务（会添加到智能体指令中；可使用标签） | 该节点要求智能体做的事情。它会添加在说明之后，并且可以使用与 AI 节点提示词相同的标签，例如用来引入客户数据。 | |
| 模型 | 主模型 | 智能体使用的模型。除自定义端点外，所有 Harness 都必须填写。 |
| 备用模型（达到软限制后） | 智能体在模型调用次数达到软限制后切换到的模型，通常是更便宜或更快的模型。 | |
| 快速模型（轻量后台任务） | Harness 可用于其轻量后台调用的模型。 | |
| 模型（Harness 允许的模型之一） | 对于托管 Harness，显示此字段以代替上面三个字段。 | |
| 智能体对话 | 会话 | 继续现有的智能体会话（默认）或开始新的智能体会话。请参阅智能体会话。 |
| 任务键（每个任务使用独立的智能体对话） | 可选。在同一对话中为每个键保留一个独立的智能体会话，例如 booking 和 support。 | |
| 消息历史上限 | 智能体接收多少条对话消息。 | |
| 语音转文字 AI 模型 | 具备转录功能的模型。对话中的语音消息会以文本形式传给智能体。 | |
| 工具设置 | AI 范围 | 智能体可以搜索的知识库。它们会作为知识库搜索工具提供给智能体。 |
| AI 工具 | 智能体可以调用的 AI 工具类型函数。 | |
| 设置 AI MCP 客户端内容工具 | 打开用于添加 MCP 工具的抽屉。请参阅 MCP 客户端。 | |
| 消息 | 将中间消息转发给客户 | 默认关闭。开启时，智能体在仍在工作时写下的内容（例如“让我查一下您的订单”）会发送给客户；关闭时，它会作为仅您的团队可见的内部备注消息添加到会话中。 |
| 发送回答 | 默认开启。将智能体的最终回答发送给客户。如果只想在流程内部使用该回答，请将其关闭。 | |
| 执行预算 | 最大模型调用次数 | 默认 4。 |
| 软限制：模型调用次数 | 可选。达到这个模型调用次数后，智能体会切换到备用模型。必须低于最大模型调用次数，并且需要设置备用模型。 | |
| 最大工具调用次数 | 默认 6。设为 0 时，智能体一尝试调用工具，运行就会以预算已超出结束。 | |
| 最大总令牌数 | 默认 20000。本次运行中所有模型调用的输入和输出令牌。 | |
| 最长时长（秒） | 默认 30。 | |
| 最大重试次数 | 默认 2。失败的模型调用会重试多少次。 |
把稳定的规则写在说明中，把这一步的具体工作写在任务中。这样，流程中的多个 AI 智能体节点可以共用同一份说明，只在任务上有所不同。
托管 Harness 不支持软限制，因为它们无法切换到备用模型。对它们请将软限制：模型调用次数留空。
流程到达该节点时会发生什么
- MonoChat 检查您的余额和节点设置，并启动一次运行。运行先是排队中，然后是运行中。流程实例在该节点上等待。
- 智能体收到说明和任务；如果流程属于某个对话，还会收到该对话中不超过消息历史上限的消息，其中的语音消息已被转录。
- 智能体调用模型和工具，直到得出答案或达到某项限制。它在两次工具调用之间写下的文本会作为中间消息处理。
- 运行结束时：
- 如果运行已完成且发送回答已开启，回答会发送给客户。当回答超过渠道的长度限制（WhatsApp 为 4096 个字符）时，会被拆分成多条消息；
- 如果以其他方式结束，会向会话添加一条内部备注消息 “AI agent run ended: status. error”，供您的团队查看。
- 流程会沿着与运行结束方式相匹配的输出继续。
同一个智能体会话的运行会按顺序逐个处理。
输出
| 输出 | 何时触发 |
|---|---|
| 已完成 | 智能体已给出答案并结束。 |
| 预算已超出 | 运行用完了最大模型调用次数、最大工具调用次数或最大总令牌数。 |
| 已超时 | 运行达到了最长时长（秒）。 |
| 仇恨、越狱、自残、色情、暴力 | 模型提供商的内容过滤器因该类别而终止了运行。这些与 AI 节点的输出相同。 |
| 失败时 | 运行因任何其他原因失败，或被取消。在这些输出出现之前保存的节点上，内容过滤器导致的终止也会走这个输出；打开并保存此类节点即可获得这些输出。 |
请至少连接已完成和失败时。一种常见做法是把预算已超出、已超时和失败时连接到分配会话节点，让团队成员接手。
智能体会话
智能体会话是智能体在多次运行之间的记忆。MonoChat 为每个对话、Harness 和任务键保留一个活跃的智能体会话。
- 继续现有的智能体会话会复用该会话，让智能体从上次中断的地方继续。在托管 Harness 上，提供商自己的会话也会继续。
- 开始新的智能体会话会关闭当前活跃的会话并重新开始，例如在新话题开始时。
- 任务键可以让多个相互独立的会话在同一个对话中并存。
计费
- MonoChat 提供的 AI 模型上的模型调用照常从您的余额中扣费。您自己的模型上的调用由您的提供商计费。
- MonoChat 提供的 Harness 可以按每次运行、每分钟和每次工具调用收取自己的费用；对于托管 Harness，还会收取其提供商报告的令牌费用。它们会在交易中显示为 AI 智能体运行记录、AI 智能体时长、AI 智能体工具调用以及 AI 令牌类别。
- 您使用自己的凭据添加的 Harness 没有 MonoChat 费用；由其提供商向您计费。
- 余额不足时，运行不会启动。
AI 智能体运行已结束事件
AI 智能体运行已结束是一个事件节点。当与某位客户相关联的运行结束时它就会触发，无论该运行是由流程启动的，还是通过带会话的 API 启动的。与其他事件节点一样，它有可选的条件和超时设置。可用它在智能体运行之后启动一个单独的流程，例如记录结果或通知团队。
通过代码启动智能体
自定义函数和 API 客户端可以使用以下方法运行智能体（权限 Start / Read / Cancel AI agent runs in automation）：
| 方法 | 作用 |
|---|---|
business.tenants.automation.ai.aiAgentRuns.create | 启动一次运行。返回 aiAgentRunId 和 aiAgentSessionId。 |
business.tenants.automation.ai.aiAgentRuns.show | 返回一次运行（_id）及其状态、用量、步骤和结果。 |
business.tenants.automation.ai.aiAgentRuns.cancel | 取消排队中或运行中的运行（_id）。 |
create 接受 aiHarnessClientId、input（任务），以及可选的 sessionId（用于在某个对话中工作）、aiAgentSessionId、taskKey 和 isNewSession，还有带有与节点相同设置的 options：instructions、aiModelClientId、fallbackAiModelClientId、fastAiModelClientId、harnessModel、toolCustomFunctionIds、aiScopeIds、aiMcpClientDatas、messageHistoryLimit、speechToTextAiModelClientId、forwardIntermediateMessages、willSendAnswer 和必填的 budget。通过 API 调用时，forwardIntermediateMessages 和 willSendAnswer 默认为 false。
const { aiAgentRunId } = await sdk.method({ name: 'business.tenants.automation.ai.aiAgentRuns.create' }).callAsync({
payload: {
aiHarnessClientId: 'HARNESS_ID',
input: 'Summarise the open orders of this customer.',
sessionId: 'SESSION_ID',
options: {
instructions: 'You are the order assistant of our store.',
aiModelClientId: 'MODEL_ID',
toolCustomFunctionIds: ['FUNCTION_ID'],
budget: { maxLlmCalls: 4, maxToolCalls: 6, maxTotalTokens: 20000, maxDurationSeconds: 30, maxRetries: 2 },
},
},
})
运行是异步的：稍后使用 show 读取它，或通过 AI 智能体运行已结束事件对其作出响应。如果没有 sessionId，每次调用都会启动一个新的智能体会话，除非您传入上一次调用返回的 aiAgentSessionId；此时智能体会把该智能体会话中之前已完成的运行视为其历史记录。有关如何在函数中调用方法，请参阅方法。
权限
| 权限 | 允许 |
|---|---|
| Read / Create / Update / Delete AI harnesses in automation | 管理 AI 运行框架 |
| Read AI agent runs in automation | 查看 AI 智能体运行记录 |
| Start AI agent runs in automation | 调用 aiAgentRuns.create |
| Cancel AI agent runs in automation | 调用 aiAgentRuns.cancel |
请参阅角色。
相关内容
- AI 智能体运行记录：查看每次运行做了什么
- AI 模型
- MCP 客户端
- AI 范围
- 流程