mateclaw/mateclaw-server/src/main/resources/docs/zh/agents.md

---
title: 多智能体引擎 — ReAct + Plan-and-Execute 双模式
description: MateClaw 的多智能体系统支持 ReAct 推理循环和 Plan-and-Execute 任务拆解两种模式。Agent 之间可以互相委派，实现真正的多智能体协作。
head:
  - - meta
    - name: keywords
      content: 多智能体,ReAct,Plan-and-Execute,Agent委派,Spring AI Alibaba,AI Agent
---

# 多智能体引擎

> **它们现在叫"数字员工"了。** 后台所有出现"智能体"的地方都改了。底层运行时还是 Agent，但 UI 上、概念上、模板上——它们是你团队里的同事。
> 命名变了，世界观也跟着变了：你给一个员工**角色（Role）**、**目标（Goal）**、**背景故事（Backstory）**，他知道自己是谁、为什么存在；你不用再写一段冷冰冰的 system prompt 让"agent"理解任务。

**一个数字员工就是一个带工具的人格。多个员工组成一支团队。**

短版本是这个。长一点的版本：一个员工是一个名字，一段定义它怎么思考的 system prompt（包含角色 / 目标 / 背景故事），一个真正在思考的模型，一组它被允许调用的工具，可选的知识库，可选的技能包，它自己的一份记忆，以及它处理难题的方式——一步一步反应式（ReAct）还是先写计划再执行（Plan-and-Execute）。

你可以有很多个员工。每一个都专门做一类事。你把不同的活交给不同的员工。

---

## 一个数字员工有什么

| 部分 | 是什么 |
|------|--------|
| **名字** | 你和你的团队找它用的 |
| **图标** | 像素艺术风格、按角色配色，一眼认出 |
| **角色 (Role)** | 一句话——"我是产品研究员" / "我是客户支持" |
| **目标 (Goal)** | 一句话——"我帮你看清楚市场怎么动" |
| **背景故事 (Backstory)** | 它来自哪、为什么存在、它在意什么；这些会自动拼到最终 system prompt |
| **员工卡片标语 (Tagline)** | 卡片上展示的一句"自我介绍" |
| **System Prompt** | 它的人格、规则、风格、优先级（角色/目标/背景故事会自动注入） |
| **类型** | `react` 或 `plan_execute` |
| **工具** | 它被允许调用的工具（来自内置工具、MCP、技能包、ACP 桥接） |
| **知识库** | 它可以读的 LLM Wiki（KB 热点会自动注入到 system prompt） |
| **工作空间记忆** | 它自己那一份 `PROFILE.md`、`MEMORY.md`、`SOUL.md`、`AGENTS.md`，以及每日笔记 |
| **最大迭代次数** | 强制收敛前允许走多少轮推理循环 |
| **启用开关** | 关掉它 |

模型按 **会话固定模型 → Agent 模型覆盖 → 全局默认模型** 的优先级解析。会话可以临时固定一个已启用的供应商 / 模型；Agent 也可以选择自己的主模型，留空才继承全局默认。若固定项已被禁用或删除，运行时会回退到 Agent 覆盖或全局默认，而不是让会话直接失败。每个 Agent 还可维护按供应商 + 模型排列的故障转移偏好链。

---

## 模板：从一个已经会工作的同事开始

你不必从一张白纸开始。`数字员工 → 新建` 会打开模板选择器，列出服务端 `classpath:templates/*.json` 中的模板；也可以跳过模板，直接进入空白表单。

### 6 个内置模板（推荐）

每一个都自带角色、目标、背景故事、合适的工具集、像素艺术头像、专属配色——**打开就能用**：

- **通用助手**——搜索、写作、分析等日常任务
- **产品助理**——澄清用户、场景与需求，整理产品判断
- **研究分析师**——拆解复杂研究任务，结合网络搜索与 Wiki
- **客服助理**——先共情，再查知识并解决或升级问题
- **数据分析师**——查数据源、跑 SQL、出图表、写结论
- **代码审查员**——阅读代码、发现问题并给出改进建议

选择模板会直接创建对应 Agent；跳过模板则进入可完整编辑的自定义表单。创建之后，名称、角色、目标、模型、技能、工具和知识库范围仍可继续调整。

---

## 两种思考方式

### ReAct —— 思考、行动、观察、继续

默认模式。ReAct 模式下的 Agent 跑一个循环：**推理**下一步该做什么，**行动**（可能调一个工具），**观察**结果，决定是再循环一次还是回答。

适合：
- 简单问答，需要一两次工具调用
- 对话式交互，每一轮用户输入都不大
- 需要 Agent "边学边反应"的任务

例子：*"北京今天什么天气？"* → 推理（需要实时数据）→ 行动（调 web search）→ 观察（15–26°C，晴）→ 回答。

### Plan-and-Execute —— 先计划、再执行

适合更大的任务。Agent 先生成一个**计划**——一个由 2 到 6 个步骤组成的有序列表，然后一步一步执行。完成之后，总结一下所有做过的事。

适合：
- 多步研究（"调查 X，对比 Y，写一个简报"）
- 步骤在一开始就能想清楚的任务
- 你想**看着进度跑**的任务——计划和每一步的状态会出现在对话旁边的**持久任务清单**里

例子：*"研究一下 Spring AI 框架，对比前三个，给我写个简报。"* → 计划（4 步）→ 按顺序执行 → 最终汇总。

### 怎么选

| 情境 | 用哪个 | 为什么 |
|------|--------|--------|
| 简单问答、单工具调用 | ReAct | 没有计划开销 |
| 信息检索 | ReAct | 一般 2–3 轮就结束 |
| 多步有序任务 | Plan-and-Execute | 显式计划更好看、更好 debug |
| 研究 + 对比 + 写作 | Plan-and-Execute | 每一步的结果喂给下一步 |
| "读这份文件然后告诉我 X" | ReAct | 一个工具，一个答案 |
| "给我写一份关于 X 的结构化报告" | Plan-and-Execute | 多轮收集 + 综合 |

类型可以随时改。同一份 system prompt 在两种模式下都能工作得不错。

---

## 多 Agent 并行委派

一个 Agent 不是孤军作战。一个 Agent 可以把任务委派给另一个——或者**同时委派给多个**（最多 8 个）。

- **单点委派** —— 把一个子任务交给指定 Agent，在独立会话中执行，结果流式回传
- **并行委派** —— 同时委派给多个 Agent，每个在自己的隔离会话里跑
- **子会话实时可见** —— 你在 ChatConsole 里能看到每个子任务的推理、工具调用和进度
- **路由提示** —— 系统 prompt 里内置，Agent 知道什么时候该自己做、什么时候该委派

例子：让代码 Agent 处理 Jira 工单，同时让研究 Agent 拉竞品数据，同时让写作 Agent 起草 Slack 回复。三路并行，结果汇总给编排者。

### 多级子员工委派树

::: tip 1.4.0 新增
委派不再只有一层。一个父员工可以委派给子员工，子员工还能再往下委派——**递归最深 3 级**。一支临时团队可以为某个具体任务自己长出层级。
:::

三个委派工具，覆盖三种节奏：

- **`delegateToAgent`** —— 同步委派。把一个子任务交给指定员工，等它跑完、拿到最终结果再返回。可选 `inheritParentContext`：把父会话最近的上下文一起带给子员工，省去重复交代背景。
- **`delegateParallel`** —— 扇出委派。同时派给多个子员工，各自在隔离会话里跑，结果统一收集回来。
- **`delegateAsync`** —— 后台委派。立刻返回一个 `task_id`，子员工在后台跑；之后用 **`taskOutput`** 取结果。后台任务默认有 3600 秒执行预算，可通过 `mateclaw.delegation.async-timeout-seconds` 配置，或在单次调用中用 `timeoutSeconds` 调整（最大 86400 秒）；超时后 MateClaw 会停止子会话并持久化失败结果，避免遗留孤儿任务。`taskOutput` 带**归属闸门**——只有最初发起委派的**同一个会话 + 同一个用户**才能读到结果，防止跨会话/跨用户泄露。

#### 异步长任务：调度、轮询与验收

`delegateAsync` 走通用异步任务池。当前每个用户最多同时运行 **3 个**异步任务，这个额度由委派、图片、视频等异步任务共享。批量任务应按“最多启动 3 个 → 轮询到至少一个终态 → 再补位”的方式滚动执行；触发并发上限的调用不会返回 `task_id`，不能把它计入已启动任务。

`taskOutput` 的参数与返回语义：

| 项 | 语义 |
|---|---|
| `taskId` | 必填，使用 `delegateAsync` 返回的 `task_id` |
| `block` | 可选，默认 `false`；设为 `true` 时在本次调用里等待终态 |
| `timeoutSeconds` | 只控制一次阻塞轮询，默认 30 秒、最大 120 秒；不改变子任务的执行预算 |
| `status` | `pending` / `running` / `succeeded` / `failed` |
| `progress` | 运行态的生命周期进度；本地委派目前通常保持 0，终态变为 100，不代表内容完成百分比 |
| `duration_ms` | 仅终态返回的墙钟耗时 |

::: warning `succeeded` 不等于交付验收通过
`succeeded` 只表示子任务没有以运行时异常或超时结束。模型可能只返回提纲、工具调用可能失败、目标字数可能未达到，任务仍会进入 `succeeded`。父员工在汇总或完成目标前，必须再次检查业务证据。
:::

建议至少设置以下验收门禁：

1. 要求的文件、链接或结构化结果真实存在并且可读；不要只相信回答中的“已生成”。
2. 字数、章节数、场景数等量化要求有可复核计数。
3. 计划或清单没有待办项，最终回答没有“后续继续”“其余待补”等未完成声明。
4. 关键写入、读取、执行工具没有失败；若工具失败后改为正文交付，要明确记录降级方式。
5. 父员工把上述证据写进[目标清单](./goals)，只有全部准则通过后才完成目标。

子员工默认被拒绝一组工具，保证树不失控：

- `delegateToAgent` / `delegateParallel` / `listAvailableAgents`（递归护栏——子员工不能再发起同步/并行委派，也不能枚举兄弟员工）
- `setGoal` / `addGoalCriterion` / `completeGoal` / `getGoalStatus`（目标所有权留在父员工手里）
- `remember` / `remember_structured` / `forget_structured`（子员工不能写入父员工的长期记忆）
- `create_employee`（子员工不能凭空造新员工）

这组默认拒绝列表可通过 `mateclaw.delegation.child-denied-tools` 调整。

委派和[目标系统](./goals)配合使用——父员工定目标、拆任务、把子任务委派下去，子员工专注执行。

### UI —— 嵌套子员工时间线 + 常驻计划面板

ChatConsole 把整棵委派树画出来，不是一串扁平日志：

- **委派开始**事件清晰标出
- 每个子员工显示**名字 / 层级深度 / 任务摘要**
- **完成徽标**：成功 / 超时 / 错误，外加耗时、内容长度
- 每个子员工有稳定的 **id + parentId + depth**，所以嵌套关系在时间线里一眼能看清谁派给了谁
- **计划面板常驻**——不再只有 Plan-and-Execute 模式才显示，委派树的进度也并入同一个面板

---

## 计划看板（Kanban）

::: tip 新增
`数字员工` 页头多了一个三段切换：**花名册 / 实时 / 计划看板**。计划看板把整个工作空间里员工跑出来的计划，按状态摊成一块看板，一眼看清谁在做什么、卡在哪。（仅管理员可见。）
:::

看板是 **Plan-and-Execute 计划**的全局视图，分四列，按计划状态自动归位：

| 列 | 含义 |
|----|------|
| **待执行** | 计划已生成，第一步还没开始 |
| **执行中** | 第一步已启动 |
| **已完成** | 全部步骤跑完 |
| **失败** | 有步骤失败且不再重试 |

布局是**泳道式**：每个有计划的员工占一行，按最近活动排序，顶部下拉可只看某一个员工。同一个目标的多次重新规划会折叠成**一张卡片 + ×N 徽标**，不会堆成一串。每张卡显示目标文字、进度条（已完成 / 总步数）、以及步骤分布芯片（N 待执行 / M 执行中 / K 已完成）。

看板是**只读**的——状态由执行驱动，不能拖拽。点一张卡，右侧滑出**计划详情面板**：受派员工、状态、KPI（步数 / 进度 / 创建日期）、执行产出（Markdown 渲染）、可展开的步骤时间线。顶部还有「目标」按钮，直接打开活跃[目标](./goals)列表。

REST：`GET /api/v1/plans?limit=N`（跨员工最近 N 条）、`GET /api/v1/plans?agentId=...`（按员工）、`GET /api/v1/plans/{id}`（含步骤详情）。

### 按步骤委派给专职员工

::: tip 新增
一个多步计划，不必由一个员工从头跑到尾。生成计划时，规划员可以把**单个步骤**指派给工作空间里更对口的员工去执行。
:::

机制是**自动的**，不需要手动配置：规划阶段，系统把工作空间里其他已启用员工（连名字带描述）摊给规划员看；规划员判断某一步明显属于某员工的专长时，就在计划里把那一步标给它，其余步骤留给自己。多数步骤通常不需要委派。

- 委派关系存在 `mate_sub_plan.assigned_agent_id`，计划详情面板的步骤下方会显示蓝色徽标 **「委派给 <员工名>」**
- 被委派步骤在**子会话**里执行，结果回流到主计划——这条子会话归属到原计划的对话之下，**不会**作为独立顶层会话泄漏进会话列表
- 步骤委派和[目标系统](./goals)、上面的[多级委派树](#多级子员工委派树)是一套语义：父员工拆活、专职员工干活

---

## 一句话造一支团队：数字员工搭建技能

::: tip 1.4.0 新增
不想一个一个手动建员工？给一句话，让"数字员工搭建"技能替你把整支团队搭出来。
:::

这个技能从你的一句话出发，走完整条链路：

1. **澄清需求**——先把模糊的一句话问清楚，确认你真正要解决的问题
2. **设计角色**——拆成 **2 到 6 个**互补的角色
3. **逐个创建**——对每个角色调用 `create_employee` 建出真实可用的员工
4. **串成工作流草稿**——把这几个员工链接成一条[工作流](./workflow)草稿，开箱即可调整

配套工具 **`list_capability_catalog`** 让技能先看清当前部署里有哪些工具 / 技能 / 知识库可用，再据此分配角色能力。创建出来的员工**默认即启用**，不用再手动开开关。

---

## 一句话创建员工向导（单个员工）

::: tip 新增
上面那条造的是**一整支团队**，走的是对话式技能。如果你只想要**一个**员工，又懒得逐项填表单，用列表页右上角的 **创建向导**：一句话描述，AI 把草稿生成出来，你改两下就上线。
:::

这是一个独立的三步 UI 向导（`数字员工 → 创建向导`），和上面的团队技能是两个东西——一个出团队、一个出单人，一个在聊天框里、一个是专门的页面。

1. **描述**——在输入框里用一句自然语言说清楚你要什么（"一个帮我盯竞品动态、每天写简报的运营助手"）。下方有示例 chip，点一下就填好
2. **确认**——AI 回来一份草稿：名字、头像 emoji、角色、目标、system prompt、类型（`react` / `plan_execute`）、推荐首问、标签，以及**建议绑定的工具 / 技能 / 知识库**。每个字段都能改，能力用可搜索的 picker 增删
3. **上线**——确认后一次性创建员工并完成工具 / 技能 / 知识库绑定，给你"开始聊天 / 再建一个 / 回列表"三个去处

**防幻觉**是这里的关键设计：AI 只能从你这套部署**真实存在**的能力目录里挑工具、技能、知识库——模型凭空编出来的工具名、技能 ID、KB ID 在生成阶段就被逐项反查丢弃，永远到不了向导界面。所以草稿里出现的每一项绑定都是当场可用的。

后端入口：`POST /api/v1/agents/generate`，请求体 `{ "requirement": "你的一句话" }`，返回一份校验过的草稿。

---

## 深度思考

不是所有问题都值得深度推理，但有些问题需要。MateClaw 支持按 Agent、按对话打开深度思考模式：

- **`thinkingLevel`**：`off` / `low` / `medium` / `high` / `max`
- 支持 Anthropic extended thinking、DashScope qwq 推理、OpenAI o1 `reasoning_effort=high`
- 思考块流式进入 UI，做成可折叠面板——你看得见模型怎么想，token 不会浪费在不需要推理的闲聊上

---

## 雇佣一个数字员工

`数字员工 → 新建`：

1. 选一个内置模板，或从自定义配置开始
2. 起名字，挑头像（像素艺术风格的库可选，或自己上传）
3. 写**角色 (Role)**——一句话；**目标 (Goal)**——一句话；**背景故事 (Backstory)**——几句话
4. 写一句**员工卡片标语 (Tagline)**——卡片上展示的"自我介绍"
5. 选类型（`react` 或 `plan_execute`）
6. 写或改 system prompt（角色 / 目标 / 背景故事会自动拼接进来，不用重复写）
7. 勾选它能用的工具，绑定它该读的知识库
8. 设置 `max_iterations`（默认 100）
9. 保存

立刻生效。从聊天 UI 或 API 开始用。

### 工具绑定（per-agent tool picker）

::: tip 1.3.0 新增
在 v1.2.0 时，员工的工具绑定是平铺的"勾哪个就能用哪个"列表。v1.3.0 把这块重做成**分组 + 状态感知 + 命名空间感知**的 picker，专门处理 MCP 工具的脏状态。
:::

打开数字员工编辑器的"工具"标签页：

- **按来源分组**：内置工具 / 技能注入工具 / MCP 工具（按 server 名再分组） / ACP 工具
- **状态徽标**：每个工具有一个标签——
  - `connected` —— 当前可用
  - `stale` —— 这个 MCP server 现在连不上，但绑定还保留（恢复连接后立即可用）
  - `unavailable` —— server / skill 已被禁用，绑定保留但运行时不会下发给员工
  - `orphan` —— **不存在**的工具引用（server 删了或 tool 改名了）；保存时会**拒绝**保留这种引用，强制清理
- **命名空间冲突**：两个不同 MCP server 提供同名工具时（比如两个都有 `read_file`），picker 显示完整 prefixed name（`server-a__read_file` / `server-b__read_file`）；员工的 system prompt 里把它们映射回原始名以避免混淆
- **保存时校验**：勾选的每个工具会跑 `AgentBindingService.validate(...)`——任何 orphan 引用直接报错，必须先去掉
- **MCP server 重命名**：原来挂在某 server 上的绑定**自动跟随**到新名字（按持久化的 tool cache 匹配），不需要手动重新勾

UI 入口：`Agents → 选员工 → 工具`。

技术细节见 [MCP](./mcp#per-agent-工具绑定)。

### 知识库绑定（per-agent 主知识库）

::: tip 1.5.0 新增
员工编辑器新增"知识库"标签页，可以为每个员工指定一个**主知识库**。知识库本身仍是工作空间共享资源，绑定只是声明"我默认查哪一个"——不影响其他员工的访问。
:::

**简单版本：每个员工可以指定一个"主知识库"作为它默认查的 KB。可以不指定。**

要点（这是设计模型，看完省得困惑）：

- **知识库是工作空间共享的。** 一个 KB 创出来就归属当前 workspace，workspace 里所有员工都看得见。给员工"绑"一个 KB 不会把它变成专属——其他员工照样能调
- **"主知识库"只是一个默认值。** 它告诉 wiki 工具（`wiki_search` / `wiki_read` / `wiki_backlinks` ...）："不显式说 `kbName` / `kbId` 时，默认去这个 KB"
- **多个员工可以选同一个 KB 作主库。** 互不影响，谁切谁的，KB 本身不动
- **不绑也行。** 没指定主库时，运行时按 workspace 里最近更新的 KB 兜底

UI 入口：`员工 → 选员工 → 编辑 → 知识库`。

| 选项 | 行为 |
|------|------|
| **🚫 未指定主库** | 清空绑定；下次员工的 wiki 工具不带 `kbName` 时，按 workspace 最近活跃 KB 回退 |
| **📚 <KB 名>** | 设这个 KB 为主库；之后 wiki 工具默认查它，列表上同时显示页面数 |

每个 KB 行展示：图标、名字、描述、页面数。列表内容就是当前 workspace 里所有 KB 的完整集合（包括已被其他员工选作主库的）。

#### 运行时怎么解析"该读哪个 KB"

员工调 wiki 工具时，解析顺序如下：

1. 工具调用显式带了 `kbName` / `kbId`——直接用那个
2. 没显式说 → 看员工的 `primaryKbId`，命中则用它
3. `primaryKbId` 也没有 → 在 workspace 可见 KB 集合里取最近更新的那个
4. workspace 一个 KB 都没有 → 工具返回空，员工 LLM 自己判断要不要换思路

迁移备注：早期版本的"绑定"是写在 `mate_wiki_knowledge_base.agent_id` 上的（一对一独占语义）。从 V130 迁移开始，所有老的 `kb.agent_id` 都被回填到 `agent.primary_kb_id`，老字段保留作 fallback 读取，但新的写入只走 `agent.primary_kb_id`。如果你之前依赖"KB 只给某个 agent 看"的隔离，请到员工管理面板重新审视一遍——KB 现在对 workspace 内全员可见。

#### 让某个员工彻底不碰知识库

::: tip 新增
"知识库"标签页顶部有个开关：**此智能体不使用任何知识库**。它和"工具禁用""技能禁用"是对称的三个 opt-out 开关。
:::

这里要分清两种"空"：

- **选择器留空** = "我没特别指定" → 运行时按**继承工作空间全部 KB**处理（默认行为）
- **打开这个开关** = "我明确不要任何 KB" → 运行时把该员工的可见 KB 直接判为**零**

打开后保存，员工的 KB 绑定被清空并标记为「显式无知识库」，标签页上出现「已禁用」徽标。效果：

- `wiki_read_page` / `wiki_search_pages` / `wiki_semantic_search` 等全系 wiki 工具一律返回 `"no knowledge base"`（工具还在工具集里，只是执行结果为空）
- webchat 的 `/wiki/pages` 端点对该员工返回空列表
- 知识库注入 / grounding 全部关闭

**默认关闭**，所有存量员工行为不变。开关可随时解除——只要回到 KB 选择器勾上任意一个知识库再保存，这个标志会自动清掉（非空绑定优先于 opt-out，避免状态矛盾）。

字段落在 `mate_agent.wiki_disabled`（V154 迁移，H2 / MySQL / KingbaseES 三套齐备）。

### System Prompt 最佳实践

System prompt 是数字员工的声音、优先级、约束的来源。**角色 / 目标 / 背景故事**和技能指令、工作空间记忆系统会自动拼接到最终 prompt 里——这些部分你不用自己写。

**你自己**的 prompt 应该包含：

1. **它该怎么说话**——语气、风格、措辞偏好（"专业但不死板" / "面向客户保持谨慎"）
2. **它被允许做什么、被期望做什么**——任务边界
3. **不确定时怎么办**——"先搜，不要编造" / "跑危险命令前问我"
4. **输出格式**——需要结构就明说

**不要**写的东西：

- 工具描述——会自动注入
- 工作空间记忆的使用说明——从 `AGENTS.md` 来
- 框架层的行为（工具调用格式、ReAct 结构）——别跟运行时对着干

示例：

> 你是一个专业的技术文档助手。你的职责：
>
> 1. 根据用户需求搜索并整理技术资料
> 2. 用清晰、结构化的方式回答问题
> 3. 确保代码示例语法正确
> 4. 不确定的时候先搜索，不要捏造
>
> 原则：
> - 引用外部信息时注明来源
> - 涉及时效性问题，先获取当前日期再搜索

---

## 给开发者：Agent 内部是怎么转的

只是用 Agent 的话，这一节可以跳。在它上面写代码（加节点、改路由、做扩展）的话，请直接看 [架构说明](./architecture)——StateGraph 拓扑、节点列表、共享状态 key、扩展点都在那一页。

---

## 生命周期状态

| 状态 | 含义 |
|------|------|
| `IDLE` | 等待输入 |
| `PLANNING` | 正在生成计划（Plan-and-Execute 模式） |
| `EXECUTING` | 正在执行工具调用或子任务 |
| `RUNNING` | 活跃的 ReAct 循环或 Plan-Execute 图执行中 |
| `WAITING_USER_INPUT` | 暂停，等用户响应 |
| `DONE` | 完成 |
| `FAILED` | 执行失败 |
| `ERROR` | 错误状态 |

回合的结束原因：

| 值 | 含义 |
|----|------|
| `NORMAL` | LLM 给出了直接的最终答案 |
| `SUMMARIZED` | 上下文压缩之后正常完成 |
| `MAX_ITERATIONS_REACHED` | 到达迭代上限被强制收敛 |
| `ERROR_FALLBACK` | 出错后降级的答案 |
| `INCOMPLETE` | 响应未完整完成，需要继续生成或重试 |
| `EVIDENCE_INSUFFICIENT` | 最终回答引用了未被工具结果验证的事实 |
| `STOPPED` | 用户主动停止 |
| `RETURN_DIRECT` | 带 `returnDirect=true` 的工具短路了循环，结果直接发给用户 |

---

## 可靠性机制

这些是运行时自己在做的事，目的是让 Agent 在你不想去 debug 的那种地方不脆弱：

- **上下文修剪**——上下文窗口快满时，早期轮次由 LLM 总结、摘要替换原文。缓存 30 分钟。摘要以用户消息形式注入，不是系统消息——防止历史内容被提升成系统级指令的注入风险。
- **结构化压缩（prompt 过长时）**——当模型返回"prompt 过长"时，运行时走一条四级递进的结构化压缩链：**软裁剪 → 硬清理 → 预修剪 → LLM 结构化摘要**。无论走到哪一级，都**永远保留前缀**——system prompt + 目标锚点不动；最终摘要以 UserMessage 形式注入。委派工具的返回结果**永远不会被压缩**（它们是子员工的成果，丢了就找不回来）。PTL 紧急压缩后有 **1 分钟冷却**，避免在同一个超限回合里反复硬调 LLM。
- **思考恢复**——流式中途断了，已经写出的思考和内容会持久化，会话重载时还在。
- **迭代上限处理**——到达 `max_iterations` 不会崩溃，而是强制让 LLM 用现有信息生成一个尽力而为的总结答案。
- **僵尸流清理**——后台跟踪每一个打开的 SSE 流，被遗弃的会被自动回收。
- **429 重试**——LLM 限流错误会触发带退避的自动重试。
- **重复检测**——抓住那些反复在同一个工具调用上打转的 Agent，强行把它拉出循环。
- **停滞检测 + 重新规划**——Plan-Execute 模式下，某一步抛异常或在工具内循环里反复失败时，运行时会清掉当前计划、带着失败原因回到规划节点**重新规划**，绕开坏掉的那一步，而不是带着垃圾结果硬推下去。详见[目标 · 停滞检测与重规划](./goals#停滞检测与重新规划)。
- **目标硬延续**——锁了目标的员工撞到迭代上限时，可以**续一次满额迭代**接着干，而不是停在那里等你再发消息。详见[目标 · 硬延续](./goals#撞到迭代上限的硬延续)。
- **工具超时可配置**——一个慢工具不会冻结整个回合。
- **渠道健康监控**——失败的渠道适配器走指数退避重启。

这些没有一个是用户面的按钮。它们就自己在发生。

---

## Agent 管理 API

### 创建

```bash
curl -X POST http://localhost:18088/api/v1/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "技术助手",
    "description": "专业的技术文档助手",
    "agentType": "react",
    "systemPrompt": "你是一个专业的技术文档助手...",
    "maxIterations": 10
  }'
```

### 列表 / 获取 / 更新 / 删除

```bash
curl http://localhost:18088/api/v1/agents -H "Authorization: Bearer YOUR_JWT_TOKEN"
curl http://localhost:18088/api/v1/agents/1 -H "Authorization: Bearer YOUR_JWT_TOKEN"

curl -X PUT http://localhost:18088/api/v1/agents/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"name":"技术助手 v2","maxIterations":15}'

curl -X DELETE http://localhost:18088/api/v1/agents/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### 流式对话

```bash
curl -N "http://localhost:18088/api/v1/agents/1/chat/stream?message=你好&conversationId=default" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

---

## 调试

在 `application.yml` 里打开 DEBUG 日志：

```yaml
logging:
  level:
    vip.mate.agent: DEBUG
    vip.mate.agent.graph: DEBUG
```

你会看到节点一节点的执行过程：状态切换、dispatcher 路由决策、迭代数、工具调用参数和结果摘要、Tool Guard 检查结果。

### 常见问题

| 症状 | 可能原因 |
|------|----------|
| Agent 不响应或超时 | 模型配置错、API Key 无效、额度用光 |
| Agent 卡在循环里出不来 | `max_iterations` 太低，或者某个工具反复报错 |
| `MAX_ITERATIONS_REACHED` 经常触发 | 调 system prompt 或者把上限调高 |
| 工具调用悄悄失败 | Tool Guard 在拦——看 `mate_tool_guard_audit_log` |
| 等审批的图恢复不了 | `chatWithReplay` 里 `toolCallPayload` 格式对不上 |

---

## 下一步

- [工具系统](./tools)——Agent 能调用什么
- [技能系统](./skills)——怎么扩展 Agent 能做的事
- [LLM Wiki](./wiki)——知识怎么被 Agent 读到
- [记忆系统](./memory)——Agent 怎么跨会话记住东西
- [工作流](./workflow)（1.3.0+）——把多个数字员工 + 系统动作编排成一条业务流程
- [触发器](./triggers)（1.3.0+）——让事件自动启动工作流或员工对话
- [架构说明](./architecture)——StateGraph 运行时深入