1. 为什么“能跑”和“稳定”之间隔着一整个 Harness 工程做 AI Agent 的人大概都经历过这个阶段Demo 跑通了工具调用也接上了模型能根据用户输入自主决定调哪个 API、传什么参数看起来一切都很美好。但一旦把它放到真实场景里连续跑上几十轮对话问题就开始冒出来——工具调用参数格式偶尔飘了、多轮上下文里模型忘了自己刚才做过什么、某个外部接口超时之后整个链路直接卡死、同一个操作被重复执行了两次导致数据写重。这些问题的共同点是它们都不是模型能力本身的问题而是模型外面那一层“工程外壳”没做好。这层外壳就是 Harness。Harness 这个词在 AI Agent 语境下指的是包裹在模型外面的整套运行时基础设施——它负责把模型的输出解析成可执行的动作、管理工具调用的生命周期、维护对话状态和记忆、处理错误和重试、控制执行边界和安全策略。你可以把它理解成 Agent 的“操作系统层”模型是 CPU负责推理和决策Harness 是内核负责调度、隔离、容错和资源管理。没有 Harness 的 Agent 就是一个裸奔的推理循环能跑但不可靠有了 HarnessAgent 才具备在生产环境里持续稳定运行的基础。这篇文章面向的是已经动手搭过 Agent、踩过一些坑、想把系统从“能演示”推进到“能上线”的开发者。我会从 Harness 的核心机制出发拆解一个稳定 Agent 系统需要哪些关键模块、每个模块的设计取舍是什么、实际落地时哪些地方最容易出问题以及我自己在反复调试中总结出来的一些经验。全文会涉及具体的架构思路、参数配置、代码层面的实现要点和排查方法尽量做到看完就能对照自己的项目做检查。2. Harness 工程的整体架构与核心设计思路2.1 Harness 和 Agent 的关系别把两者混为一谈很多人第一次听到 Harness 这个词会困惑它和 Agent 到底什么关系简单说Agent 是一个概念——一个能感知环境、做出决策、执行动作的智能体。Harness 是这个概念的具体工程实现。你写了一个 Python 脚本里面有个 while 循环不断调 LLM、解析输出、执行工具、把结果塞回上下文这个 while 循环加上它周围的所有辅助代码就是最简陋的 Harness。那为什么需要把它单独拿出来讲因为当系统变复杂之后这个“周围的所有辅助代码”会膨胀成一个庞大的子系统它的复杂度甚至超过模型调用本身。我见过不少项目模型调用部分只有两三百行但 Harness 层的代码有几千行——状态管理、错误处理、并发控制、日志追踪、权限校验、速率限制、缓存策略每一项都需要仔细设计。一个设计良好的 Harness 应该具备以下核心能力输入输出规范化把用户的自然语言输入转成模型能理解的格式把模型的输出解析成结构化的动作指令工具调用编排管理工具的注册、发现、调用、超时、重试和结果回传状态与记忆管理维护对话历史、工作记忆、长期记忆并在合适的时机注入上下文错误处理与恢复捕获各类异常决定是重试、降级还是终止并保证状态一致性执行边界控制限制 Agent 的行为范围防止越权操作或无限循环可观测性记录每一步的输入输出、耗时、token 消耗便于调试和优化这六项能力缺一不可。少任何一项系统在特定场景下就会表现出不可预测的行为。2.2 为什么选择“分层解耦”而不是“单体循环”最直觉的做法是把所有逻辑写在一个大循环里调模型、解析、执行、拼结果、再调模型。这种写法在原型阶段没问题但一旦需要修改任何一环就会牵一发而动全身。我早期做过一个项目就是这种结构后来想加一个“工具调用前先做参数校验”的功能结果发现校验逻辑散落在七八个地方改完一处忘了另一处测试覆盖不全上线后出了好几次参数注入的 bug。后来我改成分层架构把 Harness 拆成四个独立的层层级职责典型实现接入层接收用户输入做初步的格式校验和预处理输入解析器、意图预分类编排层管理 Agent 的执行循环决定何时调模型、何时执行工具状态机、执行计划器执行层实际调用工具和外部服务处理超时和重试工具注册表、调用代理观测层记录全链路日志、指标和追踪信息结构化日志、Span 追踪分层的核心好处是每一层可以独立测试和替换。比如我想换一个工具调用协议只需要改执行层编排层和接入层完全不受影响。这种解耦在系统演进过程中节省的时间是巨大的。2.3 状态管理Agent 稳定性的根基Agent 和普通程序最大的区别在于它是有状态的。普通函数调用给定相同输入永远返回相同输出但 Agent 的行为依赖于之前发生过什么。状态管理没做好Agent 就会表现出“精神分裂”——同一轮对话里前后矛盾或者重复执行已经完成的操作。我在实际项目中把 Agent 的状态分成三类来管理对话状态是最外层的东西记录用户和 Agent 之间的完整交互历史。这部分通常直接放在上下文窗口里但要注意控制长度超出窗口限制时需要做摘要或截断。任务状态记录当前正在执行的任务的进度。比如一个多步骤的数据处理任务已经完成了哪几步、当前在哪一步、下一步该做什么。这部分状态需要持久化因为 Agent 可能在中途因为超时或错误而中断恢复后需要从断点继续。工具状态记录每个工具的调用历史和当前状态。比如某个 API 的调用频率、上次调用的返回值、是否有未完成的异步操作。这部分状态对于避免重复调用和处理幂等性至关重要。状态管理的难点不在于存储而在于一致性。当 Agent 同时进行多个操作时如何保证状态更新不会互相覆盖我的做法是给每个状态变更操作加一个版本号更新时做乐观锁检查冲突时回滚重试。这个机制在并发场景下救过我好几次。3. 核心机制拆解从工具调用到错误恢复3.1 工具调用的完整生命周期工具调用是 Agent 最核心的能力也是最容易出问题的环节。一个完整的工具调用生命周期包含以下阶段意图识别模型决定需要调用某个工具输出工具名称和参数参数解析Harness 解析模型输出的参数做格式校验和类型转换权限检查确认当前上下文是否有权限调用该工具前置校验检查参数的业务合法性比如日期格式、ID 是否存在执行调用实际发起调用设置超时和重试策略结果处理解析返回值处理异常情况状态更新更新工具状态和任务状态结果回传把处理后的结果格式化后塞回模型上下文这八个步骤里第 2 步和第 5 步是最容易出问题的。参数解析的难点在于模型输出的格式并不总是稳定的——即使你在 prompt 里明确要求输出 JSON模型偶尔还是会输出带 markdown 代码块包裹的 JSON或者在某些字段上使用不同的命名风格。我的做法是在解析层做容错处理先尝试严格解析失败后尝试提取 JSON 子串再失败则尝试用正则提取关键字段最后才报错让模型重新生成。执行调用的难点在于超时和重试的策略设计。不是所有工具都适合重试——查询类工具重试是安全的但写入类工具重试可能导致数据重复。我的做法是给每个工具打上标签标记它是否幂等然后根据标签决定重试策略TOOL_REGISTRY { search_database: {idempotent: True, timeout: 10, max_retries: 3}, send_email: {idempotent: False, timeout: 30, max_retries: 0}, update_record: {idempotent: False, timeout: 15, max_retries: 1}, }对于非幂等工具重试前需要先做一次状态查询确认上一次调用是否已经生效。这个检查逻辑虽然增加了一次调用开销但避免了数据不一致的风险。3.2 上下文窗口管理不只是截断那么简单Agent 跑多轮对话时上下文会不断增长最终超出模型的窗口限制。最简单的做法是直接截断最早的消息但这会导致 Agent 丢失关键信息。我试过几种策略最后总结出一套组合方案滑动窗口加摘要是最常用的方法。保留最近 N 轮完整对话对更早的对话生成摘要。摘要的生成时机很关键——不能每轮都生成那样开销太大也不能等到窗口满了才生成那样可能来不及。我的做法是当上下文使用率达到 70% 时触发摘要把最早 30% 的消息压缩成一段摘要文本。关键信息提取是补充手段。从对话历史中提取出实体、决策和约束条件以结构化格式单独存储。每次构建上下文时把这些关键信息以系统消息的形式注入确保 Agent 不会忘记重要约束。工具结果压缩经常被忽略。工具返回的结果可能很长比如一个数据库查询返回了几十条记录。全部塞进上下文会迅速消耗窗口。我的做法是对工具结果做预处理如果结果超过阈值只保留关键字段和统计摘要详细数据存到外部存储在上下文里放一个引用 IDAgent 需要时再通过工具查询。注意上下文管理策略需要根据具体模型做调整。不同模型对上下文位置的敏感度不同有些模型对开头和结尾的信息记得更牢中间部分容易忽略。构建上下文时要把最重要的信息放在开头或结尾。3.3 错误恢复让 Agent 从失败中站起来Agent 在执行过程中会遇到各种错误模型输出格式错误、工具调用超时、外部服务不可用、参数校验失败、权限不足等等。一个稳定的 Harness 需要能够区分这些错误类型并采取不同的恢复策略。我把错误分成三个等级可恢复错误包括格式解析失败、临时性网络超时、速率限制等。这类错误通过重试或重新生成通常能解决。处理策略是记录错误信息在上下文里插入一条错误提示让模型重新尝试。重试次数上限设为 3 次超过后升级为不可恢复错误。可降级错误包括某个工具暂时不可用、某个数据源响应过慢等。这类错误不影响整体任务完成但需要调整执行路径。处理策略是标记该工具为不可用在后续决策中排除该选项同时通知模型当前的能力限制。不可恢复错误包括权限不足、参数根本性错误、外部服务永久下线等。这类错误需要终止当前任务向用户报告。处理策略是保存当前状态生成错误报告清理资源退出执行循环。错误恢复的关键在于状态一致性。当错误发生时必须确保已经执行的操作被正确记录未完成的操作被正确回滚。我见过一个案例Agent 在调用一个写入接口时超时了Harness 直接重试结果数据被写入了两次。后来加了幂等键才解决。这个教训说明错误恢复策略必须和工具本身的特性配合设计。3.4 执行边界控制防止 Agent 跑偏Agent 的自主性是一把双刃剑。它能灵活应对各种情况但也可能做出意料之外的操作。执行边界控制就是给 Agent 划出安全范围。最大步数限制是最基本的控制。设置一个硬上限比如 50 步超过就强制终止。这个限制防止 Agent 陷入无限循环。但步数设置需要根据任务复杂度调整太少了任务做不完太多了浪费资源。工具白名单控制 Agent 能调用哪些工具。不是所有工具都适合让 Agent 自主调用有些敏感操作需要人工确认。我的做法是把工具分成三档自动执行、需确认、禁止调用。Agent 只能自动执行第一档第二档需要用户确认第三档直接拒绝。参数范围校验防止 Agent 传入危险参数。比如删除操作必须带明确的 ID不能是通配符查询操作必须带分页限制不能一次拉全表。这些校验在 Harness 层做不依赖模型的自觉。循环检测识别重复行为。如果 Agent 连续三次调用同一个工具且参数相同大概率是陷入了循环。Harness 检测到这种情况后应该中断执行把控制权交还给用户或触发降级逻辑。4. 实操落地从零搭建一个可用的 Harness4.1 最小可行 Harness 的代码结构说了这么多理论来看一个实际可用的 Harness 骨架。以下是一个简化但完整的实现用 Python 编写核心逻辑不依赖特定框架import json import time import logging from dataclasses import dataclass, field from typing import Any, Callable, Optional from enum import Enum class ToolStatus(Enum): SUCCESS success TIMEOUT timeout ERROR error REJECTED rejected dataclass class ToolResult: status: ToolStatus data: Any None error: Optional[str] None elapsed: float 0.0 dataclass class AgentState: conversation: list field(default_factorylist) task_progress: dict field(default_factorydict) tool_history: list field(default_factorylist) step_count: int 0 max_steps: int 50 version: int 0 class Harness: def __init__(self, model_client, tools: dict, config: dict None): self.model model_client self.tools tools self.config config or {} self.state AgentState() self.logger logging.getLogger(harness) def run(self, user_input: str) - str: self.state.conversation.append({role: user, content: user_input}) while self.state.step_count self.state.max_steps: self.state.step_count 1 response self._call_model() action self._parse_action(response) if action[type] final_answer: return action[content] elif action[type] tool_call: result self._execute_tool(action) self._inject_result(action, result) else: self._inject_error(无法解析模型输出) return 任务执行步数超出限制已终止。 def _call_model(self) - str: messages self._build_context() return self.model.chat(messages) def _build_context(self) - list: context self.state.conversation[-20:] system_msg { role: system, content: f当前任务进度{json.dumps(self.state.task_progress, ensure_asciiFalse)} } return [system_msg] context def _parse_action(self, response: str) - dict: try: data json.loads(response) return data except json.JSONDecodeError: pass import re match re.search(r\{.*\}, response, re.DOTALL) if match: try: return json.loads(match.group()) except json.JSONDecodeError: pass return {type: unknown, raw: response} def _execute_tool(self, action: dict) - ToolResult: tool_name action.get(tool) params action.get(params, {}) if tool_name not in self.tools: return ToolResult(statusToolStatus.REJECTED, errorf工具 {tool_name} 不存在) tool self.tools[tool_name] start time.time() try: result tool[fn](**params) elapsed time.time() - start self.state.tool_history.append({ tool: tool_name, params: params, status: success, elapsed: elapsed }) return ToolResult(statusToolStatus.SUCCESS, dataresult, elapsedelapsed) except TimeoutError: return ToolResult(statusToolStatus.TIMEOUT, error调用超时) except Exception as e: return ToolResult(statusToolStatus.ERROR, errorstr(e)) def _inject_result(self, action: dict, result: ToolResult): content json.dumps({ tool: action.get(tool), status: result.status.value, data: result.data if result.status ToolStatus.SUCCESS else None, error: result.error }, ensure_asciiFalse) self.state.conversation.append({role: tool, content: content}) def _inject_error(self, msg: str): self.state.conversation.append({role: system, content: f错误{msg}})这个骨架包含了前面提到的核心机制状态管理、工具调用、错误处理、上下文构建和步数限制。实际项目中需要在此基础上扩展权限校验、重试策略、日志追踪和持久化。4.2 工具注册与参数校验的实操细节工具注册看起来简单但有几个细节决定了系统的健壮性。首先是参数 schema 的定义我建议用 JSON Schema 来约束每个工具的参数格式TOOL_SCHEMAS { query_order: { type: object, properties: { order_id: {type: string, pattern: ^ORD[0-9]{10}$}, fields: {type: array, items: {type: string}, maxItems: 10} }, required: [order_id] } }有了 schema 之后在调用工具前做一次校验不通过就直接返回错误让模型重新生成参数。这一步能拦截掉大部分因为模型幻觉导致的参数错误。其次是工具描述的质量。模型选择工具的依据是工具的名称和描述描述写得不好模型就会选错工具或者传错参数。我的经验是描述里要包含工具的功能、适用场景、不适用场景、参数含义和示例。比如{ name: query_order, description: 根据订单号查询订单详情。适用于用户询问某个具体订单的状态、金额、物流信息。不适用于查询订单列表或统计信息。order_id 必须是 ORD 开头加 10 位数字的格式例如 ORD1234567890。, parameters: TOOL_SCHEMAS[query_order] }这段描述比简单写一句“查询订单”要有效得多。实测下来模型选错工具的概率明显降低。4.3 日志与可观测性的落地方法Agent 系统的调试难度远高于普通程序因为它的行为不是确定性的。没有完善的日志出了问题根本不知道是哪一步导致的。我在每个关键节点都打结构化日志def log_step(self, step_type: str, data: dict): entry { timestamp: time.time(), step: self.state.step_count, type: step_type, data: data, state_version: self.state.version } self.logger.info(json.dumps(entry, ensure_asciiFalse))关键是要记录模型输入完整的上下文、模型输出原始文本、解析后的动作、工具调用参数和结果、状态变更前后的值。这些信息在排查问题时缺一不可。除了日志我还建议加两个指标每步耗时和token 消耗。耗时异常通常意味着某个工具调用卡住了token 消耗异常增长可能意味着上下文管理出了问题。这两个指标能帮你快速定位性能瓶颈。实操心得日志里不要记录敏感信息比如用户密码、API 密钥、个人身份信息。在记录前做一次脱敏处理把敏感字段替换成掩码。5. 常见问题与排查技巧实录5.1 模型输出格式不稳定怎么办这是最高频的问题。即使你在 prompt 里千叮咛万嘱咐要输出 JSON模型还是会在某些情况下输出多余的文字、markdown 代码块或者格式错误的 JSON。我的应对策略是三层防护第一层是在 prompt 里给出明确的格式示例并且用 few-shot 的方式展示正确和错误的输出对比。第二层是在解析时做容错先尝试直接解析失败后提取 JSON 子串再失败用正则提取关键字段。第三层是解析彻底失败时把错误信息回传给模型让它重新生成同时降低 temperature 参数。实测下来这三层防护能把格式错误导致的任务失败率降到 1% 以下。5.2 工具调用超时和重试怎么设计超时设置需要根据工具的实际响应时间分布来定。我的做法是先跑一轮压测收集每个工具的 P50、P95 和 P99 响应时间然后把超时设为 P99 的 1.5 倍。这样既能覆盖绝大多数正常请求又不会让异常请求等太久。重试策略要区分错误类型。网络超时和 5xx 错误可以重试4xx 错误通常重试也没用。重试间隔用指数退避第一次等 1 秒第二次等 2 秒第三次等 4 秒。对于非幂等操作重试前必须做状态检查。5.3 Agent 陷入循环怎么破循环的典型表现是 Agent 反复调用同一个工具或者反复输出相似的内容。检测方法很简单维护一个最近 N 步的动作哈希如果出现重复就触发告警。处理循环的策略有三种一是注入一条系统消息提醒 Agent 当前操作已经重复要求它换一种方式二是强制中断把控制权交还给用户三是触发降级逻辑用预设的兜底方案完成任务。我通常先用第一种无效再用第二种。5.4 上下文丢失关键信息怎么排查如果 Agent 在多轮对话后忘记了之前的约束或决策大概率是上下文管理出了问题。排查步骤是先检查上下文构建逻辑确认关键信息是否被包含再检查摘要生成的质量看摘要是否丢失了重要细节最后检查模型对上下文中不同位置的敏感度调整信息摆放位置。一个实用的技巧是在系统消息里维护一个“当前有效约束”列表每次构建上下文时都带上。这样即使对话历史被截断约束也不会丢失。问题现象可能原因排查方法解决策略工具调用参数格式错误模型输出不稳定检查原始输出加 few-shot 示例增强解析容错同一操作重复执行缺少幂等控制检查工具历史加幂等键重试前做状态检查多轮后忘记约束上下文被截断检查上下文构建关键信息单独存储并注入任务中途卡死工具超时未处理检查超时日志设置合理超时加降级逻辑token 消耗异常增长上下文膨胀检查每轮 token 数压缩工具结果及时生成摘要5.5 几个容易忽略的坑时区问题工具返回的时间戳如果不带时区信息Agent 在计算时间差时可能出错。统一用 UTC 时间并在上下文里明确标注。编码问题中文、emoji 和特殊字符在 JSON 序列化和反序列化时容易出问题。确保所有环节都用 UTF-8并且在解析时处理转义字符。并发问题如果 Agent 支持并行工具调用状态更新需要加锁。我见过因为并发写入导致状态覆盖的案例排查了很久才发现。模型版本切换不同版本的模型对同一 prompt 的响应可能不同。切换模型版本后要重新跑一遍回归测试确认关键行为没有变化。6. 从可用到可靠持续演进的几个方向Harness 工程不是一次性的工作它需要随着 Agent 能力的扩展和业务场景的变化持续演进。我在实际项目里总结了几个值得投入的方向。自动化回归测试是首要任务。Agent 的行为难以用传统单元测试覆盖但可以构建一套场景化的回归测试集准备一批典型的用户输入和预期行为每次修改 Harness 后自动跑一遍对比实际输出和预期输出的差异。这套测试集不需要覆盖所有情况但要把核心路径和已知的边界情况都包含进去。性能剖析与优化是第二个方向。Agent 的响应延迟由模型推理时间和工具调用时间共同决定。通过埋点数据可以清楚地看到时间花在哪里。如果模型推理占大头考虑换更快的模型或优化 prompt 长度如果工具调用占大头考虑加缓存或并行调用。安全加固是第三个方向。随着 Agent 能调用的工具越来越多安全边界的重要性也在上升。除了前面提到的白名单和参数校验还需要考虑 prompt 注入攻击的防护——用户可能在输入里嵌入恶意指令试图让 Agent 执行非预期操作。防护方法包括输入清洗、指令隔离和输出审查。可配置化是第四个方向。不同场景对 Agent 的行为要求不同硬编码的策略很难适应变化。把关键参数最大步数、超时时间、重试次数、上下文窗口大小做成配置项通过配置文件或环境变量注入能让同一套 Harness 适配多种场景。我在最近一个项目里把 Harness 的配置抽成了一个 YAML 文件不同业务线用不同的配置代码完全复用。这个改动让新场景的接入时间从两天缩短到了两小时。最后分享一个我在调试 Agent 时常用的小技巧把每一轮的完整上下文和模型输出保存成单独的文件按步骤编号命名。出问题时直接打开对应的文件就能看到模型当时“看到”了什么、“想”了什么、“做”了什么。这个习惯帮我省下了大量猜测的时间推荐你也试试。