Skip to content

多智能体引擎

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

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

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

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


一个数字员工有什么

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

注意一个没有的东西:模型。整个 MateClaw 部署里只有一个全局默认模型(在 设置 → 模型 里设置),所有 Agent 在运行时用的都是它。Agent 行上那个 model_name 字段是历史遗留——被忽略。这是刻意的:换模型是整个部署一次点击的事,不是三十次。


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

你不是从一张白纸开始。数字员工 → 新建 打开一个模板选择器。里面有两层:

5 个职业模板(推荐)

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

  • 产品研究员——竞品调研、市场动态追踪、用户访谈整理
  • 客户支持——接住客户问的事、查知识库、把不能解决的升级出去
  • 知识管理员——把零散材料整理进 LLM Wiki、维护双向链接、定期归纳
  • 数据分析师——查数据源、跑 SQL、出图表、写结论
  • 行政助理——日程、邮件草稿、跨工具协调

通用模板(白纸或半成品)

  • 通用助手——默认的聊天员工
  • 研究 / 代码 / 写作 / 知识策展 / 数据分析——按用途分类的半成品
  • 自定义——彻底白纸一张,知道自己要什么就选这个

选一个,给它起名字、调一下角色和目标,保存。一分钟以内就有一个能上岗的同事。 创建之后每一项都能改。


两种思考方式

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 回复。三路并行,结果汇总给编排者。

多级子员工委派树

1.4.0 新增

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

三个委派工具,覆盖三种节奏:

  • delegateToAgent —— 同步委派。把一个子任务交给指定员工,等它跑完、拿到最终结果再返回。可选 inheritParentContext:把父会话最近的上下文一起带给子员工,省去重复交代背景。
  • delegateParallel —— 扇出委派。同时派给多个子员工,各自在隔离会话里跑,结果统一收集回来。
  • delegateAsync —— 后台委派。立刻返回一个 task_id,子员工在后台跑;之后用 taskOutput 取结果。taskOutput归属闸门——只有最初发起委派的同一个会话 + 同一个用户才能读到结果,防止跨会话/跨用户泄露。

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

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

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

委派和目标系统配合使用——父员工定目标、拆任务、把子任务委派下去,子员工专注执行。

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

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

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

计划看板(Kanban)

新增

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

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

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

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

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

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

按步骤委派给专职员工

新增

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

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

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

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

1.4.0 新增

不想一个一个手动建员工?给一句话,让"数字员工搭建"技能替你把整支团队搭出来。

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

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

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


一句话创建员工向导(单个员工)

新增

上面那条造的是一整支团队,走的是对话式技能。如果你只想要一个员工,又懒得逐项填表单,用列表页右上角的 创建向导:一句话描述,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、按对话打开深度思考模式:

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

雇佣一个数字员工

数字员工 → 新建

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

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

工具绑定(per-agent tool picker)

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

知识库绑定(per-agent 主知识库)

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 内全员可见。

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

新增

"知识库"标签页顶部有个开关:此智能体不使用任何知识库。它和"工具禁用""技能禁用"是对称的三个 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 的话,这一节可以跳。在它上面写代码(加节点、改路由、做扩展)的话,请直接看 架构说明——StateGraph 拓扑、节点列表、共享状态 key、扩展点都在那一页。


生命周期状态

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

回合的结束原因:

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

可靠性机制

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

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

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


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
等审批的图恢复不了chatWithReplaytoolCallPayload 格式对不上

下一步

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