Agent 就绪度

AuraBoot 的设计目标是:让 AI Agent 通过与人类完全相同的执行契约作用于业务,而不是通过另一条更弱的、自由文本式的旁路。本页解释让这条契约 AI-safe 的设计选择,以及 Agent(或者写 Agent 的开发者)应该如何在这条契约上推理。

如果你要找的是把这条契约暴露给 Agent 的运行时接口,请看 MCP 与工具、Agent Builder、Aura Bot 与 ACP 协议。本页是这些运行时下沉的概念页。

为什么 AI Agent 需要一条不同的调用面

把"一个 API token + OpenAPI spec"丢给一个通用 LLM Agent,它在企业系统里能造成的损失并不抽象,而是几条性质的必然推论:

1. 爆炸半径不可控。 REST 端点通常接受调用方能拼出来的任意字段组合,没有任何地方声明"这个调用会写入总账"或"这个调用无法撤销"。一个会幻觉参数的 LLM、或在瞬时超时上自动重试的 LLM,会愉快地触发一次不可逆的跨对象写入,因为没人告诉它不能。
2. 没有声明语义。 POST /orders 这种 OpenAPI summary 并不告诉 Agent:这是写、它在自然键上不幂等、提交两次会生成两份库存预留、撤销要走另一个有不同权限的端点。
3. Agent 本身没有审计身份。 当模型用 token 调端点时,审计写的是"用户 X 做了某件事",并没有"用户 X 其实是一个代表用户 X 的 Agent"、"这是哪个 prompt 触发的"、"这属于哪一次会话"的记录。

正确答案不是给 REST 层再加一层护栏。正确答案是暴露一条以受治理业务命令为最小动作单位的调用面,声明足够多的元数据,让 Agent 能推理是否该调、是否该重试、是否该升级到人。这条面就是 AuraBoot 叫的 Agent Readiness。

对比的形状:

下面逐行解释每一行是怎么被交付的。

第二个推论是 Agent 面与人类面同步演化。插件新加一条命令,同一天就既能由人在页面设计器里调,又能由 Agent 在工具目录里调,没有额外的"暴露给 AI"环节。四个声明字段是命令编写流程的一部分,而不是下游补丁。

第三个推论是契约可移植。无论 Agent 跑在 AuraBoot 部署内部(Aura Bot、Agent Builder 编写的 Agent)、还是经 MCP 从外部接入、还是经 ACP 调到另一个 AuraBoot 部署,看到的词汇都一致:cmdCode、agentHint、riskLevel、idempotent、reversible、inputSchema。没有任何 Agent 运行时看到的是另一种形状。

Command 是 AI-safe 的执行单元

AuraBoot Agent Readiness 故事里最重要的一条设计决策是:Agent 没有私有执行路径。当 Agent 调 expense.report.submit 时,这个请求走的是和同一条命令从 Web UI、工作流任务、移动端发起时完全相同的 Pipeline。Pipeline 细节见 Command Pipeline;对 Agent 来说重要的是这条结构给出的保证。

保证是:无论调用方是人、Agent 还是工作流,以下阶段都按顺序跑:

1. Load 已发布的命令定义。草稿与已删除的 Command 不可调。
2. Schema 校验 payload 是否符合命令的 inputSchema。幻觉字段在这里被拒,不会等到写入后才暴露。
3. 幂等检查。 命令声明 idempotent: true 且请求带幂等键时,重复请求返回原结果而不重跑。
4. Entitlement 检查。 特性开关、License 校验在任何业务逻辑之前。
5. 职责分离 (SoD)。 同一用户不能既提交又审批,无论权限怎么发。
6. 状态守卫。 生命周期迁移由状态图执行,不由调用方决定。
7. 断言、不变式、跨字段校验。 写入前后的前/后置条件。
8. Field map 与 Handler。 真正的写或 handler 逻辑,在事务里。
9. Side effects、Roll-ups、Post-actions。 全部在事务边界内。
10. Effect、审计、变更追踪。 审计记录与写入同一次 commit。
11. Domain events、API call、Webhook。 在事务成功提交之后。

因为 Agent 永远不被允许跳过这些阶段,Agent 调入时系统的安全属性不会变弱。一个被指令"尽快提交五份报销单"的 Agent 无法绕过 SoD、无法跳过审批工作流、无法在命令声明幂等的情况下因重试而重复写入、无法生成隐藏"谁做了什么"的审计。

事务边界值得专门强调。每一个状态变更阶段 —— FIELD_MAP、COMPUTED_FIELDS、CHANGE_TRACKING、HANDLER、SIDE_EFFECT、ROLL_UP、POST_ACTION、EFFECT、POST_INVARIANT —— 都跑在同一次数据库事务里。任意一个失败时,全部回滚,审计记录也一起回滚。只在 commit 成功之后才能跑的阶段(DOMAIN_EVENT、API_CALL、WEBHOOK、GOVERNANCE_SNAPSHOT)跑在事务之外。这意味着 Agent 一次失败的调用不会留下半写的数据、不会留下孤立的审计行、不会泄漏出去的 webhook。要么整次调用生效,要么完全没生效。

反方向同样成立:Agent 一次成功的调用,审计不会在重试时被悄悄丢掉。审计行与数据写入处于同一次 commit,数据库保证它们同生共灭。

阶段拒绝时 Agent 看到的是什么

Agent 调命令收到的结构化错误带有拒绝它的阶段名与结构化原因,词汇稳定:

• schema_validate —— payload 形状错了。Agent 应该修正参数。
• idempotency_check —— 与一个在途请求重复。Agent 应该等待并重读状态。
• entitlement_check —— 当前租户未授权该 feature。Agent 不应重试。
• sod_check —— SoD 不允许该用户在该记录上做该动作。Agent 应升级到另一个用户,而非重试。
• state_check —— 目标记录所处状态下,此命令不合法。Agent 应先回读记录状态再继续。
• assert / pre_invariant / post_invariant —— 一条业务规则失败。Agent 应把规则信息汇报给用户,不重试。

返回阶段名给 Agent 推理回路的东西远比"HTTP 400"更有用。它支持像"state_check 失败时,先取当前状态再回复用户"这种提示,这比"任何错误都重试"是好得多的恢复回路。

四个声明字段

每一条 CommandDefinition 都自带四个一类字段,Agent 在决定是否调用以及如何调用之前会读它们。这些字段存在命令上、通过 MCP tool 描述符暴露、也在产品内的 Agent 运行时暴露。

agentHint

一句简短的、自然语言的业务意图描述,写给 LLM 读者,不是给开发者读的。它不是 API 文档,它回答的是"如果要用一句话告诉一个 Agent 何时该调这条命令,你会怎么说?"

示例:

这条提示会被渲染进每一份 MCP tool 描述符以及每一次产品内 tool 注册。一个合格的 agentHint 对减少幻觉调用的作用比任何其他单一干预都大。

写好 agentHint 的纪律:

• 用目标用户实际使用的自然语言写,不要用产品行话。
• 写出人在点按钮前会检查的前置条件。
• 如果有配对的撤回/取消命令,直接写在里头。
• 不要重复参数 schema —— 那已经在 inputSchema 里。
• 不要描述实现 —— Agent 不需要知道哪个 handler 跑。

riskLevel

对操作影响的分级,平台用五级:

Agent 应把这五级视作确认梯度:L0 和 L1 可作为 Agent 正常推理的一部分直接调用;L2 应在调用前向用户简要汇报;L3 与 L4 必须在同一轮里取得用户明确确认。

这套分级故意是粗的。五级足够把"可以放手"、"要先汇报"、"要明确确认"三档分开;更细的分级反而会引出"某条命令属于哪个细类"的争论而不会改变 Agent 的实际行为。分级在命令定义里一次性写好,作者就是写 handler 的同一个人。

idempotent

布尔。声明用同一 payload(且同一幂等键)重跑是否产生相同的业务状态。Agent 和客户端用它决定重试策略:

• idempotent: true — 命令可在瞬时失败时重试。Pipeline 的幂等阶段会为重复请求返回原结果。
• idempotent: false — 命令禁止自动重试。Agent 应该重新问用户,或者先回读下游状态,再决定是否再发一次。

大多数读是幂等的。大多数提交、迁移、对外分发都不是。

reversible

布尔。声明是否存在一条配对命令可以撤销其效果。可逆性是业务域的属性,不是数据库的属性 —— 它说的是"如果用户反悔了,有没有一条文档化的命令可以让事情回到原状?"

reversible: true 通常和同级命令的 agentHint 配套:

{
  "cmdCode": "expense.report.submit",
  "reversible": true,
  "agentHint": "提交已起草的报销单。终审之前可通过 expense.report.recall 撤销。"
}

reversible: false 意味着 Agent 必须在调用前获得用户明确确认,即使用户在同一次会话里已经批准过相似调用。

不可逆命令之间不传递同意,理由很直接:不可逆动作按定义是用户最后一次能改主意的点。会话早些时候给过的"统一同意"不能代替"对这条特定不可逆动作的此时此刻同意"。

这里也有文档效应。把 reversible: true 与撤回命令的 cmdCode 一起写进 agentHint,让安全网可被发现。知道撤回命令存在的 Agent 可以放心提交;不知道的(正确地)更保守。

工具暴露

这四个声明字段就是命令变成Agent 可调工具的入口。机制细节见 MCP 与工具;摘要:

平台的 DslToolProvider 会遍历当前调用用户有权调用的所有已发布命令,逐条生成 tool 描述符,暴露:

• cmdCode —— 作为稳定的 tool 名。
• displayName —— 作为对人友好的 label,已本地化。
• agentHint、riskLevel —— 作为结构化元数据直接随 tool 描述符暴露,Agent 可基于它推理。idempotent、reversible 同样在命令上声明,经能力视图(Capability View)层导出给 Agent。
• inputSchema —— 命令的 JSON Schema,直接作为 function-call schema。必填、枚举、format 约束、描述全部透传。
• requiredFeature —— 在有 entitlement gating 时出现,用于过滤目录。

不暴露的部分:

• Handler 类名、Spring bean wiring、内部 SPI 实现细节。
• 20 阶段 Pipeline 的配置。Agent 看到的是命令,不是编排。
• 其他租户的命令。目录天然是按租户切的。
• 调用用户无权调用的命令。Agent 不会看到自己调不动的 tool。

结果是一个小、强类型、语义化的目录,而不是一片摊开的 REST 表面。无论 Agent 是经 MCP、ACP、还是产品内 Agent Builder 接入,看到的形状一致。

目录过滤

Agent 看到的目录是以下集合的交集:

• 当前租户已发布的命令。
• 命令所需 feature(如有)在当前租户已授权。
• 调用用户被授予了命令所标注的权限。
• 命令的目标 model 在用户的数据域与组织域内。

这个交集在 Agent 的工具清单物化时计算。Agent 永远不会看到一条原则上无法调用的 tool。推论是:你可以通过修改用户的权限来收紧 Agent 的有效面,而不必维护一份与权限并行的 Agent allow-list。

MCP tool 描述符长什么样

{
  "name": "expense.report.submit",
  "description": "提交报销单 —— 把已起草的报销单提交给经理审批。员工确认金额并附上发票后使用。终审之前可通过 expense.report.recall 撤销。",
  "inputSchema": {
    "type": "object",
    "required": ["operationType", "targetRecordId"],
    "properties": {
      "operationType": { "type": "string", "enum": ["UPDATE"] },
      "targetRecordId": { "type": "string", "description": "要提交的草稿单 ID。" }
    }
  },
  "annotations": {
    "auraboot.riskLevel": "L2",
    "auraboot.idempotent": false,
    "auraboot.reversible": true
  }
}

annotations 块是四个声明字段对 Agent 的机器可读副本。自然语言提示被合并到 description 里,这样只消费标准 MCP 字段的 LLM 也能拿到。

实例:Agent 提交一份报销单

为了把规则落到具体动作,以下是 Agent 收到"提交我十月出差报销"指令时的判断流。

第 1 步:在工具目录里搜索。

Agent 找到两条相关命令:

{
  "cmdCode": "expense.report.submit",
  "displayName": "提交报销单",
  "agentHint": "把已起草的报销单提交给经理审批。员工确认金额并附上发票后使用。",
  "riskLevel": "L2",
  "idempotent": false,
  "reversible": true
}

{
  "cmdCode": "expense.report.recall",
  "displayName": "撤回报销单",
  "agentHint": "撤回一份在途的报销单让提交人重新编辑。终审之前有效。",
  "riskLevel": "L1",
  "idempotent": true,
  "reversible": false
}

第 2 步:基于风险推理。

riskLevel: L2 意味着这次写动了多条记录(单据头、明细行、工作流实例)。Agent 决定在调用前向用户简要汇报计划。

第 3 步:基于幂等性推理。

idempotent: false 意味着 Agent 禁止在超时时悄悄重试。如果调用失败,Agent 先回读报销单状态再决定下一步。

第 4 步:基于可逆性推理。

reversible: true,配对命令 expense.report.recall 可用,告诉 Agent 一次诚实的失误是可以恢复的。Agent 不必再要一次确认;一次就够。

第 5 步:调用。

Agent 用单据的 targetRecordId 和正确的 operationType(UPDATE,因为命令在迁移一条已有记录)调用 expense.report.submit。Pipeline 跑完 20 阶段。审计落库。Commit 后 domain event 触发审批工作流。

第 6 步:处理失败。

如果 Pipeline 拒绝调用 —— 比如状态守卫拒绝迁移,或 SoD 不允许 Agent 的用户提交一份自己之前审批过的单 —— Agent 收到带阶段名和原因的结构化错误,如实把原因汇报给用户,而不是重试。

整条序列不依赖任何 Agent 特有代码。无论调用来自 MCP、ACP、产品内 Agent 还是 Web UI 的"提交"按钮,流程都一样。

反例:没有声明字段会出什么事。

设想同一个 expense.report.submit 暴露成裸 POST /api/expense-reports/{id}/submit。Agent 只读到 POST、一个 path 和一份 JSON schema。它没有信号说这条调用是 L2(所以不会在调前汇报);没有信号说它非幂等(所以超时就重试,产生重复提交和重复工作流实例);没有信号说有撤回命令(所以反悔的用户让 Agent"撤"时,Agent 会去猜一个并不存在的 DELETE)。每一种失败模式都被"加三个布尔 + 一句提示"关掉 —— 这正是四个声明字段所编码的交换。

权限继承

AuraBoot 里的 Agent 代表用户行事。它没有自己的权限集。当用户 Alice 打开产品内 Agent 会话并让它提交一份报销时,产生的命令调用会把 Alice 的身份带进认证与授权阶段。Agent 做不了 Alice 做不了的事。

这点由三层强制保证,与人类用户走的是同一三层(见 权限):

1. 第 1 层 — 权限。 Alice 的角色是否被授予 expense.report.submit 的权限?如果不是,授权阶段直接拒,Agent 的目录里压根看不到这条命令。
2. 第 2 层 — 数据域。 命令可以触及的记录里,Alice 能看到哪些?这一层在写之前先剪掉候选集。
3. 第 3 层 — 组织域。 如果 Alice 在 Org A,目标记录属于 Org B,即使第 1 层权限齐备,也在这层被拒。

这三层里没有任何 Agent 专用旁路。没有任何"服务账号模式"让"Agent"独立于用户拥有更高权限。跨租户操作对 Agent 的拒绝方式和对人类完全相同,都是在第 3 层。

实际后果是 Agent 永远不可能比它代表的用户更强大,所以约束 Agent 最稳的办法就是约束它跑在哪个用户身上。只读审计 Agent 跑在只读用户上;一线支持 Agent 跑在支持账号上;监管面 Agent 跑在监管账号上。

这也顺手解决了一类否则会很难答的治理问题。"Agent 能不能看这条记录?"还原成"该用户能不能看这条记录?"。"Agent 能不能删这个客户?"还原成"该用户能不能删这个客户?"。用户访问控制就是 Agent 访问控制。合规团队已经批过的用户模型,不必再批一份平行的 Agent 模型。

也意味着撤 Agent 访问权与撤用户访问权是同一个动作。停用用户即停用代表它的 Agent。轮换用户角色,在 Agent 下一次工具目录物化时生效。

审计与可追溯

每一次命令调用都会在执行写入的同一个数据库事务里产生一条审计记录。对人是这样,对 Agent 也是这样。Agent 的不同之处在于:审计记录额外捕获 Agent 这一层:

• 用户身份 —— Agent 所代表的人。
• Agent 身份 —— 当时激活的 Agent 定义、它用的模型与版本。
• Prompt 来源 —— 触发本次调用的会话或触发器。
• 审批用户 —— 当不可逆/高风险命令需要用户确认时,实际给出确认的那个用户。

审计员拿到的是可查询面(支撑产品内审计视图的同一审计 API),而不是一堆聊天 transcript。"上季度 Agent 调过哪些触动总账条目的命令"、"其中哪些是 L3/L4"、"哪些要求并取得了用户审批"这类合规问题,可以作为 SQL 或审计 UI 的筛选答上来。

因为审计与命令的事务在同一次 commit 写入,它不会和写漂移。不会出现"审计写了但写入回滚了",反之亦然。

一行典型审计记录,概念上:

对 L4 命令,approvedBy 必填,缺失时 Pipeline 拒绝。对 L0/L1 的 Agent 调用,approvedBy 为 null,但记录里仍带 Agent 身份与会话。所以审计日志一次查询就能同时回答"Alice 批准过什么?"和"她的 Agent 没问她就做了什么?"。

与 BPM 的集成

命令调用面也是 AuraBoot 的工作流引擎与 Agent 层相会的地方。

• Agent 触发工作流。 任何会发 domain event 的 Command 都能触发工作流。Agent 调 expense.report.submit 间接启动了审批流,是因为工作流订阅了"提交事件",不是因为 Agent 直接调了工作流。
• Agent 被分派工作流任务。 工作流任务可以建模成一个 service task,解析到一条 Command。Agent 接手任务时调的就是人类用户在该步骤本来要调的同一条命令,权限、风险、审计语义完全一致。
• 工作流可以基于 riskLevel 分支。 一个常见模式:在工作流里建一条"Agent 协助"分支,下一个 service-task 命令若声明 L3/L4 或 reversible: false,强制人类显式审批;较低风险的步骤允许自动执行。

契约端到端保持:工作流任务是命令,Agent 接任务是命令调用,审计记录捕获三层身份。

一个具体的 BPM 模式:"低风险步骤 Agent 推进、不可逆步骤人在环"

Agent 辅助工作流里有一个常见模式:让 Agent 在低风险步骤推进流程,在高风险步骤停下来等人显式审批。形状:

1. 工作流定义一连串 service task,每个解析到一条 Command。
2. 每个 service task 之前有一个 script task,读下一条命令的 riskLevel 与 reversible。
3. 下一条命令是 L0/L1/L2 且 reversible: true,工作流自动推进,Agent 执行。
4. 下一条命令是 L3/L4 或 reversible: false,工作流插入一个 user task 分派给人在环。Agent 等待。
5. 在最终的命令调用上,审计记录就这次工作流实例上这条 user task 的人类审批写下来。

这套模式完全在工作流配置里实现。平台不需要专门的"Agent mode"工作流类型。

Agent 不应被允许做的事

Agent Readiness 既是关于授权,也是关于明确禁止。以下事情不是 AuraBoot 中合法的 Agent 行为,无论 Agent 怎么构建、部署在哪:

• 不带用户审批就调用不可逆高风险命令。 Agent 持有 riskLevel: L4 或 reversible: false 的 tool 描述符时,必须在同一轮里取得用户明确确认才能调。会话早些时候给过的确认不能转给一条新的此类命令。
• 跨租户操作。 Agent 的用户属于某个租户,跨租户在第 3 层被拒。没有 Agent-mode 的逃逸通道。
• 用 raw SQL 或直接走 repository 绕过 Pipeline。 给"Agent"开后门的 Plugin 代码是平台反模式,Pipeline 是唯一合法的写路径。
• 跳过审计。 任何 Agent 运行时、任何 MCP tool、任何 ACP handler 都不得抑制审计记录。审计与命令事务同 commit 写,不能被 opt out。
• 自我提权。 Agent 不得在会话中途调管理命令为自己的用户拓宽权限。
• 伪造审批用户。 命令要求用户审批时,审批用户只能是真实点了确认的那个人,而不是 Agent prompt 里写的那个人。

这些是平台属性,不是 prompt 属性。被指令"你可以跳过审批"的 Agent 依然跳不过去,因为禁止条款住在 Command Pipeline 里,而不是住在 Agent 指令里。

平台禁止 vs prompt 禁止这条区分是承重的。prompt 级禁止是对模型的请求,现代 LLM 越来越擅长遵守它,但它不可执行。平台级禁止不是请求,它是无论上面挂哪个模型、哪个厂商、哪个 prompt,系统都不会跌穿的地板。四个声明字段加 20 阶段 Pipeline 一起,就是这块地板。

设计新命令时一个有用的自检:如果一个恶意或糊涂的 Agent 用任意参数全速调这条命令,最糟会发生什么? 如果答案涉及"跨租户数据丢失"或"不可恢复的财务影响"或"无审计的合规违规",那这条命令还不是 Agent-Ready。补救通常是其中之一:把 riskLevel 上调一档强制确认;标 reversible: false 并配对撤回;收紧权限让更少用户(因此更少 Agent)能调;或把高风险路径推到一个带强制 user task 的工作流后面。

同一条自检也适用于第一次为某租户开启 Agent 运行时的既有命令。Agent 看到的目录正是用户在 UI 里已能调的目录。如果目录里有任何不该暴露给 Agent 的,它在 UI 里也同样不该暴露 —— 补救做在命令上,不做在 Agent 上。

:::note[企业版:Agent Control Plane] OSS 调用面已经给单租户一条 AI-safe、可审计的 Agent 契约。企业版在此之上加 Agent Control Plane:跨租户 Agent 编排、独立于人类账号的 Agent 身份发放、风险分级审批闸门的审计回放、按 Agent 的 token 与成本预算上限、多 Agent 协作、prompt provenance 签名(让审计记录可以基于产生它的精确 prompt 与模型版本回放)。本页之上的契约不变 —— Agent Control Plane 是搭在它之上的治理与运维层。 :::

编写命令的清单

新加一条命令、想让它第一天就 Agent-Ready,逐条过这份清单:

1. 先把 displayName 与 description 写给人看。 它们会进入 Agent 的 prompt,把它们当文档,不当样板。
2. 写一句 agentHint。 写清业务意图与人在点按钮前会检查的前置。
3. 设 riskLevel。 默认比"感觉"再上调一档。Agent 会在调前汇报,多一次汇报代价低,捕获一次失误收益高。
4. 诚实标 idempotent。 两次相同调用产生两个不同业务结果(两笔预留、两封邮件、两条总账)的,就不是幂等,必须如实标。
5. 决定有无配对撤回。 有就 reversible: true 并在 agentHint 里点名;没有就 reversible: false,并思考是不是应该有。
6. inputSchema 写紧。 必填就是必填;能用枚举就用枚举;每个属性都加描述。schema 是 Agent 唯一的结构化调用指引。
7. License 命令记得设 requiredFeature。 Agent 只在已授权租户里看到它。
8. 谨慎选权限码。 它是目录闸门。高风险命令配过宽权限,会悄悄抬高 Agent 的面。
9. 加一份样例 payload。 exampleInput 会被 tool provider 与产品内浏览命令的人同时消费。
10. 跑一次干式 Agent 调用。 开 Aura Bot,用自然语言提出该动作,确认 Agent 找得到并调起。找不到,就是 agentHint 写错了。

十条都过,这条命令就能被人、Aura Bot、Agent Builder 写的 Agent、外部 MCP 客户端、ACP 对端同样安全地调用,不需要任何按通道额外加的管道。

下一步

• Command Pipeline —— 每次 Agent 调用都走完的 20 阶段执行契约。
• 权限 —— Agent 从用户继承的三层权限模型。
• MCP 与工具 —— 命令如何作为 MCP tool 暴露给外部客户端。
• ACP 协议 —— AuraBoot 部署之间的 Agent-to-Agent 调用。
• Agent Builder —— 在此契约上编写产品内 Agent。
• Aura Bot —— 已经跑在这条契约之上的平台默认 Agent。