AgentHarness十二大核心模块详解

如果你能把这 12 层真正理解透，其实你已经具备设计 Agent 平台的基础能力了。

 一、编排循环：真正决定 Agent 能不能“像人一样工作”

很多人第一次接触 Agent 时，会天然觉得“大模型”才是核心。但真正做过工程之后会发现，模型其实只负责“下一步生成什么内容”，真正决定 Agent 是否能连续完成任务的，是编排循环（Orchestration Loop）。

因为 Agent 和普通聊天机器人最大的区别在于，它不是只回答一句话，而是会不断经历“思考 → 调工具 → 获取结果 → 再思考 → 再执行”的循环过程。这个循环决定了 Agent 什么时候调用工具、什么时候继续推理、什么时候暂停等待人工确认、什么时候结束任务。从工程角度看，它其实就是整个 Agent 系统的 CPU 调度器。

现在主流的 Agent 编排方式大概有三种。

第一种是自动循环，也就是框架自动帮你完成 model → tool → model 的调用链路。LangChain、OpenAI Agents SDK 基本都属于这种模式，好处是开发简单、上手快，适合快速做 Demo。

第二种是工作流式编排。开发者自己定义节点、状态、分支、并行逻辑以及中断恢复点。这种模式更像 DAG 工作流，因此在复杂业务系统里会更稳定。LangGraph、ADK、CrewAI 基本都属于这一类。

第三种则是 Actor 模型，也就是把每个 Agent 看成独立服务，通过异步消息进行通信。AutoGen 很典型，这种模式更适合复杂多 Agent 协作。

但真正到了线上之后，编排循环最容易出的问题其实并不是“跑不起来”，而是“停不下来”。很多 Agent 会无限调用工具，最后 token 疯狂增长，甚至进入死循环。所以生产环境一定会加各种限制，比如最大轮数、最大工具调用次数、超时时间、最大 token 消耗，以及中断恢复机制。否则 Agent 很容易从“智能系统”变成“成本黑洞”。

一句话来说，编排循环本质上就是 Agent 的 CPU 调度系统。

 二、工具系统：Agent 为什么突然“能做事了”

很多人第一次看到 Agent 自动查网页、发邮件、操作浏览器时，会觉得特别神奇。但本质上，这些能力都来自工具系统（Tool System）。

因为大模型本身并不能真正操作外部世界，它只能生成文本。真正让 Agent 能“干活”的，是开发者把各种外部能力包装成模型能够理解的工具接口。换句话说，工具系统其实就是给 AI 安装“手和脚”。

工具系统负责的范围非常广，包括搜索网页、查询数据库、发送邮件、调用内部 API、执行代码、操作浏览器，甚至控制企业内部系统。没有工具系统，Agent 永远只是聊天机器人；有了工具系统，它才真正具备执行能力。

现在主流的工具协议主要有三类。

第一类是 Function Calling，本质上就是把工具描述成 JSON Schema，让模型知道“这个工具叫什么”“需要什么参数”“返回什么结果”。这是目前最主流也最容易接入的方式。

第二类是 OpenAPI，更适合已有 REST API 系统。很多企业会直接把已有接口转成 Agent Tool。

第三类是 MCP，也是现在越来越热门的方向。MCP 最大的价值是把工具接入标准化，以后不同 Agent 框架之间不需要再重复写 adapter。

不过真正到了工程里，最大的难点往往不是“怎么调用工具”，而是“怎么限制工具”。因为一旦 Agent 能操作 shell、数据库、文件系统或者支付接口，风险会瞬间放大。

所以真正成熟的 Agent 平台一定会做权限控制，比如哪些工具必须人工审批、哪些操作只能只读、哪些参数禁止传入，以及所有工具调用都必须具备完整 trace 和审计记录。否则工具能力越强，系统风险反而越大。 

一句话来说，工具系统本质上就是 Agent 的设备驱动层。

三、结构化输出：为什么真正的 Agent 不会直接输出“自然语言”

很多团队刚开始做 Agent 时，都会有一个典型阶段：先让模型输出一大段文本，然后自己再用正则表达式去解析。比如从回答里提取状态、提取金额、提取任务字段。一开始看起来没问题，但系统一旦上线，很快就会发现这种方式极其不稳定。因为自然语言本身就不是给程序消费的。真正的工程系统需要的是结构。这也是为什么，结构化输出（Structured Output）几乎已经成为所有 Agent 框架的标配能力。它本质上是在解决一个问题：如何把大模型的“语言能力”，变成程序真正可以执行的协议。比如你让 Agent 创建工单，那最终输出不应该是一段“我已经帮你创建完成啦”的文本，而应该是一个标准 JSON：包含工单 ID、优先级、负责人、状态等字段。因为只有这样，下游系统才能继续执行自动化流程。

现在主流实现方式大概有三种。

第一种是模型原生 Structured Outputs，也就是直接要求模型严格按照 schema 输出。这种方式最稳定，因为协议本身已经被约束。

第二种是 validator + retry。也就是模型先生成，然后再通过 Pydantic 或 Validator 去校验。如果格式不对，就重新生成。PydanticAI 很典型。

第三种则更底层，叫 grammar decoding。它直接在 token 生成阶段做约束，让模型从一开始就只能输出合法结构。Outlines、vLLM 都在往这个方向发展。

但真正线上最重要的一件事其实很简单：永远不要相信自由文本。因为模型今天可能输出 status，明天就可能变成 state，后天又可能变成 current_status。对于人类来说这不影响理解，但对于程序来说，这就是线上事故。所以成熟的 Agent 系统一定会做 schema 校验、失败重试、repair 修复，甚至人工兜底。因为结构化输出本质上不是“优化体验”，而是在保证系统可运行。 

一句话来说，结构化输出本质上是 Agent 的协议层。

四、记忆系统：为什么 Agent 能“越用越懂你”

很多人会把记忆系统理解成“把聊天记录重新塞回 Prompt”。但真正做过工程之后会发现，这种做法根本撑不住。因为上下文窗口永远有限，而真实用户的历史信息会越来越多。真正成熟的记忆系统，更像数据库，而不是聊天记录。它负责让 Agent 不需要每次都从零开始理解用户。比如用户喜欢什么表达方式、之前做过哪些操作、公司是什么行业、哪些信息已经确认过，这些都属于长期记忆。而当前任务状态、当前页面内容、刚刚执行的步骤，则属于短期记忆。真正成熟的 Agent，一定会把这两类信息拆开管理。因为如果所有内容都混在一起，系统很快就会出现“记忆污染”。所谓记忆污染，其实就是 Agent 开始记住大量无意义的信息。比如用户今天随口提了一句股票，结果系统永久记住“用户喜欢股票”。久而久之，Agent 会越来越像一个“信息垃圾堆”。所以真正成熟的记忆系统，重点根本不在“怎么存”，而在“存什么”。

生产环境里通常会有一整套写入策略，比如：写前抽取、去重、TTL、分层存储、按用户隔离、来源追踪等等。很多团队一开始会特别关注向量检索，但后来都会发现，真正决定系统质量的不是 embedding，而是记忆治理。因为只要记忆策略错了，再强的检索系统也只是在更快地检索错误信息。现在主流框架里，Mem0、Zep、Letta 都在重点解决这类问题。尤其 Letta 很有意思，它会把“常驻记忆”和“归档记忆”拆开，本质上已经很像操作系统里的内存分层。所以记忆系统真正重要的地方，并不是“让 Agent 记得更多”，而是“让 Agent 记得正确”。 

一句话来说，记忆系统本质上是 Agent 的长期存储系统。

五、上下文管理：真正决定模型“此刻能思考什么”

很多人刚开始做 Agent 时，会下意识觉得：既然上下文窗口越来越大，那我是不是把所有信息都塞进去就好了？结果往往是，Prompt 越来越长，模型却越来越笨。因为上下文并不是越多越好，而是越精准越好。

真正成熟的 Agent 系统里，上下文管理（Context Management）其实是一层非常核心的能力。它负责决定：这一轮推理里，模型到底应该看到什么。这件事的重要性远超很多人的想象。因为大模型本质上没有真正意义上的长期记忆，它每一次推理，都只能基于当前 token 窗口里的内容进行思考。所以谁能进入上下文窗口，谁就拥有“被模型思考”的资格。

从工程角度看，上下文管理本质上是一个信息调度系统。它每天都在做四件事：检索、筛除、压缩、重排。哪些内容应该保留，哪些应该删除；哪些信息应该放前面，哪些应该被总结压缩；哪些历史记录还重要，哪些已经失效。这些都属于上下文管理。

现在很多框架已经开始把这些能力内建化。LangChain 有 trim、summarize、tool limit 等 middleware；ADK 会动态生成 instruction；Responses API 也开始支持 stateful continuation 和 prompt caching，本质上都在解决“上下文调度”问题。但真正到了线上，最大的两个坑其实叫 Context Overload 和 Context Collapse。Context Overload 很容易理解：信息太多，重点被淹没。模型虽然“看到了所有内容”，但真正相关的信息反而被稀释掉。而 Context Collapse 更麻烦。很多系统为了节省 token，会不断总结历史对话。但总结次数一多，细节会逐渐丢失，最后模型只剩一个模糊摘要。很多 Agent 聊久了开始“失忆”，本质上就是上下文坍塌。

所以现在越来越多团队开始做结构化上下文，而不是简单文本摘要。因为真正高质量的上下文系统，目标从来不是“塞更多信息”，而是“让模型在关键时刻看到最重要的信息”。 

一句话来说，上下文管理本质上是 Agent 的内存管理器。

六、提示词组装：真正的 Prompt Engineering，已经越来越像“编译器工程”

很多人提到 Prompt Engineering，第一反应还是“怎么写一句更厉害的 System Prompt”。但真正的大厂 Agent 系统，早就已经不是“手写提示词”了。因为真正进入模型的 Prompt，往往是动态生成的。它可能同时包含：系统规则、用户目标、工具定义、上下文检索结果、历史记忆、输出 schema、安全规则，甚至还有调试信息。

换句话说，现在的 Prompt 已经不是一句文本，而是一套动态编译系统。这也是为什么，提示词组装（Prompt Assembly）会越来越重要。它负责把系统中的各种信息源，按照稳定顺序和规则，最终拼接成模型真正看到的输入。从工程角度看，它其实非常像编译器前端。因为它干的事情，本质上就是“把各种上层语义编译成模型可执行的 Prompt”。现在成熟系统通常都会把 Prompt 分层。

比如 system layer 负责身份与规则；task layer 负责当前任务；memory layer 负责历史记忆；tool layer 负责工具描述；output layer 负责结构化约束。这么做最大的价值，不只是代码更清晰。而是它解决了三个真正工程化的问题：可测试、可缓存、可解释。

可测试意味着 Prompt 可以做回归测试；可缓存意味着稳定前缀可以复用；可解释意味着线上出问题时，开发者能真正还原“模型当时到底看到了什么”。这一点其实非常关键。

因为很多 Agent 系统出问题后，开发者甚至无法还原真实 Prompt。最后只能不停猜测模型为什么会这样回答。而随着 Agent 越来越复杂，Prompt 也开始越来越像“运行时动态生成代码”。所以未来真正成熟的 Prompt Engineering，很可能已经不再是“写提示词”，而是“设计 Prompt 编译系统”。 

一句话来说，提示词组装本质上是 Agent 的 Prompt 编译器。

七、状态与检查点：为什么真正的 Agent 必须“断点续跑”

很多 Agent Demo 看起来都很丝滑。因为它们通常只跑十几秒。但真正线上系统完全不是这样。

真实业务里的 Agent，可能要运行几个小时，甚至几天。中间可能等待人工审批、等待外部接口、等待数据库任务，甚至等待用户第二天继续操作。这时候，一个问题就会变得特别致命：如果系统中途崩了怎么办？于是状态与检查点（State & Checkpoint）就出现了。它负责保存 Agent 当前的运行状态，包括已经完成的步骤、当前工作流节点、工具结果、会话状态、审批状态等等。

本质上，它是在给 Agent 做“存档”。真正成熟的 Agent 系统，一定是可恢复的。也就是说，系统崩溃之后，不需要从头开始，而是能从最近 checkpoint 继续恢复执行。但这里真正难的，其实不是“保存状态”，而是“避免副作用重复执行”。比如一个 Agent 已经发过邮件了。结果系统恢复时又重新执行一次。那就是生产事故。所以 durable execution 系统都会特别强调幂等性。所有工具调用，要么天然幂等，要么必须支持回滚。另外一个工程上的难点是 checkpoint 粒度。太粗的话，一旦失败就要重跑大量步骤；太细的话，状态存储又会暴涨。所以真正成熟的状态系统，本质上是在“恢复效率”和“存储成本”之间找平衡。现在像 LangGraph、Temporal、DBOS、Azure Durable Functions，其实都在解决这一类问题。因为真正的 Agent，不可能永远只是一个短生命周期的聊天会话，它迟早会变成长期运行的任务系统。 

一句话来说，状态与检查点本质上是 Agent 的存档与恢复系统。

八、错误处理：真正成熟的 Agent，不会“一报错就死”

很多 Agent Demo 都有一个共同特点：只要 API 报错，整个流程立刻终止。但真实线上系统根本不可能这样。因为现实世界本身就是不稳定的。接口会超时、模型会限流、数据库会抖动、第三方服务会宕机，甚至模型自己都会输出非法结果。所以真正成熟的 Agent，一定需要完整的错误恢复系统。

错误处理（Error Handling）本质上是在解决一个问题：当系统出错时，到底应该怎么办。是重试？降级？人工介入？还是直接终止？真正成熟的系统，通常会把错误分层。

第一类叫瞬时错误：比如 429、网络抖动、请求超时。这种错误本质上是“暂时不可用”，所以最适合指数退避重试。

第二类叫结构错误：比如模型输出不符合 schema，JSON 格式非法，字段缺失。这种问题通常适合 repair 或 re-prompt。

第三类才是真正危险的业务错误：比如权限不足、资金校验失败、关键前置条件缺失。这类问题如果盲目重试，反而可能造成更大事故。

所以很多企业 Agent 最后都会引入人工接管机制。真正线上还有一个特别重要的问题：错误信息隔离。因为系统内部错误往往包含大量敏感信息，比如堆栈、内部路径、数据库结构、API Key 等。如果这些内容直接暴露给模型，安全风险会非常高。所以成熟框架通常会把“系统错误”和“模型可见错误”拆开。系统内部记录完整日志，但给模型的只是经过脱敏后的纠错信号。

本质上，真正成熟的错误处理系统，并不是为了“让 Agent 不出错”，而是为了“让系统即使出错也不会崩”。

一句话来说，错误处理本质上是 Agent 的异常恢复中心。

九、护栏系统：为什么真正危险的不是模型，而是“会行动的模型”

很多人第一次做 Agent 时，最容易忽略的就是安全。因为过去的大模型，大多数时候只是“说错话”。但 Agent 不一样。一旦模型拥有工具能力，它就开始真正接触现实世界。它可以发邮件、删文件、查数据库、操作浏览器，甚至执行代码。这时候，风险会瞬间放大。因为真正危险的，从来不是“会聊天的 AI”，而是“会行动的 AI”。于是护栏系统（Guardrails）就变得极其重要。它负责在输入、推理、工具执行、输出各阶段，对 Agent 进行安全约束。

成熟的 Guardrails 通常会分成四层。

第一层是输入护栏：主要解决 Prompt Injection、越权请求、敏感信息诱导等问题。

第二层是上下文护栏：因为很多恶意内容可能来自外部检索结果，而不是用户输入。

第三层是工具护栏：这层最关键。因为真正危险的动作通常都发生在工具执行阶段。比如 shell、SQL、文件写入、支付接口，这些都必须限制权限。

第四层则是输出护栏：包括内容审核、脱敏、政策检查以及结构校验。

但真正成熟的安全体系，其实有一个非常重要的原则：不要把所有安全问题都交给 LLM。因为模型本身并不稳定。今天能识别风险，不代表明天还能稳定识别。所以成熟系统通常都会采用“规则优先，模型兜底”的策略。

确定性规则负责核心安全边界；LLM 负责模糊风险判断；高风险动作则必须人工审批。因为到了工程层面，Guardrails 已经不再是“模型能力”，而是企业级安全体系。 

一句话来说，护栏系统本质上是 Agent 的安全内核。

十、验证与反馈：为什么 Agent 上线之后，真正困难的才刚开始

很多团队做 Agent 时，最开始关注的都是“能不能跑起来”。但真正上线之后，很快就会遇到一个更难的问题：到底怎么判断 Agent 好不好？

因为传统软件的结果通常是确定的。但 Agent 天然带随机性。同一个问题，不同时间、不同模型、不同上下文，可能都会得到不同结果。于是验证与反馈（Eval & Feedback）开始变得越来越重要。它本质上是在解决两个问题：系统现在到底靠不靠谱，以及系统如何持续变好。成熟团队通常会同时做三类评测。

第一类是离线评测：也就是固定数据集回归测试，用来比较 Prompt、模型、Workflow 的效果变化。

第二类是在线评测：直接监控真实用户流量，发现线上漂移。

第三类则是人工反馈：把线上 bad case 收集起来，进入标注与 review 流程。

很多团队一开始特别迷信 LLM-as-Judge，觉得“让 GPT 给 GPT 打分”就够了。但真正做久了会发现，这远远不够。因为模型评测本身也会漂移。所以真正稳定的评测体系，一定是组合式的。包括规则校验、Schema 校验、Reference Test、LLM Judge、人工抽检，多种机制一起工作。现在很多平台，比如 LangSmith、Phoenix、Braintrust、MLflow，本质上都在做同一件事：把 traces、eval、dataset、feedback 连成闭环。

因为真正成熟的 Agent 系统，不是“上线一次就结束”，而是一个持续演进的系统。所以 Eval 最终其实越来越像传统软件里的 CI/CD 与 QA，只不过测试对象从“代码逻辑”变成了“模型行为”。 

一句话来说，验证与反馈本质上是 Agent 的 QA 与持续优化系统。

十一、多 Agent 编排：为什么 AI 世界开始出现“AI 团队”

现在越来越多 Agent 系统开始搞多 Agent。比如一个 Agent 负责搜索，一个负责写代码，一个负责审查，一个负责总结。很多人第一次看到时，会觉得这不就是“多开几个模型实例”吗？但真正工程里，多 Agent 远远没那么简单。因为它真正解决的问题，其实是复杂系统里的角色分工。

当一个 Agent 同时承担规划、执行、审查、沟通、总结时，它的上下文会越来越混乱，目标也会越来越冲突。于是很多团队开始把不同职责拆成不同 Agent。从工程角度看，这其实已经越来越像分布式系统。因为多 Agent 系统开始出现：角色通信、共享状态、权限隔离、任务委派、冲突处理等问题。

目前主流模式其实比较稳定。比如 delegation，也就是主 Agent 分派任务；handoff，也就是控制权转移；parallelization，也就是多个 Agent 并行求解；group chat，则更像多人会议。但真正线上最容易踩的坑，其实是“过度多 Agent 化”。很多团队会把所有问题都拆成多个 Agent。最后系统复杂度直接爆炸。

因为 Agent 一多，通信成本、状态同步、trace 数量、调试复杂度都会指数级上升。很多时候，一个 Agent 加 planner 就已经够用了。只有在角色目标、权限边界、上下文窗口明显不同的时候，多 Agent 才真正有价值。所以真正成熟的多 Agent 系统，重点从来不是“Agent 数量”，而是“角色边界是否清晰”。本质上，多 Agent 已经越来越不像 Prompt Engineering，而越来越像组织架构设计。 

一句话来说，多 Agent 编排本质上是 AI 世界里的分布式协作系统。

十二、初始化与运行时：真正决定 Agent 能不能从 Demo 走向生产

最后这一层，往往是最容易被忽略的。因为很多人做 Agent 时，注意力都会放在 Prompt、Workflow、Tools 上。但真正决定系统能不能上线的，其实是运行时（Runtime）。因为 Demo 能跑，不代表生产能跑。真正线上环境里，你会开始遇到各种现实问题：环境不一致、依赖冲突、权限隔离、Session 生命周期、冷启动、扩缩容、代码执行安全等等。

于是初始化与运行时系统就变得非常重要。它负责的事情其实很多，包括环境初始化、配置加载、密钥管理、Session 管理、部署、沙箱隔离、生命周期管理等。从工程角度看，它其实已经非常接近“操作系统”了。真正成熟的 Agent Runtime，通常都会特别关注三件事。

第一件事叫可复现：也就是无论在哪运行，环境都必须一致。否则线上问题会非常难排查。

第二件事叫隔离：尤其是 Coding Agent。因为一旦允许模型执行代码，系统风险会瞬间提升。所以现在很多平台都会引入 Docker Sandbox、E2B 这类隔离环境，本质上就是给 AI 提供一个独立操作系统。

第三件事则是会话复用：因为很多 Agent 都是长生命周期任务。如果每次都重新初始化环境，成本会非常高。所以成熟 Runtime 通常都会保留 workspace、cache、session 状态。

现在像 Agent Framework、ADK、LangSmith Agent Server，其实都在往“Agent Runtime 平台”方向发展。因为未来真正的 Agent，很可能已经不再只是 SDK，而会变成长期运行的智能服务。

一句话来说，运行时层本质上是 Agent 的操作系统与宿主环境。

最后：真正的 Agent，已经越来越像“新一代软件架构”

如果你一路看到这里，其实会发现一个特别明显的变化。过去大家聊 AI，大多数时候聊的还是模型本身。比如参数量、上下文长度、推理能力、Benchmark 排名。但到了 Agent 时代，问题已经开始彻底变化了。因为真正决定系统能力的，已经不再只是“模型够不够强”，而是整套工程体系是否完整。一个真正成熟的 Agent 系统，背后其实已经越来越像传统软件架构。它有自己的 CPU，也就是编排循环；有自己的内存管理，也就是上下文系统；有自己的长期存储，也就是记忆系统；有自己的协议层、状态恢复系统、安全内核、运行时环境，以及持续评测体系。

换句话说，Agent 已经不再只是“大模型调用”。它正在慢慢演变成一种新的软件形态。这也是为什么，很多团队一开始做 Agent 时会特别痛苦。因为大家原本以为，所谓 Agent，只是“Prompt + Tools”。结果真正上线之后才发现：真正困难的，根本不是让模型回答问题。而是：

• 怎么让系统长期稳定运行
• 怎么让状态不中断
• 怎么避免无限循环
• 怎么控制工具权限
• 怎么做上下文治理
• 怎么做安全审计
• 怎么做线上评测
• 怎么持续迭代优化

你会发现，这些问题其实已经越来越不像 AI 问题，而越来越像“软件工程问题”。所以未来真正的竞争，很可能已经不是“谁 Prompt 写得更好”，而是谁能把 Agent 的整套基础设施真正工程化。因为只有当这 12 个模块真正稳定协同之后，Agent 才会从一个 Demo，变成真正可上线、可扩展、可维护、可持续演进的生产系统。而这，可能才是 AI Agent 真正开始改变软件行业的地方。