1. 从“模型很强但不好用”说起Harness 到底在解决什么问题大模型本身是个“裸脑”。你给它一段 prompt它回你一段文本仅此而已。但真实业务里我们要的是它能读文件、能调接口、能记住上下文、能在多轮里保持状态、能在出错时重试、能把一个复杂任务拆成若干步跑完。这些能力模型自己给不了得靠外面套一层“壳”来补齐。这层壳就是 Harness。很多人第一次听到 Harness 这个词会懵因为它不像 Agent 那么直观。Agent 是“智能体”一听就知道是干活的主体Harness 直译是“马具、挽具”听起来像是给马套的装备。这个比喻其实非常精准——模型是那匹力气很大的马Harness 就是把它套住、引导它往正确方向跑的那套挽具。没有挽具马能跑但你控制不了它往哪跑、跑多快、什么时候停。所以 Harness 的本质是围绕大模型构建的一整套运行时控制层它负责把模型的原始输出转化为可执行的动作把外部世界的反馈重新喂回模型并在整个循环里管理状态、约束行为、处理异常。OpenHarness 就是这样一个框架。它不是一个模型也不是一个单纯的 SDK而是一套帮你把“模型能力”变成“可用系统”的工程骨架。你可以在它上面挂不同的模型本地跑的、API 调的都行定义不同的工具配置不同的记忆策略然后它负责把这一整套东西串起来跑通。这篇文章面向的是想真正把大模型用起来的开发者。不管你是刚接触 Agent 开发的新手还是已经用其他框架搭过一些 demo、但总觉得“跑起来容易、跑稳难”的老手下面这些内容应该都能帮你少走一些弯路。我会从 Harness 和 Agent 的区别讲起然后一步步拆 OpenHarness 的核心结构、工具接入、记忆管理、执行循环最后聊几个实际踩过的坑。提示本文所有代码示例以 Python 为主假设你已经具备基本的 Python 编程能力并且本地或远程有一个可用的大模型接口。如果你还没配好模型环境先把这一步搞定再往下看否则后面跑不起来会很挫败。2. Harness 和 Agent 到底差在哪一个容易被混淆的核心概念2.1 从“谁在做决定”这个角度切进去很多人把 Harness 和 Agent 当成同义词用这在口语里问题不大但在工程上会带来严重的认知混乱。我见过不少项目代码里 Agent 类既负责调模型、又负责管状态、又负责执行工具、还负责重试逻辑一个文件两千行改一处崩三处。这就是没把 Harness 和 Agent 的职责分清楚。用一个类比来说Agent 是“司机”Harness 是“车”。司机决定去哪、怎么走车提供方向盘、油门、刹车、仪表盘并且保证司机踩油门时车真的会动。司机可以换车也可以换两者是解耦的。具体到代码层面Agent 通常包含的是决策逻辑——给定当前状态下一步该调哪个工具、该生成什么回复。而 Harness 包含的是执行逻辑——怎么把 Agent 的决策变成实际的动作怎么把动作的结果收集回来怎么在出错时保护整个流程不崩。2.2 一张表把职责边界说清楚维度AgentHarness核心职责决策下一步做什么执行把决策落地并管理运行时状态管理通常不关心负责维护对话历史、工具调用记录、中间状态工具执行只输出“我要调某个工具”实际去调处理超时、异常、重试模型交互构造 prompt、解析输出管理模型连接、token 预算、并发控制生命周期一次决策整个任务从开始到结束的完整循环可替换性可以换不同的 Agent 策略可以换不同的模型后端这张表不是学术定义是我自己在拆项目时总结出来的实用边界。你拿它去对照任何一个 Agent 框架基本都能对上。2.3 为什么 OpenHarness 要把这两者分开分开的最大好处是可测试性。Agent 的决策逻辑可以单独测——给它一个状态看它输出什么动作不需要真的调模型、真的执行工具。Harness 的执行逻辑也可以单独测——给它一个动作序列看它能不能正确执行并收集结果不需要关心这个动作是怎么决策出来的。第二个好处是可替换性。你今天用 A 模型做决策明天想换 B 模型只需要换 Agent 层Harness 层不用动。反过来你今天用同步执行明天想改成异步并发只需要换 Harness 层Agent 层不用动。第三个好处是错误隔离。Agent 决策错了最多是选错工具Harness 可以在执行前做校验拦截。Harness 执行挂了Agent 可以收到错误信息后重新决策而不是整个流程直接崩掉。注意如果你之前写的 Agent 代码里混杂了大量执行逻辑建议先别急着迁移到 OpenHarness而是先把职责边界理清楚。带着一团乱麻迁移只会把乱麻搬到新框架里。3. OpenHarness 的骨架拆解四个核心模块与它们的数据流3.1 模块一Model Adapter——把不同模型的差异抹平OpenHarness 的第一个核心模块是模型适配层。它的作用很简单不管你后面接的是哪个模型上层拿到的接口都是一样的。为什么需要这一层因为不同模型的 API 差异比想象中大。有的用messages数组有的用prompt字符串有的支持 function calling有的只支持纯文本有的返回finish_reason有的返回stop_reason。如果 Agent 层直接对接这些差异换模型就是一场灾难。Model Adapter 通常需要实现这几个方法class ModelAdapter: def chat(self, messages, toolsNone, **kwargs): 发送对话请求返回标准化响应 raise NotImplementedError def count_tokens(self, text): 估算 token 数量用于预算控制 raise NotImplementedError def supports_tool_calling(self): 该模型是否原生支持工具调用 raise NotImplementedErrorchat方法的返回值需要标准化成一个统一结构至少包含模型生成的文本内容、是否请求调用工具、请求调用哪些工具及参数、本次消耗的 token 数。这样上层就不用关心底层是哪个模型了。count_tokens这个方法看起来不起眼但在实际项目里非常关键。你需要它来做上下文窗口管理——当对话历史太长时决定截断哪些、保留哪些。不同模型的 tokenizer 不一样粗略估算可以用字符数除以 3 到 4但精确控制还是得用对应模型的 tokenizer。3.2 模块二Tool Registry——工具的注册、发现与调用第二个核心模块是工具注册表。Agent 要干活就得有工具。读文件是工具查数据库是工具调外部 API 也是工具。Tool Registry 负责管理这些工具的元信息和调用入口。一个工具的定义通常包含三部分名称、描述、参数 schema。名称是给模型看的标识符描述是给模型判断“什么时候该用这个工具”的依据参数 schema 是给模型生成调用参数时的约束。from pydantic import BaseModel class ReadFileParams(BaseModel): path: str encoding: str utf-8 def read_file(path: str, encoding: str utf-8) - str: with open(path, r, encodingencoding) as f: return f.read() registry.register( nameread_file, description读取指定路径的文本文件内容, params_modelReadFileParams, funcread_file )这里有个经验工具描述的质量直接决定 Agent 的决策质量。我见过太多项目工具描述写得含糊其辞比如“处理数据”这种模型根本不知道什么时候该调。好的描述应该说清楚这个工具做什么、什么时候用、输入是什么、输出是什么、有什么限制。参数 schema 用 Pydantic 这类库来定义是个好选择因为它能自动生成 JSON Schema 给模型看同时还能在调用前做参数校验。模型生成的参数经常有类型错误或者缺字段有了校验层就能在执行前拦住而不是执行到一半报错。3.3 模块三Memory Store——短期记忆与长期记忆的分层第三个模块是记忆管理。大模型本身是无状态的每次调用都是全新的。要让它在多轮对话里保持连贯就得把历史信息重新喂给它。但上下文窗口有限不能无限往里塞所以需要分层管理。短期记忆就是当前任务的对话历史包括用户输入、模型输出、工具调用记录。这部分通常直接放在上下文里但需要控制长度。长期记忆是跨任务、跨会话的信息比如用户偏好、历史结论、知识片段这部分需要存储和检索。OpenHarness 的记忆层通常提供这几个能力追加把新的对话轮次加入历史截断当历史太长时按策略丢弃旧内容摘要把旧内容压缩成简短摘要保留关键信息检索从长期存储里找出与当前任务相关的片段截断策略有很多种最简单的就是保留最近 N 轮。但这样会丢失早期的重要信息。更好的做法是“保留最近 N 轮 对更早内容做摘要”。摘要可以用模型来做也可以用规则来做看你对成本和质量的权衡。提示记忆管理是 Agent 项目里最容易出问题的地方。我建议在项目早期就把记忆策略定清楚不要等到上下文爆了才临时加截断逻辑那时候往往已经积累了一堆难以复现的 bug。3.4 模块四Execution Loop——整个系统的心脏第四个模块是执行循环这是 Harness 的心脏。它的逻辑用伪代码表示大概是def run(task, max_steps20): state init_state(task) for step in range(max_steps): response agent.decide(state) if response.is_final: return response.content for tool_call in response.tool_calls: result execute_tool(tool_call) state.append(tool_call, result) return 达到最大步数限制任务未完成看起来简单但魔鬼在细节里。execute_tool需要处理超时、异常、重试agent.decide需要处理模型返回格式错误state.append需要处理上下文长度max_steps需要防止无限循环。我实际项目里遇到过几种典型的循环问题模型反复调同一个工具、参数一模一样陷入死循环模型在两个工具之间来回跳始终不给出最终答案模型生成的工具参数格式错误执行失败后又生成同样的错误参数。这些都需要在 Execution Loop 里加防护。常见的防护手段包括检测重复调用并强制中断、设置单步超时、设置总步数上限、对连续失败的工具调用做降级处理。这些不是可选项是必选项。4. 从零搭一个最小可跑的 OpenHarness 实例4.1 环境准备与依赖选择先把环境搭起来。Python 3.10 以上是基本要求因为很多现代 Agent 框架用到了类型注解的新特性。依赖方面核心的几个是模型 SDK看你用哪家、Pydantic参数校验、以及 OpenHarness 本身。pip install openharness pydantic如果你用的是本地模型还需要装对应的推理引擎。这里不展开因为不同引擎差异太大。假设你已经有一个能通过 HTTP 调用的模型接口不管是本地的还是远程的。目录结构建议这样组织project/ agents/ __init__.py my_agent.py tools/ __init__.py file_tools.py api_tools.py config/ settings.py main.py把 Agent、工具、配置分开后面扩展的时候不会乱。我见过把所有东西塞一个文件的写法demo 阶段没问题一旦工具有十几个、Agent 有多个策略就没法维护了。4.2 定义第一个 Agent决策逻辑怎么写Agent 的核心是一个decide方法输入当前状态输出下一步动作。最简单的实现就是把状态转成 prompt调模型解析输出。class SimpleAgent: def __init__(self, model_adapter, tool_registry, system_prompt): self.model model_adapter self.tools tool_registry self.system_prompt system_prompt def decide(self, state): messages [ {role: system, content: self.system_prompt}, *state.to_messages() ] response self.model.chat( messages, toolsself.tools.to_schema() ) return self.parse_response(response)system_prompt是 Agent 的“人格设定”它决定了 Agent 的行为风格。写 system prompt 有几个经验明确角色、明确可用工具、明确输出格式、明确边界。不要写得太长模型记不住也不要写得太短模型会乱来。parse_response负责把模型输出解析成结构化动作。如果模型原生支持 function calling这一步很简单直接读结构化字段就行。如果不支持就得从文本里解析这时候需要约定好输出格式比如要求模型输出 JSON。4.3 注册一组实用工具文件读写与 HTTP 请求工具不在多在于精。新手最容易犯的错是一次性注册几十个工具结果模型选择困难决策质量反而下降。建议从最基础的几个开始读文件、写文件、发 HTTP 请求、执行计算。def write_file(path: str, content: str) - str: with open(path, w, encodingutf-8) as f: f.write(content) return f已写入 {len(content)} 字符到 {path} def http_get(url: str, timeout: int 10) - str: import requests resp requests.get(url, timeouttimeout) return resp.text[:2000] # 截断防止上下文爆炸注意http_get里的截断。外部接口返回的内容可能非常长直接塞进上下文会瞬间占满窗口。截断是一种保护但也要在工具描述里说明“返回内容可能被截断”让模型知道这个限制。工具注册的时候参数类型要写清楚。timeout这种参数给个默认值模型不传也能跑。path这种必填参数要在 schema 里标成 required让模型知道必须提供。4.4 跑通第一个任务让 Agent 读文件并总结现在把上面这些串起来跑一个最简单的任务让 Agent 读一个文件然后总结内容。def main(): model YourModelAdapter(...) registry ToolRegistry() registry.register(read_file, 读取文本文件, ReadFileParams, read_file) registry.register(write_file, 写入文本文件, WriteFileParams, write_file) agent SimpleAgent( model_adaptermodel, tool_registryregistry, system_prompt你是一个文件处理助手。用户让你读文件时调用 read_file 工具。 ) harness Harness(agentagent, max_steps10) result harness.run(读取 notes.txt 并总结成三句话) print(result)跑通之后你会看到 Agent 先调read_file拿到内容然后生成总结。这个过程可能成功也可能失败。失败的原因通常有几类模型没按格式输出工具调用、工具执行报错、模型拿到结果后不给出最终答案。这些都需要在 Harness 层处理。提示第一次跑通之后不要急着加功能。先把这个最小实例跑稳多试几个不同的任务观察 Agent 的行为模式。你对它的“脾气”了解得越深后面加复杂功能时越不容易翻车。5. 工具调用的稳定性超时、重试与参数校验的实战处理5.1 工具执行失败的三种典型场景工具执行失败是常态不是异常。我统计过自己项目里的失败日志大概分三类第一类是超时。调外部 API对方响应慢或者网络抖动请求卡住。这类失败最危险因为它会阻塞整个执行循环。如果不设超时一个卡住的请求能让整个任务挂死。第二类是参数错误。模型生成的参数不符合工具要求比如该传整数传了字符串该传路径传了个描述。这类失败在执行前就能拦住前提是你做了参数校验。第三类是业务异常。工具本身执行了但返回了错误结果。比如读文件时文件不存在调 API 时返回 404。这类失败需要把错误信息回传给模型让它决定下一步怎么办。5.2 超时控制每个工具都要有兜底超时控制的原则是任何可能阻塞的操作都必须有超时。文件读写一般不会阻塞太久但网络请求一定会。给每个工具的执行包一层超时保护import signal class TimeoutError(Exception): pass def with_timeout(func, timeout_sec): def handler(signum, frame): raise TimeoutError(f工具执行超过 {timeout_sec} 秒) signal.signal(signal.SIGALRM, handler) signal.alarm(timeout_sec) try: return func() finally: signal.alarm(0)这是 Unix 系统下的做法Windows 下需要用线程或其他机制。核心思路是一样的给执行设一个上限超了就中断把超时信息作为工具结果返回给模型。模型收到超时信息后通常会尝试换一种方式或者告诉你任务无法完成。这比整个流程卡死要好得多。5.3 重试策略不是所有失败都值得重试重试要有选择性。网络抖动导致的失败重试大概率能成功参数错误导致的失败重试一百次还是失败。所以重试前要先判断失败类型。我的做法是给工具执行结果加一个retryable标记。超时和网络错误标记为可重试参数错误和业务错误标记为不可重试。Harness 在执行循环里根据这个标记决定是否重试。def execute_with_retry(tool_call, max_retries2): for attempt in range(max_retries 1): try: result execute_tool(tool_call) return result except RetryableError as e: if attempt max_retries: return ToolResult(errorstr(e), retryableFalse) continue except NonRetryableError as e: return ToolResult(errorstr(e), retryableFalse)重试之间最好加一个短暂的等待给外部系统一点恢复时间。等待时间可以固定也可以指数递增。我一般用固定的一到两秒太长了会拖慢整体速度。5.4 参数校验在模型和执行之间加一道闸参数校验是性价比最高的防护。用 Pydantic 定义参数模型模型生成的参数先过一遍校验不通过就直接返回错误不执行工具。class ReadFileParams(BaseModel): path: str Field(..., description文件路径) encoding: str Field(utf-8, description编码格式) validator(path) def path_must_exist(cls, v): if not os.path.exists(v): raise ValueError(f文件不存在: {v}) return v校验失败时把具体的错误信息返回给模型。模型看到“文件不存在”这种明确提示通常会调整参数重新尝试而不是盲目重试。这里有个细节校验信息要足够具体。只说“参数错误”模型不知道怎么改说“path 字段必须是存在的文件路径你提供的是 xxx”模型就知道该怎么调整了。6. 记忆管理的坑上下文爆炸、信息丢失与摘要策略6.1 上下文爆炸是怎么发生的上下文爆炸往往不是一次发生的而是慢慢积累的。一开始对话很短没问题。跑了几轮工具调用每次工具返回的内容都塞进历史历史越来越长。到某一轮突然就超了模型的上下文窗口请求直接失败。更隐蔽的问题是即使没超窗口上下文太长也会导致模型注意力分散决策质量下降。我实测过同样的任务上下文控制在 2000 token 以内和放到 8000 token模型的工具选择准确率能差 15% 以上。所以上下文管理不是“超了才处理”而是“从一开始就控制”。6.2 三种截断策略的取舍截断策略我试过三种各有适用场景保留最近 N 轮最简单实现成本最低。适合任务步骤少、每步信息独立的场景。缺点是早期的重要信息会丢比如用户最开始说的约束条件。保留首尾保留最开始的几轮和最近的几轮中间丢掉。适合开头有重要设定的场景。缺点是中间的关键信息可能丢。摘要压缩把旧内容用模型压缩成简短摘要。适合长任务、信息密度高的场景。缺点是要额外调模型有成本。我现在的默认策略是“保留最近 N 轮 对更早内容做摘要”。摘要只在历史超过阈值时触发不是每轮都做控制成本。6.3 摘要怎么写才不丢关键信息摘要的质量直接决定记忆管理的效果。写得不好关键信息丢了Agent 后面就会做出错误决策。我的经验是摘要 prompt 要明确要求保留这几类信息——用户的原始目标、已经确认的事实、已经排除的方案、待解决的问题。不要要求模型“总结对话”那样它会写一堆废话。要给它明确的提取维度。SUMMARY_PROMPT 请从以下对话历史中提取关键信息按以下格式输出 目标用户最初想要完成什么 已确认已经确认的事实或结论 已排除已经尝试但失败的方案 待办还需要解决的问题 对话历史 {history} 这个格式是我迭代了好几次才定下来的。早期版本让模型自由总结结果摘要里全是“用户询问了...助手回答了...”这种没有信息量的内容。改成结构化提取后摘要的可用性大幅提升。6.4 长期记忆的检索什么时候该翻旧账长期记忆是跨会话的比如用户上周让你处理过一个类似任务这周又来了。如果能检索到上次的处理方式就能少走弯路。但检索不是越多越好。检索出来的内容如果和当前任务不相关反而会干扰模型。所以检索要有相关性阈值低于阈值的不返回。实现上最简单的做法是把历史任务存成向量用当前任务去检索最相似的几条。向量化可以用模型做也可以用现成的 embedding 接口。检索出来的内容作为“参考信息”注入上下文而不是作为对话历史。注意长期记忆涉及数据存储和隐私如果你的应用面向多用户一定要做好隔离。不同用户的数据不能混在一起检索否则会出大问题。7. 执行循环的防护死循环检测、步数限制与优雅退出7.1 死循环的几种形态死循环是 Agent 项目里最让人头疼的问题。它不像报错那样直接而是安静地消耗你的 token 和时间。我遇到过几种形态重复调用模型反复调同一个工具参数一模一样。这通常是因为工具返回的结果模型没理解或者模型陷入了某种固定模式。乒乓循环模型在两个工具之间来回跳A 调完调 BB 调完调 A始终不收敛。这通常是因为两个工具的输出互相触发对方的调用条件。无效重试工具执行失败模型重试还是失败再重试。如果失败原因是参数错误重试永远不会成功。7.2 检测机制怎么判断“它在原地打转”检测重复调用最简单的方法是记录最近几次的工具调用签名工具名 参数哈希如果连续 N 次相同就判定为死循环。def is_stuck(recent_calls, threshold3): if len(recent_calls) threshold: return False signatures [call.signature() for call in recent_calls[-threshold:]] return len(set(signatures)) 1乒乓循环的检测稍微复杂一点需要看调用序列的模式。简单做法是检测最近 N 次调用是否在两个签名之间交替。检测到死循环后不要直接崩掉而是给模型一个“你似乎在重复操作请换一种方式或给出最终答案”的提示让它有机会自己跳出来。如果提示后还是重复再强制中断。7.3 步数限制给任务一个硬性边界步数限制是最后的防线。不管有没有检测到死循环总步数到了就停。这个限制要根据任务复杂度来定简单任务 5 到 10 步复杂任务 20 到 30 步。步数到了之后怎么处理我的做法是让 Agent 做一次“收尾决策”——基于当前已有的信息给出一个尽可能完整的回答并说明任务未完全完成的原因。这比直接返回“超时”要有用得多。if step max_steps: final_prompt 已达到最大步数限制。请基于当前已有信息给出你能给出的最完整回答并说明哪些部分未完成。 return agent.finalize(state, final_prompt)7.4 优雅退出让失败也有价值任务失败不可怕可怕的是失败后什么信息都没有。好的 Harness 应该在退出时输出足够的信息让你知道发生了什么、卡在哪里、下次怎么改进。我通常会在退出时输出这几项总步数、每步的工具调用和结果摘要、最终状态、失败原因分类。这些信息对于调试和优化至关重要。class ExecutionTrace: def __init__(self): self.steps [] self.failure_reason None def summary(self): return { total_steps: len(self.steps), tools_used: [s.tool_name for s in self.steps], failure_reason: self.failure_reason, last_state: self.steps[-1] if self.steps else None }这个 trace 在开发阶段直接打印在生产环境可以存日志。有了它排查问题就不用靠猜了。8. 几个我踩过的坑和对应的解法8.1 模型不按格式输出工具调用这是新手最常遇到的问题。你要求模型输出 JSON它给你输出一段带解释的文字JSON 藏在里面。解析失败整个流程就断了。解法有两个方向。一是用原生支持 function calling 的模型从根上避免这个问题。二是如果只能用纯文本模型解析要做得足够宽容——先尝试直接解析失败后用正则提取 JSON 片段再失败就返回错误让模型重试。我现在的做法是解析失败时把“你的输出格式不正确请只输出 JSON不要有其他内容”作为工具结果返回让模型重新生成。通常一两次就能纠正。8.2 工具返回内容太长撑爆上下文外部 API 返回一大段 HTML或者读了一个大文件直接塞进上下文下一轮请求就超了。解法是在工具层面做截断同时在工具描述里说明“返回内容可能被截断”。截断长度根据你的上下文预算来定我一般单个工具返回不超过 2000 字符。如果确实需要处理长内容不要让工具直接返回全文而是让工具返回“文件已读取共 N 字符前 2000 字符如下...”然后提供一个read_more工具让模型按需读取后续部分。8.3 多工具场景下模型选择困难工具一多模型就懵了。我试过注册 20 多个工具结果模型经常选错或者选一个明显不合适的工具。解法是控制工具数量同时优化工具描述。如果确实需要很多工具可以做工具分组——先让模型选组再在组内选具体工具。这样每次决策的候选集就小了。另一个技巧是在 system prompt 里给出工具选择的指引比如“处理文件相关任务时优先使用 file 组工具”。这能显著提升选择准确率。8.4 异步执行带来的状态竞争当 Harness 支持并发执行多个工具时状态管理会变得复杂。两个工具同时修改同一个状态字段结果不可预测。解法是给状态加锁或者设计成不可变状态——每次修改生成新状态而不是原地修改。后者更符合函数式编程的思路也更容易调试。如果并发不是必须的我建议先用同步执行。同步执行慢一点但状态管理简单得多。等同步版本跑稳了再考虑哪些环节可以并发。9. 从能跑到好用性能优化与生产化的几个方向9.1 减少不必要的模型调用每次模型调用都有成本和延迟。有些调用是可以省掉的。比如工具执行成功后如果结果是确定性的不需要再让模型判断下一步可以直接按预设流程走。我一般会把任务分成“需要模型决策”和“不需要模型决策”两类步骤。后者用代码直接串起来前者才走 Agent 循环。这样能省下不少调用。9.2 缓存重复的模型请求同样的 prompt 和参数如果之前调过结果可以直接缓存。这在开发调试阶段特别有用能省大量时间和成本。缓存 key 可以用 prompt 的哈希加上模型标识。注意缓存要有过期策略因为模型本身可能会更新。9.3 监控与告警生产环境里你需要知道 Harness 的运行状况每天跑多少任务、成功率多少、平均步数多少、哪些工具失败率最高。这些指标不需要很复杂几个计数器就能搞定。关键是持续收集定期看。我见过太多项目上线后就不管了直到用户投诉才发现某个工具已经连续失败一周了。9.4 灰度与回滚Agent 的行为受 prompt、模型版本、工具实现多个因素影响。任何一处改动都可能让效果变差。所以改动要灰度先在小流量上验证没问题再全量。同时要保留回滚能力。prompt 和配置都要版本化出问题能快速切回上一个版本。10. 关于学习路径的一点个人建议如果你刚开始接触 Harness 和 Agent 开发我的建议是不要一上来就追求大而全。先把最小闭环跑通——一个模型、一个工具、一个简单的执行循环。跑通之后再逐步加工具、加记忆、加防护。我见过太多人一开始就照着复杂的框架文档搭搭了两周还没跑起来然后就放弃了。其实核心逻辑就那么点东西把它吃透剩下的都是工程细节。另外多动手改。看十篇教程不如自己改一遍代码。把执行循环里的某个参数改一改看看行为有什么变化把工具描述改一改看看模型选择有什么不同。这种体感是看文档看不来的。最后保持对模型行为的观察。模型不是确定性的程序同样的输入可能给出不同的输出。你要通过大量实际运行积累对它的“直觉”。这种直觉才是你后面做各种工程决策的基础。
OpenHarness 实战：从零构建大模型 Agent 运行时控制层
1. 从“模型很强但不好用”说起Harness 到底在解决什么问题大模型本身是个“裸脑”。你给它一段 prompt它回你一段文本仅此而已。但真实业务里我们要的是它能读文件、能调接口、能记住上下文、能在多轮里保持状态、能在出错时重试、能把一个复杂任务拆成若干步跑完。这些能力模型自己给不了得靠外面套一层“壳”来补齐。这层壳就是 Harness。很多人第一次听到 Harness 这个词会懵因为它不像 Agent 那么直观。Agent 是“智能体”一听就知道是干活的主体Harness 直译是“马具、挽具”听起来像是给马套的装备。这个比喻其实非常精准——模型是那匹力气很大的马Harness 就是把它套住、引导它往正确方向跑的那套挽具。没有挽具马能跑但你控制不了它往哪跑、跑多快、什么时候停。所以 Harness 的本质是围绕大模型构建的一整套运行时控制层它负责把模型的原始输出转化为可执行的动作把外部世界的反馈重新喂回模型并在整个循环里管理状态、约束行为、处理异常。OpenHarness 就是这样一个框架。它不是一个模型也不是一个单纯的 SDK而是一套帮你把“模型能力”变成“可用系统”的工程骨架。你可以在它上面挂不同的模型本地跑的、API 调的都行定义不同的工具配置不同的记忆策略然后它负责把这一整套东西串起来跑通。这篇文章面向的是想真正把大模型用起来的开发者。不管你是刚接触 Agent 开发的新手还是已经用其他框架搭过一些 demo、但总觉得“跑起来容易、跑稳难”的老手下面这些内容应该都能帮你少走一些弯路。我会从 Harness 和 Agent 的区别讲起然后一步步拆 OpenHarness 的核心结构、工具接入、记忆管理、执行循环最后聊几个实际踩过的坑。提示本文所有代码示例以 Python 为主假设你已经具备基本的 Python 编程能力并且本地或远程有一个可用的大模型接口。如果你还没配好模型环境先把这一步搞定再往下看否则后面跑不起来会很挫败。2. Harness 和 Agent 到底差在哪一个容易被混淆的核心概念2.1 从“谁在做决定”这个角度切进去很多人把 Harness 和 Agent 当成同义词用这在口语里问题不大但在工程上会带来严重的认知混乱。我见过不少项目代码里 Agent 类既负责调模型、又负责管状态、又负责执行工具、还负责重试逻辑一个文件两千行改一处崩三处。这就是没把 Harness 和 Agent 的职责分清楚。用一个类比来说Agent 是“司机”Harness 是“车”。司机决定去哪、怎么走车提供方向盘、油门、刹车、仪表盘并且保证司机踩油门时车真的会动。司机可以换车也可以换两者是解耦的。具体到代码层面Agent 通常包含的是决策逻辑——给定当前状态下一步该调哪个工具、该生成什么回复。而 Harness 包含的是执行逻辑——怎么把 Agent 的决策变成实际的动作怎么把动作的结果收集回来怎么在出错时保护整个流程不崩。2.2 一张表把职责边界说清楚维度AgentHarness核心职责决策下一步做什么执行把决策落地并管理运行时状态管理通常不关心负责维护对话历史、工具调用记录、中间状态工具执行只输出“我要调某个工具”实际去调处理超时、异常、重试模型交互构造 prompt、解析输出管理模型连接、token 预算、并发控制生命周期一次决策整个任务从开始到结束的完整循环可替换性可以换不同的 Agent 策略可以换不同的模型后端这张表不是学术定义是我自己在拆项目时总结出来的实用边界。你拿它去对照任何一个 Agent 框架基本都能对上。2.3 为什么 OpenHarness 要把这两者分开分开的最大好处是可测试性。Agent 的决策逻辑可以单独测——给它一个状态看它输出什么动作不需要真的调模型、真的执行工具。Harness 的执行逻辑也可以单独测——给它一个动作序列看它能不能正确执行并收集结果不需要关心这个动作是怎么决策出来的。第二个好处是可替换性。你今天用 A 模型做决策明天想换 B 模型只需要换 Agent 层Harness 层不用动。反过来你今天用同步执行明天想改成异步并发只需要换 Harness 层Agent 层不用动。第三个好处是错误隔离。Agent 决策错了最多是选错工具Harness 可以在执行前做校验拦截。Harness 执行挂了Agent 可以收到错误信息后重新决策而不是整个流程直接崩掉。注意如果你之前写的 Agent 代码里混杂了大量执行逻辑建议先别急着迁移到 OpenHarness而是先把职责边界理清楚。带着一团乱麻迁移只会把乱麻搬到新框架里。3. OpenHarness 的骨架拆解四个核心模块与它们的数据流3.1 模块一Model Adapter——把不同模型的差异抹平OpenHarness 的第一个核心模块是模型适配层。它的作用很简单不管你后面接的是哪个模型上层拿到的接口都是一样的。为什么需要这一层因为不同模型的 API 差异比想象中大。有的用messages数组有的用prompt字符串有的支持 function calling有的只支持纯文本有的返回finish_reason有的返回stop_reason。如果 Agent 层直接对接这些差异换模型就是一场灾难。Model Adapter 通常需要实现这几个方法class ModelAdapter: def chat(self, messages, toolsNone, **kwargs): 发送对话请求返回标准化响应 raise NotImplementedError def count_tokens(self, text): 估算 token 数量用于预算控制 raise NotImplementedError def supports_tool_calling(self): 该模型是否原生支持工具调用 raise NotImplementedErrorchat方法的返回值需要标准化成一个统一结构至少包含模型生成的文本内容、是否请求调用工具、请求调用哪些工具及参数、本次消耗的 token 数。这样上层就不用关心底层是哪个模型了。count_tokens这个方法看起来不起眼但在实际项目里非常关键。你需要它来做上下文窗口管理——当对话历史太长时决定截断哪些、保留哪些。不同模型的 tokenizer 不一样粗略估算可以用字符数除以 3 到 4但精确控制还是得用对应模型的 tokenizer。3.2 模块二Tool Registry——工具的注册、发现与调用第二个核心模块是工具注册表。Agent 要干活就得有工具。读文件是工具查数据库是工具调外部 API 也是工具。Tool Registry 负责管理这些工具的元信息和调用入口。一个工具的定义通常包含三部分名称、描述、参数 schema。名称是给模型看的标识符描述是给模型判断“什么时候该用这个工具”的依据参数 schema 是给模型生成调用参数时的约束。from pydantic import BaseModel class ReadFileParams(BaseModel): path: str encoding: str utf-8 def read_file(path: str, encoding: str utf-8) - str: with open(path, r, encodingencoding) as f: return f.read() registry.register( nameread_file, description读取指定路径的文本文件内容, params_modelReadFileParams, funcread_file )这里有个经验工具描述的质量直接决定 Agent 的决策质量。我见过太多项目工具描述写得含糊其辞比如“处理数据”这种模型根本不知道什么时候该调。好的描述应该说清楚这个工具做什么、什么时候用、输入是什么、输出是什么、有什么限制。参数 schema 用 Pydantic 这类库来定义是个好选择因为它能自动生成 JSON Schema 给模型看同时还能在调用前做参数校验。模型生成的参数经常有类型错误或者缺字段有了校验层就能在执行前拦住而不是执行到一半报错。3.3 模块三Memory Store——短期记忆与长期记忆的分层第三个模块是记忆管理。大模型本身是无状态的每次调用都是全新的。要让它在多轮对话里保持连贯就得把历史信息重新喂给它。但上下文窗口有限不能无限往里塞所以需要分层管理。短期记忆就是当前任务的对话历史包括用户输入、模型输出、工具调用记录。这部分通常直接放在上下文里但需要控制长度。长期记忆是跨任务、跨会话的信息比如用户偏好、历史结论、知识片段这部分需要存储和检索。OpenHarness 的记忆层通常提供这几个能力追加把新的对话轮次加入历史截断当历史太长时按策略丢弃旧内容摘要把旧内容压缩成简短摘要保留关键信息检索从长期存储里找出与当前任务相关的片段截断策略有很多种最简单的就是保留最近 N 轮。但这样会丢失早期的重要信息。更好的做法是“保留最近 N 轮 对更早内容做摘要”。摘要可以用模型来做也可以用规则来做看你对成本和质量的权衡。提示记忆管理是 Agent 项目里最容易出问题的地方。我建议在项目早期就把记忆策略定清楚不要等到上下文爆了才临时加截断逻辑那时候往往已经积累了一堆难以复现的 bug。3.4 模块四Execution Loop——整个系统的心脏第四个模块是执行循环这是 Harness 的心脏。它的逻辑用伪代码表示大概是def run(task, max_steps20): state init_state(task) for step in range(max_steps): response agent.decide(state) if response.is_final: return response.content for tool_call in response.tool_calls: result execute_tool(tool_call) state.append(tool_call, result) return 达到最大步数限制任务未完成看起来简单但魔鬼在细节里。execute_tool需要处理超时、异常、重试agent.decide需要处理模型返回格式错误state.append需要处理上下文长度max_steps需要防止无限循环。我实际项目里遇到过几种典型的循环问题模型反复调同一个工具、参数一模一样陷入死循环模型在两个工具之间来回跳始终不给出最终答案模型生成的工具参数格式错误执行失败后又生成同样的错误参数。这些都需要在 Execution Loop 里加防护。常见的防护手段包括检测重复调用并强制中断、设置单步超时、设置总步数上限、对连续失败的工具调用做降级处理。这些不是可选项是必选项。4. 从零搭一个最小可跑的 OpenHarness 实例4.1 环境准备与依赖选择先把环境搭起来。Python 3.10 以上是基本要求因为很多现代 Agent 框架用到了类型注解的新特性。依赖方面核心的几个是模型 SDK看你用哪家、Pydantic参数校验、以及 OpenHarness 本身。pip install openharness pydantic如果你用的是本地模型还需要装对应的推理引擎。这里不展开因为不同引擎差异太大。假设你已经有一个能通过 HTTP 调用的模型接口不管是本地的还是远程的。目录结构建议这样组织project/ agents/ __init__.py my_agent.py tools/ __init__.py file_tools.py api_tools.py config/ settings.py main.py把 Agent、工具、配置分开后面扩展的时候不会乱。我见过把所有东西塞一个文件的写法demo 阶段没问题一旦工具有十几个、Agent 有多个策略就没法维护了。4.2 定义第一个 Agent决策逻辑怎么写Agent 的核心是一个decide方法输入当前状态输出下一步动作。最简单的实现就是把状态转成 prompt调模型解析输出。class SimpleAgent: def __init__(self, model_adapter, tool_registry, system_prompt): self.model model_adapter self.tools tool_registry self.system_prompt system_prompt def decide(self, state): messages [ {role: system, content: self.system_prompt}, *state.to_messages() ] response self.model.chat( messages, toolsself.tools.to_schema() ) return self.parse_response(response)system_prompt是 Agent 的“人格设定”它决定了 Agent 的行为风格。写 system prompt 有几个经验明确角色、明确可用工具、明确输出格式、明确边界。不要写得太长模型记不住也不要写得太短模型会乱来。parse_response负责把模型输出解析成结构化动作。如果模型原生支持 function calling这一步很简单直接读结构化字段就行。如果不支持就得从文本里解析这时候需要约定好输出格式比如要求模型输出 JSON。4.3 注册一组实用工具文件读写与 HTTP 请求工具不在多在于精。新手最容易犯的错是一次性注册几十个工具结果模型选择困难决策质量反而下降。建议从最基础的几个开始读文件、写文件、发 HTTP 请求、执行计算。def write_file(path: str, content: str) - str: with open(path, w, encodingutf-8) as f: f.write(content) return f已写入 {len(content)} 字符到 {path} def http_get(url: str, timeout: int 10) - str: import requests resp requests.get(url, timeouttimeout) return resp.text[:2000] # 截断防止上下文爆炸注意http_get里的截断。外部接口返回的内容可能非常长直接塞进上下文会瞬间占满窗口。截断是一种保护但也要在工具描述里说明“返回内容可能被截断”让模型知道这个限制。工具注册的时候参数类型要写清楚。timeout这种参数给个默认值模型不传也能跑。path这种必填参数要在 schema 里标成 required让模型知道必须提供。4.4 跑通第一个任务让 Agent 读文件并总结现在把上面这些串起来跑一个最简单的任务让 Agent 读一个文件然后总结内容。def main(): model YourModelAdapter(...) registry ToolRegistry() registry.register(read_file, 读取文本文件, ReadFileParams, read_file) registry.register(write_file, 写入文本文件, WriteFileParams, write_file) agent SimpleAgent( model_adaptermodel, tool_registryregistry, system_prompt你是一个文件处理助手。用户让你读文件时调用 read_file 工具。 ) harness Harness(agentagent, max_steps10) result harness.run(读取 notes.txt 并总结成三句话) print(result)跑通之后你会看到 Agent 先调read_file拿到内容然后生成总结。这个过程可能成功也可能失败。失败的原因通常有几类模型没按格式输出工具调用、工具执行报错、模型拿到结果后不给出最终答案。这些都需要在 Harness 层处理。提示第一次跑通之后不要急着加功能。先把这个最小实例跑稳多试几个不同的任务观察 Agent 的行为模式。你对它的“脾气”了解得越深后面加复杂功能时越不容易翻车。5. 工具调用的稳定性超时、重试与参数校验的实战处理5.1 工具执行失败的三种典型场景工具执行失败是常态不是异常。我统计过自己项目里的失败日志大概分三类第一类是超时。调外部 API对方响应慢或者网络抖动请求卡住。这类失败最危险因为它会阻塞整个执行循环。如果不设超时一个卡住的请求能让整个任务挂死。第二类是参数错误。模型生成的参数不符合工具要求比如该传整数传了字符串该传路径传了个描述。这类失败在执行前就能拦住前提是你做了参数校验。第三类是业务异常。工具本身执行了但返回了错误结果。比如读文件时文件不存在调 API 时返回 404。这类失败需要把错误信息回传给模型让它决定下一步怎么办。5.2 超时控制每个工具都要有兜底超时控制的原则是任何可能阻塞的操作都必须有超时。文件读写一般不会阻塞太久但网络请求一定会。给每个工具的执行包一层超时保护import signal class TimeoutError(Exception): pass def with_timeout(func, timeout_sec): def handler(signum, frame): raise TimeoutError(f工具执行超过 {timeout_sec} 秒) signal.signal(signal.SIGALRM, handler) signal.alarm(timeout_sec) try: return func() finally: signal.alarm(0)这是 Unix 系统下的做法Windows 下需要用线程或其他机制。核心思路是一样的给执行设一个上限超了就中断把超时信息作为工具结果返回给模型。模型收到超时信息后通常会尝试换一种方式或者告诉你任务无法完成。这比整个流程卡死要好得多。5.3 重试策略不是所有失败都值得重试重试要有选择性。网络抖动导致的失败重试大概率能成功参数错误导致的失败重试一百次还是失败。所以重试前要先判断失败类型。我的做法是给工具执行结果加一个retryable标记。超时和网络错误标记为可重试参数错误和业务错误标记为不可重试。Harness 在执行循环里根据这个标记决定是否重试。def execute_with_retry(tool_call, max_retries2): for attempt in range(max_retries 1): try: result execute_tool(tool_call) return result except RetryableError as e: if attempt max_retries: return ToolResult(errorstr(e), retryableFalse) continue except NonRetryableError as e: return ToolResult(errorstr(e), retryableFalse)重试之间最好加一个短暂的等待给外部系统一点恢复时间。等待时间可以固定也可以指数递增。我一般用固定的一到两秒太长了会拖慢整体速度。5.4 参数校验在模型和执行之间加一道闸参数校验是性价比最高的防护。用 Pydantic 定义参数模型模型生成的参数先过一遍校验不通过就直接返回错误不执行工具。class ReadFileParams(BaseModel): path: str Field(..., description文件路径) encoding: str Field(utf-8, description编码格式) validator(path) def path_must_exist(cls, v): if not os.path.exists(v): raise ValueError(f文件不存在: {v}) return v校验失败时把具体的错误信息返回给模型。模型看到“文件不存在”这种明确提示通常会调整参数重新尝试而不是盲目重试。这里有个细节校验信息要足够具体。只说“参数错误”模型不知道怎么改说“path 字段必须是存在的文件路径你提供的是 xxx”模型就知道该怎么调整了。6. 记忆管理的坑上下文爆炸、信息丢失与摘要策略6.1 上下文爆炸是怎么发生的上下文爆炸往往不是一次发生的而是慢慢积累的。一开始对话很短没问题。跑了几轮工具调用每次工具返回的内容都塞进历史历史越来越长。到某一轮突然就超了模型的上下文窗口请求直接失败。更隐蔽的问题是即使没超窗口上下文太长也会导致模型注意力分散决策质量下降。我实测过同样的任务上下文控制在 2000 token 以内和放到 8000 token模型的工具选择准确率能差 15% 以上。所以上下文管理不是“超了才处理”而是“从一开始就控制”。6.2 三种截断策略的取舍截断策略我试过三种各有适用场景保留最近 N 轮最简单实现成本最低。适合任务步骤少、每步信息独立的场景。缺点是早期的重要信息会丢比如用户最开始说的约束条件。保留首尾保留最开始的几轮和最近的几轮中间丢掉。适合开头有重要设定的场景。缺点是中间的关键信息可能丢。摘要压缩把旧内容用模型压缩成简短摘要。适合长任务、信息密度高的场景。缺点是要额外调模型有成本。我现在的默认策略是“保留最近 N 轮 对更早内容做摘要”。摘要只在历史超过阈值时触发不是每轮都做控制成本。6.3 摘要怎么写才不丢关键信息摘要的质量直接决定记忆管理的效果。写得不好关键信息丢了Agent 后面就会做出错误决策。我的经验是摘要 prompt 要明确要求保留这几类信息——用户的原始目标、已经确认的事实、已经排除的方案、待解决的问题。不要要求模型“总结对话”那样它会写一堆废话。要给它明确的提取维度。SUMMARY_PROMPT 请从以下对话历史中提取关键信息按以下格式输出 目标用户最初想要完成什么 已确认已经确认的事实或结论 已排除已经尝试但失败的方案 待办还需要解决的问题 对话历史 {history} 这个格式是我迭代了好几次才定下来的。早期版本让模型自由总结结果摘要里全是“用户询问了...助手回答了...”这种没有信息量的内容。改成结构化提取后摘要的可用性大幅提升。6.4 长期记忆的检索什么时候该翻旧账长期记忆是跨会话的比如用户上周让你处理过一个类似任务这周又来了。如果能检索到上次的处理方式就能少走弯路。但检索不是越多越好。检索出来的内容如果和当前任务不相关反而会干扰模型。所以检索要有相关性阈值低于阈值的不返回。实现上最简单的做法是把历史任务存成向量用当前任务去检索最相似的几条。向量化可以用模型做也可以用现成的 embedding 接口。检索出来的内容作为“参考信息”注入上下文而不是作为对话历史。注意长期记忆涉及数据存储和隐私如果你的应用面向多用户一定要做好隔离。不同用户的数据不能混在一起检索否则会出大问题。7. 执行循环的防护死循环检测、步数限制与优雅退出7.1 死循环的几种形态死循环是 Agent 项目里最让人头疼的问题。它不像报错那样直接而是安静地消耗你的 token 和时间。我遇到过几种形态重复调用模型反复调同一个工具参数一模一样。这通常是因为工具返回的结果模型没理解或者模型陷入了某种固定模式。乒乓循环模型在两个工具之间来回跳A 调完调 BB 调完调 A始终不收敛。这通常是因为两个工具的输出互相触发对方的调用条件。无效重试工具执行失败模型重试还是失败再重试。如果失败原因是参数错误重试永远不会成功。7.2 检测机制怎么判断“它在原地打转”检测重复调用最简单的方法是记录最近几次的工具调用签名工具名 参数哈希如果连续 N 次相同就判定为死循环。def is_stuck(recent_calls, threshold3): if len(recent_calls) threshold: return False signatures [call.signature() for call in recent_calls[-threshold:]] return len(set(signatures)) 1乒乓循环的检测稍微复杂一点需要看调用序列的模式。简单做法是检测最近 N 次调用是否在两个签名之间交替。检测到死循环后不要直接崩掉而是给模型一个“你似乎在重复操作请换一种方式或给出最终答案”的提示让它有机会自己跳出来。如果提示后还是重复再强制中断。7.3 步数限制给任务一个硬性边界步数限制是最后的防线。不管有没有检测到死循环总步数到了就停。这个限制要根据任务复杂度来定简单任务 5 到 10 步复杂任务 20 到 30 步。步数到了之后怎么处理我的做法是让 Agent 做一次“收尾决策”——基于当前已有的信息给出一个尽可能完整的回答并说明任务未完全完成的原因。这比直接返回“超时”要有用得多。if step max_steps: final_prompt 已达到最大步数限制。请基于当前已有信息给出你能给出的最完整回答并说明哪些部分未完成。 return agent.finalize(state, final_prompt)7.4 优雅退出让失败也有价值任务失败不可怕可怕的是失败后什么信息都没有。好的 Harness 应该在退出时输出足够的信息让你知道发生了什么、卡在哪里、下次怎么改进。我通常会在退出时输出这几项总步数、每步的工具调用和结果摘要、最终状态、失败原因分类。这些信息对于调试和优化至关重要。class ExecutionTrace: def __init__(self): self.steps [] self.failure_reason None def summary(self): return { total_steps: len(self.steps), tools_used: [s.tool_name for s in self.steps], failure_reason: self.failure_reason, last_state: self.steps[-1] if self.steps else None }这个 trace 在开发阶段直接打印在生产环境可以存日志。有了它排查问题就不用靠猜了。8. 几个我踩过的坑和对应的解法8.1 模型不按格式输出工具调用这是新手最常遇到的问题。你要求模型输出 JSON它给你输出一段带解释的文字JSON 藏在里面。解析失败整个流程就断了。解法有两个方向。一是用原生支持 function calling 的模型从根上避免这个问题。二是如果只能用纯文本模型解析要做得足够宽容——先尝试直接解析失败后用正则提取 JSON 片段再失败就返回错误让模型重试。我现在的做法是解析失败时把“你的输出格式不正确请只输出 JSON不要有其他内容”作为工具结果返回让模型重新生成。通常一两次就能纠正。8.2 工具返回内容太长撑爆上下文外部 API 返回一大段 HTML或者读了一个大文件直接塞进上下文下一轮请求就超了。解法是在工具层面做截断同时在工具描述里说明“返回内容可能被截断”。截断长度根据你的上下文预算来定我一般单个工具返回不超过 2000 字符。如果确实需要处理长内容不要让工具直接返回全文而是让工具返回“文件已读取共 N 字符前 2000 字符如下...”然后提供一个read_more工具让模型按需读取后续部分。8.3 多工具场景下模型选择困难工具一多模型就懵了。我试过注册 20 多个工具结果模型经常选错或者选一个明显不合适的工具。解法是控制工具数量同时优化工具描述。如果确实需要很多工具可以做工具分组——先让模型选组再在组内选具体工具。这样每次决策的候选集就小了。另一个技巧是在 system prompt 里给出工具选择的指引比如“处理文件相关任务时优先使用 file 组工具”。这能显著提升选择准确率。8.4 异步执行带来的状态竞争当 Harness 支持并发执行多个工具时状态管理会变得复杂。两个工具同时修改同一个状态字段结果不可预测。解法是给状态加锁或者设计成不可变状态——每次修改生成新状态而不是原地修改。后者更符合函数式编程的思路也更容易调试。如果并发不是必须的我建议先用同步执行。同步执行慢一点但状态管理简单得多。等同步版本跑稳了再考虑哪些环节可以并发。9. 从能跑到好用性能优化与生产化的几个方向9.1 减少不必要的模型调用每次模型调用都有成本和延迟。有些调用是可以省掉的。比如工具执行成功后如果结果是确定性的不需要再让模型判断下一步可以直接按预设流程走。我一般会把任务分成“需要模型决策”和“不需要模型决策”两类步骤。后者用代码直接串起来前者才走 Agent 循环。这样能省下不少调用。9.2 缓存重复的模型请求同样的 prompt 和参数如果之前调过结果可以直接缓存。这在开发调试阶段特别有用能省大量时间和成本。缓存 key 可以用 prompt 的哈希加上模型标识。注意缓存要有过期策略因为模型本身可能会更新。9.3 监控与告警生产环境里你需要知道 Harness 的运行状况每天跑多少任务、成功率多少、平均步数多少、哪些工具失败率最高。这些指标不需要很复杂几个计数器就能搞定。关键是持续收集定期看。我见过太多项目上线后就不管了直到用户投诉才发现某个工具已经连续失败一周了。9.4 灰度与回滚Agent 的行为受 prompt、模型版本、工具实现多个因素影响。任何一处改动都可能让效果变差。所以改动要灰度先在小流量上验证没问题再全量。同时要保留回滚能力。prompt 和配置都要版本化出问题能快速切回上一个版本。10. 关于学习路径的一点个人建议如果你刚开始接触 Harness 和 Agent 开发我的建议是不要一上来就追求大而全。先把最小闭环跑通——一个模型、一个工具、一个简单的执行循环。跑通之后再逐步加工具、加记忆、加防护。我见过太多人一开始就照着复杂的框架文档搭搭了两周还没跑起来然后就放弃了。其实核心逻辑就那么点东西把它吃透剩下的都是工程细节。另外多动手改。看十篇教程不如自己改一遍代码。把执行循环里的某个参数改一改看看行为有什么变化把工具描述改一改看看模型选择有什么不同。这种体感是看文档看不来的。最后保持对模型行为的观察。模型不是确定性的程序同样的输入可能给出不同的输出。你要通过大量实际运行积累对它的“直觉”。这种直觉才是你后面做各种工程决策的基础。
