前几天有个读者私信我说他在跑一个开源 Agent 项目时刚启动就弹了一行红字error: agent harness runtime codex is unavailable because its plugin registration failed他问我这到底是什么意思为什么一个看起来普普通通的 Agent 项目还没开始对话就先崩了这不是个例。我接触过不少刚入门 AI Agent 的同学大家普遍把 Agent 想得太简单以为就是一个大模型 API while 循环。结果真的跑起来问题一个接一个工具调用乱成一团、上下文越攒越长、模型经常绕不回来最后连 Agent 到底执行了哪些步骤都说不清楚。问题通常不在模型本身而是少了一个能管理 Agent 的壳。这个壳在工程上有个专门的名词叫 Agent Harness。所以这篇教程我就把锦恢那套 AI Agent 小白教程里最核心的两块东西讲透一个是 PTC 设计原则教你用 Plan、Tool、Critic 三个词把 Agent 的逻辑想明白另一个是 Agent Harness 标准架构告诉你一个可维护、可观测、可扩展的 Agent 运行时到底该由哪些层组成、每一层干什么、怎么从零写一个最小可用的 Harness。不管你是刚接触 AI Agent 开发还是已经写过几个 demo 但总觉得工程上不对劲这篇都适合你。1. 先搞清楚AI Agent 为什么会卡壳1.1 一次让小白崩溃的报错我们先回到开头那个报错。error: agent harness runtime codex is unavailable because its plugin registration failed这句话拆开看并不复杂agent harness runtimeAgent 的运行时容器也就是承载 Agent 逻辑的框架而不是大模型本身。codex这里指的是一个具体的插件或后端实现你可以把它理解成某个工具集、模型适配器或者服务入口。plugin registration failed系统启动时尝试加载这个插件但是失败了。换句话说Harness 在启动时会做一堆初始化事情比如扫描插件、注册工具、检查配置、建立模型连接。任何一步挂了整个 Agent 就起不来。很多小白第一次看到这个报错会以为是大模型密钥错了其实更多时候是插件没装全、依赖版本对不上或者配置文件里的路径没写对。这种问题反过来说明一件事Agent Harness 不是可有可无的装饰它本身就是一套有启动流程、有依赖管理、有运行约束的程序。如果你不理解这个壳是怎么设计的遇到类似报错就只能靠瞎猜。1.2 Agent 不是脚本而是“系统”再说说另一个更常见的现象。很多新手第一次写 Agent代码大概长这样while True: user_input input(你说) prompt f你是助手请回答{user_input} reply llm.chat(prompt) print(reply)这东西能跑但它只是个脚本不是一个真正能用的 Agent。因为它遇到下面任一情况都会崩模型说要调用工具你却不知道怎么把工具结果传回给模型多轮对话下来历史消息全塞进上下文token 直接爆掉工具返回了异常数据Agent 不知道该怎么处理只能把错误信息原样吐给用户Agent 跑完一轮你完全看不出它中间调了哪些工具、为什么得出这个结论。所以我们需要一个 Harness。用生活里的事情打个比方洗衣机不是“一台电机加水桶”的简单组合而是有进水、洗涤、排水、甩干这些阶段每个阶段都有控制逻辑。Agent 也一样它需要一套固定流程去管理“理解需求、调用工具、检查结果、给你答案”的整个过程。而 PTC 设计原则就是用来指导你设计这套流程的。简单说把 Agent 的逻辑想成一句话先做计划Plan再调工具Tool最后检查结果Critic。这个框架足够简单小白能立刻上手同时也不算太业余真要放大到生产项目里也完全不虚。2. PTC 设计原则Plan-Tool-Critic一个新手足够用的 Agent 设计范式PTC 不是某个国际标准它是锦恢在教程里提出的一套设计原则缩写。我第一次看到时也觉得有点“玄乎”但后来在项目里用多了发现它其实就是把 Agent 的思考循环高度抽象成了三个动作规划、执行、校验。为什么这三个动作就够了因为 Agent 的本质是让大模型在“思考”和“行动”之间交替进行。模型先想怎么做然后动手调工具拿到工具结果后再判断是不是可以给用户答案。如果结果不满意就再想、再调、再查。PTC 恰好覆盖了这个循环的三个关键节点。2.1 Plan先别急着写代码把任务拆成计划P 是 Plan意思是任务规划。很多刚入门的朋友拿到一个需求就急着写 prompt希望大模型直接输出最终答案。对于特别简单的任务这没问题。但一旦任务复杂点比如“帮我整理一份上海二手房市场分析报告”你让模型直接输出它很容易漏信息、结构混乱、甚至编数据。正确的做法是先拆解计划。你可以在系统 prompt 里强模型输出 step-by-step也可以专门写一个 planner 模块让大模型先生成一份任务清单。举个最简单的例子用户问“北京今天适合穿什么衣服”这个任务的计划应该是调用天气工具获取北京今天的温度、湿度、天气现象根据天气数据结合季节和体感得出穿衣建议。为什么要先拆一步因为拆完之后每一步都可以单独校验。如果天气数据没拿到后面穿衣建议就无从谈起如果你直接让模型回答它可能连“今天北京是刮风还是下雨”都不知道就开始了长篇大论。这里我想多说一句Plan 不是越复杂越好。小白项目最忌讳的就是把计划设计成一个庞大的任务树。我的建议是一个 Agent 默认承担一个主任务内部步骤控制在三到五步。超过五步就该拆成多个 Agent 或者做子任务调用了那是后面的进阶内容。2.2 Tool给 Agent 配好“手脚”并且管好它们T 是 Tool也就是工具调用层。Agent 和大模型聊天机器人最大的区别就在于它能操作外部工具。查天气、算数学、读写文件、访问数据库这些都是能力。但能力越多管理越乱。我见过有人把三十个工具一股脑塞进 prompt结果模型根本不知道该选哪个。一个合格的工具层至少要管好这四件事注册每个工具必须有唯一名称、清晰描述、参数 schema。描述工具描述要写清楚“什么时候用、参数是什么、返回什么格式”。大模型靠描述来选工具描述写得像谜语模型就会乱点鸳鸯谱。执行工具调用要捕获异常、设置超时不能因为一个工具崩溃就让整个 Agent 挂掉。结果回填工具返回结果要结构化比如 JSON方便后面判断和拼接上下文。具体来说你可以用 JSON Schema 约束参数。比如一个天气查询工具它的描述可以写成{ name: get_weather, description: 获取指定城市的今日天气城市名为中文例如北京。返回字段包括温度、湿度、天气现象。, parameters: { type: object, properties: { city: { type: string, description: 城市名例如北京、上海 } }, required: [city] } }这段描述看着简单但在实际项目里救了我很多次。因为模型经常会把参数传错比如city传成北京 天气或者干脆传拼音导致工具报错。参数约束越清晰这种问题越少。2.3 Critic最后一个字母决定了 Agent 是“跑起来”还是“跑对”C 是 Critic这个字母最容易被人忽略但恰恰是它决定了 Agent 到底是“跑起来”还是“跑对”。很多 Agent demo 能跑通但结果经不起推敲。模型说“北京今天适合穿短袖”可它根本没有调用天气工具模型给了你一份分析报告但报告里缺了第三部分模型调用了工具但工具返回的是上海的数据。这些错误靠大模型自己是发现不了的必须有一个 Critic 去做检查。最简单的 Critic 可以是规则校验比如检查返回结果里有没有关键字段也可以再让大模型自己反思一遍把回答和原始问题对比一下看是不是完全回答了用户的需求。我常用的一个方式是让 Critic 输出三个东西原始问题是否被完整回答计划中的所有步骤是否都已执行最终结论是否有工具数据支撑如果 Critic 发现有问题就把它的反馈文本拼回上下文让 Agent 重新回答同时设置最大重试次数比如三次。超过次数就放弃避免无限循环。你可以把 PTC 理解成一个循环计划 - 执行 - 检查 - 修改计划 - 再执行 - 再检查。它不是一条直线而是一个不断收敛的环。3. Agent Harness 标准架构把 PTC 变成能跑的代码聊完设计原则接下来就要落实成架构。Agent Harness 这个词听起来高级其实就是承载 Agent 运行的“骨架容器”。我建议所有 Agent 项目不管大小都按一个相对固定的分层来搭。下面这套架构并不是某一家公司的专利而是经过很多开源项目验证后沉淀下来的通用结构。3.1 核心组件拆解模型接入层、工具注册层、上下文管理层一个标准 Agent Harness我习惯拆成五个核心层你可以先用表格认识它们分层核心职责对标 PTC模型接入层Model Provider封装不同大模型 API统一输入输出、处理超时和重试PTC 底层支撑上下文与记忆层Context/Memory管理对话历史、token 窗口、长期记忆Plan 依赖的历史信息规划与决策层Planner任务拆解、生成执行计划、决定下一步动作Plan工具执行层Tool Executor工具注册、参数校验、执行调用、结果回填Tool校验与反思层Critic结果检查、纠错、重试控制Critic观测与安全层Observer/Guardrails日志记录、调用追踪、输入输出保护贯穿全流程模型接入层是 Harness 的地基。你以后可能会从一家模型厂商切到另一家如果代码里到处都直接调用 OpenAI SDK切换成本会非常高。正确做法是定义一个统一的chat()接口接哪家大模型只改适配器。上下文与记忆层是很多人忽略的重灾区。小白最容易犯的错误就是把历史消息全部拼接进 context结果 token 越用越多越到后面模型越“糊涂”甚至完全不记得最开始用户说了什么。标准做法是给上下文设一个窗口超过窗口就把早期的消息做摘要用摘要代表旧对话再丢给模型。工具执行层要做得“强硬”一点。所有工具必须经过注册才能被调用不能允许模型随便调用任意函数。参数校验不通过就直接返回错误信息错误信息同样要回填给模型让它知道是参数错了而不是结果错了。规划层和校验层前面的 PTC 部分已经讲了很多这里不重复。关键是这两个层在 Harness 里建议也抽象为独立模块不要和主循环混在一起。否则代码一旦复杂起来你会分不清一段逻辑到底是规划还是执行。3.2 调度与观测让 Agent 的行为可控、可回放Harness 的心脏是调度循环也就是 Agent Loop。一个最简单但完整的循环伪代码大概长下面这样while not done and step max_steps: messages context_manager.build(user_query, history) response llm.chat(messages, toolstool_registry.schemas()) if response.tool_calls: for call in response.tool_calls: result tool_registry.execute(call.name, call.arguments) history.append(tool_result_message(call.id, result)) continue if response.final_answer: done True注意这里有几个容易踩的坑第一max_steps必须设置。没有它模型可能陷入“工具调用失败-重试-再失败”的死循环白白烧掉你的 tokens。我一般给 5 到 8 步小任务完全够用。第二日志要做得足够细。不要只记录“最终答案”每轮模型输出的思考、工具调用的参数、工具返回的结果都要记录下来。我最常用的格式是 JSON Lines一行一个事件。排查问题时直接把日志拉出来像看剧本一样把 Agent 的行为重放一遍。第三给循环里的每一步都加上耗时和 token 统计。不然你根本不知道一次请求花掉的成本也不知道哪个工具调用特别慢。3.3 安全与校验小白的项目也要有“刹车”很多人觉得安全是大公司才需要考虑的事其实不是。你自己写一个小 Agent如果没做校验也照样会翻车。我这里给小白一个最低限度的安全清单工具白名单只有显式注册过的函数才能被调用杜绝“模型自己写函数自己执行”的情况。工具调用次数限制结合max_steps一起防止循环调用。输入长度限制用户输入太长先截断或提示别直接塞给模型。输出校验最终输出里如果包含邮箱、手机号等隐私信息要做脱敏处理。危险操作确认如果你的 Agent 能发邮件、删文件、转账那这类操作必须设置人工确认步骤。最笨但有效的办法是在execute_tool里加一层检查def execute_tool(name, arguments): if name not in self.tools: return {error: f工具 {name} 不存在} if name in DANGEROUS_TOOLS: return {error: f工具 {name} 需要人工确认已拒绝} try: return self.tools[name].func(**arguments) except TypeError as e: return {error: f参数错误: {e}} except Exception as e: return {error: f执行异常: {e}}这套东西写起来不费劲但能让你省下大量调试时间。4. 手把手搭建一个最小 Agent Harness基于 Python 示例讲完架构我直接带你写一个最小可用的 Harness。为了让你看得懂我会把代码尽量简化不依赖任何框架只用 Python 基础语法和一点类型注解。4.1 定义 Harness 的骨架第一步定义一个 Tool 类用来统一描述工具。每个工具包含名字、描述、参数 schema 和实际执行函数。from typing import Any, Callable, Optional class Tool: def __init__(self, name: str, description: str, parameters: dict, func: Callable): self.name name self.description description self.parameters parameters self.func func def schema(self) - dict: return { type: function, function: { name: self.name, description: self.description, parameters: self.parameters, }, }然后定义 AgentHarness 类。核心属性包括模型接口、工具字典、历史消息、最大步数。class AgentHarness: def __init__(self, llm, tools: Optional[list] None, max_steps: int 5): self.llm llm self.tools {t.name: t for t in (tools or [])} self.max_steps max_steps self.history []这里用字典来存工具好处是查找工具时时间复杂度是 O(1)同时能避免工具重名。一个小技巧如果你发现两个工具名重复应该立即报错而不是默默覆盖否则后期排查起来非常痛苦。4.2 把 PTC 挂载到 Harness 上接下来是核心的run方法。它会遍历 PTC 循环模型思考、工具执行、Critic 校验。class AgentHarness: def run(self, user_query: str) - str: self.history [{role: user, content: user_query}] for step in range(self.max_steps): print(f[step {step}] 模型思考中...) response self.llm.chat( self.history, tools[t.schema() for t in self.tools.values()], ) # Tool 阶段 if response.tool_calls: self.history.append(response.tool_call_message()) for call in response.tool_calls: result self.execute_tool(call.name, call.arguments) print(f[step {step}] 调用工具 {call.name}结果{result}) self.history.append(self.tool_result_message(call.id, result)) continue # Critic 阶段 final_answer response.content if self.check_answer(final_answer, user_query): return final_answer print(f[step {step}] Critic 发现回答不完整要求重新生成。) self.history.append({ role: system, content: Critic 反馈你的回答没有完整解决用户问题请补充细节后重新回答。, }) return 达到最大步骤Agent 结束运行。 def execute_tool(self, name: str, arguments: dict) - dict: if name not in self.tools: return {error: f工具 {name} 不存在} try: return {result: self.tools[name].func(**arguments)} except TypeError as e: return {error: f参数错误: {e}} except Exception as e: return {error: f执行异常: {e}} def tool_result_message(self, call_id: str, result: dict) - dict: return { role: tool, tool_call_id: call_id, content: str(result), } def check_answer(self, answer: str, query: str) - bool: # 这里先写一个最简单的规则回答不允许为空且必须包含用户问题里的关键名词 if not answer or len(answer) 10: return False keywords [w for w in query.replace(吗, ).replace(, ).split() if len(w) 1] return True这里需要解释几个设计点tool_call_message和tool_result_message分别把工具的调用和结果写入历史这样模型可以看到“我调了什么工具、返回了什么”。execute_tool里把异常捕获转换成结果信息而不是直接抛异常。这样模型还能根据错误信息自行修正参数Agent 才不会那么容易挂掉。check_answer是最初级的 Critic真实项目可以换成规则校验加 LLM 反思的组合。4.3 一个完整的运行示例假设我们要做一个“查询天气并判断穿衣建议”的 Agent。先定义一个天气工具def get_weather(city: str) - dict: data { 北京: {temp: 22, desc: 晴, humidity: 0.3}, 上海: {temp: 28, desc: 多云, humidity: 0.6}, } return data.get(city, {error: f暂时不支持 {city} 的天气查询})然后用一个模拟 LLM 来代替真实的模型方便演示。真实项目里你只需要替换成 OpenAI 或本地模型的 client 即可。class MockLLM: def chat(self, history, tools): # 第一轮调用模型决定调用工具 if len(history) 1: return Response( tool_calls[ToolCall(nameget_weather, idcall_1, arguments{city: 北京})], contentNone, ) # 拿到天气结果后模型生成最终答案 return Response(tool_calls[], content北京今天 22 度晴天建议穿长袖 T 恤或薄外套。)简单定义完 Response 和 ToolCall 后组装 Harness 并运行harness AgentHarness( llmMockLLM(), tools[Tool( nameget_weather, description获取指定城市的今日天气城市名为中文例如北京。, parameters{type: object, properties: {city: {type: string}}, required: [city]}, funcget_weather, )], max_steps5, ) result harness.run(今天北京适合穿什么衣服) print(Agent 回答, result)运行结果会很直观模型先计划调用天气工具拿到结果后再给出穿衣建议。其中步骤日志会打印在控制台上这就是最基础的观测能力。当然这只是最小实现。你完全可以把 Tool 换成数据库查询、HTTP 请求、代码解释器把 MockLLM 换成真实模型接口Harness 的整体骨架不需要变。5. 从 PTC 到标准架构项目变复杂以后怎么演进5.1 从小型 Harness 到分布式编排的演进路线看到这里你可能觉得 Harness 不过如此一个类就够了。对一个单工具、单模型、单用户场景确实是够了。但项目一旦变复杂比如你要让多个 Agent 协作、要处理后台长任务、要给 Agent 加上长期记忆那就需要在最小 Harness 的基础上做几件关键升级状态外置把history从内存里挪到 Redis 或数据库让 Agent 实例可以随意重启。任务队列长耗时的工具调用丢到队列里去不让 Agent 主循环一直阻塞等待。记忆升级用向量库存历史对话摘要再按相关性检索拼进上下文这叫长期记忆。多模型混合规划用强模型简单任务用便宜模型Critic 用另一个模型做交叉验证。完整评测系统用一批测试用例自动跑 Agent算成功率这会在你改 prompt 或换模型时帮你守住底线。但这些升级都是在“层”内部做的。比如你可以在 Planner 层里加多轮规划而不是绕开 PTC 去重写一套逻辑。架构可以变核心循环没有变。5.2 常见问题速查表下面这份速查表是我在调 Agent 项目时最常遇到的问题也涵盖了热搜词里一些同学的疑问现象可能原因排查建议harness runtime 插件注册失败插件依赖缺失、版本不匹配、配置文件路径错误查看完整启动日志确认插件目录和配置重装依赖后再试模型总是选错工具工具描述不清晰、参数 schema 太松散重写描述明确“什么时候用”用 JSON Schema 严格约束参数上下文一直膨胀token 越用越多没有做上下文截断或摘要给上下文加 token 上限超限后对早期对话做摘要Agent 陷入工具调用死循环没有 max_steps 限制设置最大步数同时让 Critic 检测到重复调用时强制打断模型拿到工具结果后依然乱答工具结果没有回填到历史或回填格式不规范检查 tool_result_message 是否包含 tool_call_id内容是否结构化Agent 跑完不知道它做了什么缺少日志记录从第一天就按 JSON Lines 记录事件含思考、工具、结果、耗时每次遇到“模型行为诡异”的问题先别急着骂模型多数情况是你的 Harness 在某个环节漏传了信息或者没有把约束写清楚。5.3 我的实操心得有一句话我特别想分享给所有新手在设计 Agent 之前先在白板上画一遍 PTC 流程图哪怕只是随手写三个圆圈。画完之后你的代码结构基本就定了Harness 该有哪些方法、该抽象哪些模块全都一目了然。我每次新起一个 Agent 项目都会先画这个图再用骨架代码跑通一个最小链路哪怕工具还是空的也先把整个循环串起来。另一个心得是日志和校验不是后期补的而是第一天就要有。我见过太多人先写 Agent 逻辑出了 bug 再补日志结果发现自己根本不知道问题出在哪个步骤只能靠猜。与其那样不如在最小 Harness 里就把print或结构化日志写好这个习惯能帮你省掉大量烂摊子。还有一条关于 Critic 的小建议。Critic 初期不用做得很复杂不要一上来就搞“多模型互相吐槽”那非常烧钱。先用“回答是否为空、是否包含关键字段、是否回答原始问题”这种规则判断等稳定了再慢慢加 LLM 反思和外部验证。大多数场景一个简单的规则 Critic 就已经能拦住绝大部分错误了。最后分享一个小技巧。给工具命名时尽量用动宾结构比如get_weather、send_email、query_database不要用do_something这种模糊名字。描述里写清楚“什么时候用”比写“这个函数可以调用”有用得多。大模型是真的会读你的工具描述的你把工具文档写得越好Agent 的表现就越稳。PTC 和 Agent Harness 这块是我认为整套 AI Agent 教程里最该先掌握的内容。把这两样吃透后面再去学多 Agent 编排、记忆机制、效果评测都会顺很多。下一篇我们再聊点更进阶的东西。