AI Agent Harness 七大核心子系统：从 Agent Loop 到可观测性的工程实践

1. 拆开“Harness”这个词，先搞清楚它到底管什么

很多人第一次听到 AI Agent 的 Harness，脑子里浮现的是“马具”“线束”这类词，觉得跟智能体八竿子打不着。其实这个比喻相当精准——Harness 就是套在模型这匹“野马”身上的那套挽具，让它别乱跑、能拉车、听指挥。你直接调 LLM API，它只会给你吐一段文本；你给它套上 Harness，它才能读文件、跑命令、调工具、记住上下文、在失败后重试，最后把一个任务从头干到尾。

我接触过不少刚入门的开发者，他们做 AI Agent 的第一反应是“写个 while 循环，把模型输出解析一下，遇到工具调用就执行，再把结果塞回去”。这个思路没错，但它只是 Harness 的雏形。真正能扛住生产环境的 Harness，远不止一个循环那么简单。它要处理上下文窗口溢出、工具调用格式解析失败、并发任务隔离、执行超时、权限边界、状态持久化、错误恢复等一系列脏活累活。这些东西单拎出来都不难，但要把它们有机地组装在一起，让 Agent 稳定地“下地干活”，就需要一套清晰的子系统划分。

这篇文章要聊的，就是这套 Harness 到底由哪些子系统构成，每个子系统解决什么问题，它们之间怎么协作，以及在实际搭建时有哪些坑。不管你是用现成框架还是从零手搓，理解这七个部分之后，你对 AI Agent 的掌控力会上一个台阶。适合有基本编程能力、想认真做一个能跑起来的 Agent 的读者，也适合已经在用某些平台但想搞明白底层原理的人。

2. 七个核心子系统逐个拆解

2.1 Agent Loop：整个 Harness 的心脏

Agent Loop 是 Harness 最核心的调度器，它决定了 Agent 的“思考-行动-观察”节奏。你可以把它理解成一个永不疲倦的工头：拿到用户任务后，它把任务和当前上下文交给 LLM，LLM 返回一个决策（可能是直接回答，也可能是调用某个工具），Loop 执行这个决策，把结果追加到上下文，然后再次调用 LLM，如此往复，直到任务完成或触发终止条件。

这个循环看似简单，但设计时有几个关键决策点。第一是终止条件怎么定。常见的有：LLM 返回了明确的结束标记、达到了最大迭代次数、连续多次没有产生有效工具调用、或者外部信号要求停止。我见过有人只靠“LLM 说完成了”来判断，结果模型陷入死循环，反复调用同一个工具，烧掉大量 token。稳妥的做法是设置硬性上限，比如最多 25 轮，同时配合“连续 3 轮无新信息则终止”的软性判断。

第二是上下文管理。每一轮循环都会往上下文里追加内容，很快窗口就不够用了。Harness 需要决定什么时候压缩历史、什么时候丢弃旧消息、什么时候做摘要。一个实用的策略是保留最近 N 轮完整对话，更早的内容用 LLM 生成摘要替代。摘要的 prompt 要专门设计，确保关键的工具调用结果和决策依据不丢失。

第三是循环的并发模型。单个 Agent 的 Loop 通常是串行的，但如果你要同时跑多个 Agent 任务，就需要在 Loop 外面套一层任务队列和并发控制。这里要注意的是，每个 Agent 实例的上下文必须隔离，不能共享可变状态，否则会出现一个任务污染另一个任务的情况。

# Agent Loop 的极简骨架示意 def agent_loop(task, tools, max_turns=25): context = [{"role": "user", "content": task}] for turn in range(max_turns): response = call_llm(context, tools) if response.is_final: return response.content if response.tool_call: result = execute_tool(response.tool_call) context.append(response.message) context.append({"role": "tool", "content": result}) if should_compress(context): context = compress_context(context) return "达到最大轮次，任务未完成"

注意：Agent Loop 里千万不要把工具执行结果无脑全量塞回上下文。一个读文件的操作可能返回几万字符，几轮下来窗口就爆了。要在工具层做截断和摘要，只把关键信息传回 Loop。

2.2 LLM Integration：模型接入层的门道

LLM Integration 负责和模型打交道，听起来只是“调个 API”，但实际要处理的细节非常多。首先是多模型适配。你可能主用某个模型，但需要备选方案，或者不同任务用不同模型。Harness 要抽象出统一的调用接口，把各家 API 的差异（消息格式、工具调用协议、流式输出方式、错误码）屏蔽掉。

其次是工具调用的解析与校验。模型返回的工具调用请求，格式可能五花八门：有的用 JSON，有的用特定标记，有的把参数嵌在自然语言里。Harness 需要一套健壮的解析器，能处理格式错误、参数缺失、类型不匹配等情况。我踩过的坑是：模型偶尔会返回一个不存在的工具名，或者参数里少了一个必填字段。如果不做校验直接执行，轻则报错中断，重则产生副作用。正确的做法是在执行前做 schema 校验，校验失败就把错误信息返回给模型，让它重新生成。

第三是重试与降级。API 调用可能因为网络、限流、服务端错误而失败。Harness 要有指数退避的重试机制，同时区分可重试错误和不可重试错误。对于不可重试的错误，要能降级到备用模型或返回友好的错误提示。

第四是流式输出的处理。很多场景下用户希望看到 Agent 的实时输出，但流式输出和工具调用会冲突——你需要在流式过程中检测到工具调用标记，然后中断流式、执行工具、再继续。这个切换逻辑要处理好，否则会出现输出截断或重复。

2.3 Tool Registry & Execution：工具怎么管、怎么跑

工具是 Agent 的手和脚。Tool Registry 负责注册、描述、发现工具，Tool Execution 负责实际执行。这两块合在一起，决定了 Agent 能干什么、干得安不安全。

先说注册。每个工具需要有一个清晰的名称、描述、参数 schema。描述要写给模型看，所以要用自然语言说清楚“这个工具做什么、什么时候用、参数什么意思”。我见过有人把描述写得极其简略，结果模型根本不知道什么时候该调这个工具。好的描述应该像给新员工写操作手册，具体、明确、有边界。

参数 schema 建议用 JSON Schema 定义，这样既能给模型看，也能用于执行前的校验。对于复杂参数，要给出示例值。比如一个“搜索文件”的工具，参数pattern的描述可以是“glob 模式，如**/*.py表示所有 Python 文件”。

再说执行。工具执行要在受控环境中进行，尤其是涉及文件系统、命令执行、网络请求的工具。几个关键控制点：超时控制，每个工具调用设置最大执行时间，防止卡死；资源限制，限制内存、CPU、输出大小；权限隔离，不同工具不同权限，敏感操作需要额外确认；沙箱化，对于执行代码或命令的工具，尽量在容器或受限环境中运行。

# 工具注册的 schema 示例 { "name": "read_file", "description": "读取指定路径的文件内容，返回文本。适用于查看代码、配置、日志等。", "parameters": { "type": "object", "properties": { "path": { "type": "string", "description": "文件路径，支持相对路径和绝对路径" }, "max_lines": { "type": "integer", "description": "最多读取行数，默认 500", "default": 500 } }, "required": ["path"] } }

实操心得：工具的输出一定要做截断。一个ls -R可能返回几万行，直接塞回上下文会瞬间撑爆窗口。我的做法是默认截断到 2000 字符，如果模型需要更多，让它用分页参数再次调用。

2.4 Memory & Context：记住该记的，忘掉该忘的

Memory 子系统负责管理 Agent 的短期和长期记忆。短期记忆就是当前任务的上下文，长期记忆是跨任务、跨会话的知识积累。很多人把这两者混在一起，结果要么上下文爆炸，要么 Agent 像个失忆患者。

短期记忆的管理核心是上下文窗口的分配。一个典型的上下文包含：系统提示词、工具定义、历史对话、当前任务描述、工具执行结果。系统提示词和工具定义通常占固定开销，历史对话和工具结果占大头。Harness 需要动态决定给历史留多少空间，什么时候触发压缩。

压缩策略我常用的是“滑动窗口 + 摘要”。保留最近 K 轮完整对话，更早的内容用 LLM 生成一段摘要，摘要里保留关键决策、重要发现、未完成事项。摘要的 prompt 要专门调优，确保不丢失关键信息。另一个技巧是给工具结果打标签，重要的结果标记为“不可压缩”，普通结果可以压缩或丢弃。

长期记忆的实现方式有多种：向量数据库做语义检索、结构化数据库存事实、文件系统存笔记。选择哪种取决于你的场景。如果是个人助理类 Agent，向量库加文件笔记就够了；如果是企业级应用，可能需要更复杂的知识图谱。关键是要有写入和读取的明确策略：什么时候写入记忆、写入什么、怎么检索、检索结果怎么融入上下文。

2.5 Planning & Task Decomposition：把大任务拆成小步骤

Planning 子系统让 Agent 具备“先想后做”的能力。面对一个复杂任务，比如“帮我分析这个项目的代码质量并生成报告”，Agent 需要先拆解成子任务：读取项目结构、分析代码文件、统计指标、生成报告。没有 Planning，Agent 容易东一榔头西一棒子，或者陷入细节忘了全局。

实现 Planning 有两种主流方式。一种是显式规划：让 LLM 先输出一个任务列表，然后 Harness 按列表逐步执行，每完成一步更新状态。这种方式可控性强，适合步骤明确的场景。另一种是隐式规划：不单独生成计划，而是在 Agent Loop 中通过系统提示词引导模型“先思考再行动”，让规划融入每一轮决策。这种方式更灵活，但可控性弱一些。

我通常采用混合策略：对于复杂任务，先让模型生成一个高层计划（3-7 步），然后每一步的执行仍然走 Agent Loop，允许模型在执行中调整后续步骤。计划本身作为上下文的一部分，每完成一步就标记状态。如果执行中发现计划不可行，允许模型重新规划。

任务拆解的粒度很关键。拆得太粗，单步太复杂容易失败；拆得太细，步骤太多管理成本高。经验值是每个子任务能在 1-3 轮工具调用内完成。如果某个子任务需要超过 5 轮，考虑进一步拆分。

注意：Planning 不是必须的。对于简单任务，直接让 Agent Loop 跑就行，强行加规划反而增加开销和出错概率。判断标准是：任务是否需要多个不同类型的工具协作、是否有明确的阶段划分、是否容易在中途迷失方向。

2.6 Error Handling & Recovery：出错了怎么兜住

Error Handling 是 Harness 里最容易被忽视、但生产环境最不能少的部分。Agent 执行过程中会遇到各种错误：工具调用失败、LLM 返回格式错误、超时、权限不足、外部服务不可用。没有好的错误处理，Agent 一遇到问题就崩溃，用户体验极差。

错误处理的核心思路是分类处理 + 优雅降级。我把错误分成几类：可重试错误（网络抖动、限流），用指数退避重试；可修正错误（参数格式错、工具名错），把错误信息返回给 LLM 让它重新生成；不可恢复错误（权限不足、资源不存在），终止当前步骤并报告；致命错误（上下文溢出、内部状态损坏），终止整个任务并清理。

Recovery 机制包括：检查点，在关键步骤后保存状态，失败时可以从检查点恢复；回滚，对于有副作用的操作，失败时撤销已完成的部分；降级，主方案失败时切换到备用方案，比如主模型不可用切备用模型，复杂工具失败切简单工具。

# 错误分类处理的示意 def handle_tool_error(error, tool_call, context): if is_retryable(error): return retry_with_backoff(tool_call) elif is_fixable(error): context.append({ "role": "system", "content": f"工具调用失败：{error}。请修正参数后重试。" }) return "retry_llm" elif is_fatal(error): raise AgentFatalError(error) else: return f"工具执行失败：{error}，请尝试其他方法。"

我踩过的一个坑是：工具执行超时后，底层进程没有真正被杀掉，导致资源泄漏。后来在超时处理里加了强制终止逻辑，并且对每个工具调用记录开始和结束时间，定期清理僵尸进程。

2.7 Observability & Control：看得见才管得住

Observability 子系统负责记录 Agent 的一举一动，包括每轮 LLM 调用的输入输出、工具调用的参数和结果、耗时、token 消耗、错误信息。没有可观测性，Agent 就是个黑盒，出了问题只能靠猜。

日志要结构化，方便查询和分析。我通常记录这几个维度：时间线，每个事件的开始结束时间；调用链，把 LLM 调用和工具调用关联起来；资源消耗，token 数、API 调用次数、执行时长；状态变更，上下文压缩、计划更新、错误恢复。这些数据不仅能用于排查问题，还能用于优化——比如发现某个工具调用特别频繁但效果不好，就可以调整它的描述或参数。

Control 部分提供人工干预的接口。生产环境的 Agent 不能完全放任自流，需要支持：暂停/恢复，让操作员在关键时刻介入；审批，敏感操作需要人工确认；终止，发现异常时立即停止；注入，人工补充信息或修正方向。这些控制点要设计得自然，不能打断正常流程。

3. 七个子系统怎么串起来跑

3.1 一次完整任务的执行流程

把七个子系统串起来看，一次典型任务的执行流程是这样的：用户提交任务，Harness 初始化上下文，加载工具定义和系统提示词。Planning 子系统判断是否需要拆解，如果需要就生成计划。然后进入 Agent Loop，每一轮调用 LLM Integration 获取决策，如果是工具调用就交给 Tool Registry 查找并执行，执行结果经过 Memory 子系统处理后追加到上下文。如果出错，Error Handling 介入决定重试、修正还是终止。整个过程由 Observability 记录，Control 提供干预入口。任务完成后，结果返回用户，长期记忆写入 Memory。

这个流程里，Agent Loop 是主干，其他子系统是挂在主干上的功能模块。设计时要保证模块之间的接口清晰，比如 Tool Execution 只负责执行和返回结果，不关心结果怎么进上下文；Memory 只负责存储和检索，不关心内容从哪来。这样每个模块可以独立测试和替换。

3.2 并发场景下的隔离与调度

单 Agent 跑通了，下一步就是扛并发。多个任务同时跑，每个任务有自己的 Agent 实例和上下文，互不干扰。Harness 需要一层任务调度器，管理任务队列、分配资源、控制并发数。关键点是状态隔离：每个任务的上下文、记忆、工具执行环境都要独立，不能共享可变状态。

资源限制也要考虑。LLM API 通常有速率限制，工具执行可能消耗 CPU 和内存。调度器要根据资源情况动态调整并发数，避免把下游服务打挂。我的做法是给每类资源设一个信号量，任务执行前先获取资源许可，执行完释放。同时监控队列长度和平均等待时间，超过阈值就告警。

3.3 从零搭建的最小可行 Harness

如果你想从零搭一个最小可用的 Harness，我建议按这个顺序来：先实现 Agent Loop 和 LLM Integration，让 Agent 能跑起来；然后加 Tool Registry 和 Execution，让它能干活；接着加 Memory 的上下文压缩，解决窗口溢出；再加 Error Handling，提高鲁棒性；最后加 Observability，方便调试。Planning 和 Control 可以后面按需加。

代码结构上，建议把每个子系统做成独立的模块或类，通过明确的接口交互。比如AgentLoop依赖LLMClient、ToolExecutor、MemoryManager，但不依赖它们的具体实现。这样你可以先写简单的实现跑通流程，再逐步替换成更完善的版本。

# 最小 Harness 的组装示意 class Harness: def __init__(self, llm_client, tool_registry, memory, error_handler): self.llm = llm_client self.tools = tool_registry self.memory = memory self.error_handler = error_handler self.loop = AgentLoop(self.llm, self.tools, self.memory) def run(self, task): try: return self.loop.execute(task) except Exception as e: return self.error_handler.handle(e, task)

4. 实操中常见的坑与排查技巧

4.1 工具调用格式解析失败

这是最常见的问题。模型返回的工具调用 JSON 可能有多余的转义字符、缺少闭合括号、参数类型不对。排查时先把原始返回打印出来，看看格式到底哪里不对。解决思路是在解析器里做容错：尝试多种解析方式，失败后把错误信息返回给模型让它重新生成。另外，在系统提示词里明确工具调用的格式要求，能显著降低出错率。

4.2 上下文窗口溢出

症状是 Agent 跑着跑着突然报错，或者开始胡言乱语。原因是上下文太长，超出了模型窗口。排查时记录每轮上下文的 token 数，找到增长最快的部分。通常是工具结果太大。解决办法是在工具层做截断和摘要，在 Memory 层做压缩，同时设置上下文长度的硬性上限，超过就强制压缩。

4.3 Agent 陷入死循环

Agent 反复调用同一个工具，或者在不同工具之间来回切换，始终不结束。排查时看日志里最近几轮的工具调用是否重复。解决办法是设置最大轮次限制，同时检测重复调用——如果连续两轮调用相同工具且参数相同，就中断并提示模型换方法。另外，在系统提示词里明确“如果多次尝试无效，请报告失败原因并停止”。

4.4 工具执行超时或卡死

某个工具调用长时间不返回，整个 Agent 卡住。排查时看是哪个工具、什么参数导致的。解决办法是给每个工具调用设置超时，超时后强制终止并返回错误。对于可能长时间运行的工具，考虑改成异步执行，让 Agent 先继续其他步骤，稍后检查结果。

4.5 并发下的状态污染

多个任务同时跑时，一个任务的数据出现在另一个任务的上下文里。排查时检查是否有全局可变状态被共享。解决办法是确保每个 Agent 实例有独立的上下文、记忆和执行环境，工具执行也要隔离，避免使用全局变量。

实操心得：我习惯在开发阶段给每个 Agent 实例打一个唯一 ID，所有日志都带上这个 ID，排查并发问题时能快速定位是哪个任务出的问题。

5. 关于 Harness 设计的一些个人体会

搭过几个 Agent 之后，我最大的体会是：Harness 的复杂度不在于单个子系统有多难，而在于它们之间的交互和边界情况。一个在单任务下跑得好好的 Harness，放到并发环境可能到处是坑；一个在理想输入下表现完美的 Agent，遇到格式错误的工具返回就可能崩溃。所以设计时要始终想着“哪里可能出错”“出错后怎么恢复”“怎么让问题可见”。

另一个体会是不要过度设计。刚开始搭的时候，七个系统不需要都做到完善。先把 Agent Loop、LLM Integration、Tool Execution 跑通，让 Agent 能完成简单任务，然后再逐步加 Memory、Error Handling、Observability。Planning 和 Control 可以最后加。每加一个子系统，都要有明确的收益，不要为了架构好看而加。

最后分享一个小技巧：给 Harness 写一套“冒烟测试”，用几个典型任务快速验证各个子系统是否正常。比如一个只用 LLM 回答的任务、一个调用单个工具的任务、一个需要多轮工具调用的任务、一个故意触发错误的任务。每次改动后跑一遍，能快速发现回归问题。这套测试花不了多少时间，但能省下大量调试功夫。