很多团队把多 Agent 当作系统复杂度上升的起点，却低估了单体 Agent 一旦接入真实工具、跨会话状态和外部副作用之后，同样会变成一个需要严肃运行时治理的生产系统。问题往往不是“只有一个 Agent，所以简单”，而是“只有一个 Agent，却要独自决定什么时候调工具、如何解释结果、何时重试、何时写状态”，于是原本靠提示词勉强维持的边界开始迅速失效。
OpenAI Agents SDK 的 tools 与 running agents 文档，以及 LangGraph 关于 persistence 的设计，都在强调同一个事实：只要 Agent 要调用工具并跨步骤运行，就必须把工具输入输出、执行边界、状态持久化和恢复策略显式写成契约。对 TaskPilots 来说，这对应的不是多 Agent 编排，而是单体 Agent 运行时本身要有清晰的工具注册表、状态模型、会话边界和适配层，避免系统继续把关键控制点埋在自然语言里。
为什么这个问题重要
单体 Agent 的工具调用本质上已经是运行时集成
只要 Agent 能调用检索、邮件、CRM、数据库或工单工具，它就不再只是“会回答问题的模型”，而是在驱动一组真实系统接口。此时每次工具调用都带着参数约束、权限边界、超时处理、错误返回和后续状态更新。如果这些内容没有被显式定义，系统就会把“怎么调工具”这个关键问题交给模型临场发挥，结果通常是同一个任务在不同上下文里触发不同调用方式，排障和回归都会变得非常困难。
- 没有工具契约时，模型可能用错误字段名、错误单位或错误顺序调用接口。
- 没有状态边界时，一次成功调用可能在下一轮会话里被错误重放或错误引用。
- 没有运行时约束时，失败恢复会退化成“再试一次”，而不是基于上下文做安全决策。
如果继续靠提示词硬扛，最先坏掉的是可控性
生产环境里最常见的误区，是认为“只有一个 Agent，所以不用上太多运行时结构”。实际上单体 Agent 更容易把所有逻辑糅在一起：提示词里既写工具说明，也写权限边界，还写失败处理和状态规则。短期看似省事，长期则会在三个地方率先暴露问题。第一，工具结果没有被结构化校验，Agent 会把不完整结果当成可执行结论。第二，长会话或跨会话运行时，旧状态和新输入容易混在一起。第三，重试逻辑缺乏幂等约束，重复执行会把一次小故障放大成真实业务事故。
适用场景
哪些团队最需要这套方法
这套方法最适合仍处在单体 Agent 阶段，但已经开始接工具、写状态、跨轮执行和承担业务结果的团队。典型场景包括内部运营助手要查询并更新 CRM、客服代理要先检索后生成回复草稿、审批助手要在多轮确认后提交结果、以及自动化工作台要在不同会话里延续任务上下文。此时虽然系统还没进入多 Agent 编排，但运行风险已经明显超出“单次问答”范畴。
如果你的 Agent 已经需要在会话之间保存任务状态、根据工具返回决定后续动作、或者把一次失败恢复成可继续执行的流程，那么显式工具契约和状态层就应该被视为基础设施，而不是“等以后复杂了再说”。
什么时候可以先不做重型运行时
如果当前系统仍是只读型问答、无外部写操作、无跨会话延续、无高价值结果承诺，那么确实可以先从轻量约束做起，例如只定义工具 schema、基础超时和最小日志，而不必立刻引入完整的状态快照与恢复框架。关键判断标准不是 Agent 的数量，而是任务是否已经出现真实工具副作用、可恢复需求和状态一致性要求。只要这三项都还没有出现，就可以先控制复杂度。
推荐系统结构
先把工具注册表和执行契约定清楚
更稳的单体 Agent 结构，第一层应是清晰的工具注册表。每个工具都应显式定义用途、输入 schema、输出 schema、允许调用者、超时、重试策略、幂等要求和失败分类，而不是只给模型一段“你可以使用某某工具”的自然语言说明。这样做的好处有两个：一是模型调用前后都有稳定边界，二是运行时可以对工具结果进行结构化校验，避免把异常返回误当成功结果。
- 输入契约决定模型可以传什么，而不是让参数随上下文漂移。
- 输出契约决定系统如何解释结果，而不是让模型自己猜测返回含义。
- 失败契约决定何时重试、何时中止、何时转人工，而不是所有异常都走同一路径。
把状态快照、会话模型和 MCP 适配分层处理
第二层应是状态层。LangGraph 对 persistence 的强调值得借鉴的地方，不是某个具体实现，而是把会话状态、检查点和恢复点明确成运行时能力。单体 Agent 也应该至少区分三类状态：短期会话上下文、可持久任务状态、以及工具执行证据。前者服务当前推理，后两者用于跨轮延续、失败恢复和审计。再往下，工具接入层可以统一通过本地工具封装或 MCP 适配，把外部接口差异藏在运行时边界后面，而不是直接暴露给提示词。
映射到 TaskPilots，就是让独立运行 Agent 不仅有提示和工具，还要有明确的状态模型、执行记录和适配层。工具链负责接外部系统，运行时负责解释工具契约和恢复逻辑，状态模型负责保存任务进度与关键证据。这样单体 Agent 即使暂时不拆成多角色，也已经具备可运营、可审计、可恢复的基础。
风险与失效点
最常见的四类失控方式
第一类失控，是无状态重试。调用失败后系统直接整段重跑，却没有识别哪些步骤已经成功，导致重复发信、重复写库或重复提交。第二类失控，是工具结果未校验，工具明明返回部分失败、空结果或模糊状态，Agent 却把它当成可靠输入继续向下执行。第三类失控，是权限扩散，单体 Agent 因为“方便”而拿到过宽的工具访问范围。第四类失控，则是长会话失控，旧轮次上下文、旧任务状态和新用户意图没有被清晰分隔，最终让系统在错误状态上继续推进。
- 无状态重试会把恢复流程变成副作用重放。
- 结果未校验会让错误从工具层蔓延到决策层。
- 权限扩散会让单体 Agent 拥有不符合最小权限原则的能力半径。
- 长会话漂移会让系统越来越难判断当前状态是否仍然可信。
哪些地方必须保留人工兜底
凡是涉及高价值写操作、权限修改、面向外部的正式承诺、批量执行、以及恢复时无法确认前序步骤是否已落地的场景，都应保留人工兜底。人工介入不一定意味着人工完成整个任务，更常见的做法是人工确认一次关键状态，例如“这条记录是否已经写入”“这次重试是否会产生重复副作用”“当前工具结果是否足以继续执行”。对单体 Agent 来说，人工关口的价值尤其大，因为很多团队会误以为单体系统更容易理解，实际上当逻辑全部混在一个运行体内时，关键判断反而更需要显式证据。
验证指标
上线前怎么验证
上线前建议至少做三类验证。第一类是工具契约验证，确保每个工具的输入输出 schema、异常类型和幂等要求都能被运行时检查。第二类是状态恢复演练，模拟中断、超时、部分成功和跨会话继续执行，确认系统能从检查点恢复，而不是从头盲重跑。第三类是权限与边界测试，故意构造超范围工具调用、错误状态引用和长会话漂移样例，验证 Agent 是否会被运行时拦下。
- 执行成功率：在正常输入下，任务是否能稳定完成。
- 工具失败率：每类工具调用的异常比例是否可解释、可归因。
- 恢复时间：从中断到恢复可继续执行，系统需要多长时间。
- 状态一致性：恢复后状态、工具结果和最终输出是否保持一致。
上线后怎么持续判断
进入生产后，建议把指标拆成运行质量和治理质量两组。运行质量看成功率、重试率、平均恢复时间和工具调用异常分布；治理质量看状态一致性告警、越权调用拦截率、人工接管率和恢复后重复副作用比例。如果这些指标只看总体均值，很容易掩盖关键失败簇，因此最好按工具类型、任务类型和状态阶段分组追踪。这样团队才能知道问题到底来自工具契约不清、状态层不足，还是会话边界设计错误。
下一步 / FAQ
下一步建议
最务实的第一步，不是马上引入更多 Agent，而是先把当前单体 Agent 的三个关键边界画清楚：它能调用哪些工具、哪些状态会被持久化、哪些失败允许自动恢复。接着为每个工具补齐输入输出契约和失败分类，为每条长流程定义最小检查点，再挑一条真实业务链路做恢复演练。只要这一步跑通，后续无论继续保持单体架构，还是演进到多 Agent，都能建立在更稳的运行时基础之上。
FAQ
只有一个 Agent，真的值得做这么多约束吗？ 只要它连接真实工具并产生副作用，就值得。复杂度来自执行责任，不来自 Agent 数量。
工具契约是不是会降低灵活性？ 会减少临场随意发挥，但换来的是更稳定的调用、更可靠的恢复和更低的排障成本。
没有持久化层能不能先上线？ 如果任务会跨会话、要恢复中断或要避免重复副作用，最好不要。缺失持久化时，重试往往只能靠整段重跑。
MCP 适配什么时候需要？ 当工具来源开始增多、接口风格不一致、或团队希望统一工具接入和授权边界时，就值得把它抽成独立适配层。