AI Agent核心架构：Harness七个子系统与工程实践解析

1. 先分清边界Agent、Model、Harness 三者到底是什么关系1.1 大多数人理解的 Agent 概念是错的先说个我观察了很久的现象。现在但凡聊 AI Agent十个群里八个会把能调大模型 API、能流式输出当成 Agent 已经做完了。这其实是 2023 年那波 ChatBot 浪潮留下的后遗症大家习惯了模型输出即产品的玩法只要把用户问题丢过去返回一段漂亮的回答就觉得任务闭环了。可一旦把场景换成帮我在服务器上查日志把报表发到钉钉群根据监控数据写一个故障复盘光是触发模型吐字根本交不了差。真正的 AI Agent 起码要做到三件事接住一个目标、规划拆解步骤、在实际环境里执行动作并观察结果然后根据结果决定下一步。这个循环里模型只是扮演决策脑它负责在每一个环节输出意图和文本但谁来把意图翻译成可执行的操作谁来保存它执行到哪一步了谁来调用工具、校验权限、记录全过程这几件事统统不属于模型本身而是属于 Agent 外围那一整套工程设施。业界这两年给这套设施起了个名字就叫 Harness。1.2 Harness 这个词从测试领域借来意思却更重懂后端的老哥听到 Harness 应该不陌生软件测试里 Test Harness 指的是驱动被测代码、收集测试结果的脚手架。Agent Harness 借用了同一层意思但范围大得多它不光要驱动模型还要承载工具调用、上下文管理、记忆存取、安全守卫和可观测性。我打过一个比方模型是大脑Harness 是骨架、肌肉、神经系统和仪表盘的集合。大脑有能力思考我想打开文件编辑器可它没有手去点鼠标也没有眼睛确认窗口弹出来没有。Harness 就是那双手和那套感官反馈回路。它把模型的意图变成真实的系统调用又把系统调用的结果喂回模型让大脑能在下一步决策前看到刚才那步到底成没成、结果长什么样。这个边界划清楚之后才谈得上七个子系统。因为每一个子系统都对应着让大脑安全、稳定、可控地干活的必要条件少了哪一个Agent 都会以一种很隐蔽的方式半瘫。2. 七个子系统全景图谁负责什么、缺了谁会怎样我在自己项目的迭代过程里反复验证过一套分层逻辑一个能真正交付任务的 Harness无论如何拆分最后都会收敛到下面这七个核心子系统。你不需要第一版就把每个系统做到生产级但架构上必须预留它们的位置否则后面补课的成本会高到你怀疑人生。子系统核心职责缺失时的典型症状编排总线管理 Agent 主循环、拆解任务、决策下一步模型只输出文本不产生实际动作状态管理保存会话变量、执行进度、步骤结果多轮任务永远在重复第一步记忆子系统短期上下文 长期知识检索跨会话重复提问知识遗忘工具网关注册、发现、调用外部工具的能力Agent 有想法但动不了手可观测性日志、追踪、指标采集看透每一步出错了只能抓瞎无法定位安全守卫权限校验、成本控制、敏感操作熔断越权操作或失控循环烧钱插件/生态层动态接入外部技能、适配不同模型后端想扩展能力时必须改主代码2.1 编排总线Agent 的主循环发动机编排总线是整个 Harness 最核心的部分它决定了一个 Agent 到底是只会接话的聊天轮子还是真正推进任务的引擎。在主循环里模型每一次吐出的内容都要经过解析意图、匹配工具、执行动作、观察结果、再次决策这个闭环而把这些环节串起来的调度器就是编排总线。我做的最初版调度器非常朴拙一个while循环加一次模型调用跑完步骤判断任务是否终结。后来才意识到编排总线的难点根本不在循环本身而在分支策略同一个意图在任务初期、中期、后期可能需要完全不同的处理方式。比如用户让 Agent 整理周报它可能得先查日历事件、再拉项目进度、最后组装文本如果第一步查日历失败了是重试还是换用别的时间源这些策略都沉淀在编排层里。社区里那些什么Agent.execute一调到底的框架本质上就是把编排逻辑写死在了最表层看似省事但稍微一换业务场景就僵住了。2.2 状态管理让 Agent 记住自己刚才干了什么状态管理被很多人忽视却是我在实际项目中吃过最多暗亏的一环。原因很简单大模型本身没有真正意义上的持久记忆它的输入输出都受限于上下文窗口。你让它完成一个读取日志 - 统计错误码 - 生成报表的三步任务每一步的中间结果放哪儿放模型上下文里开几个长任务上下文就爆了放内存变量里进程重启就丢了放文件里谁来定义文件格式好的状态管理会在 Harness 内部维护一份结构化状态包括任务级变量、步骤执行记录、工具调用返回值、错误堆栈。它相当于给 Agent 发了一张便签纸让模型在每一个决策点都能重新读到我目前在哪、已经完成了什么、剩下什么。实测下来状态管理写得好不好直接决定 Agent 能否处理超过 3 步的复合任务。很多号称一起工作写代码就犯迷糊的 Agent 产品根因往往不在模型能力而在状态没有真正接好。2.3 记忆子系统跨会话不忘事的根本如果状态管理解决的是当前任务进行到哪记忆子系统解决的则是以前遇到过什么、学过什么。最常见的做法是分两层工作记忆放当前会话的关键信息长期记忆用向量数据库把历史知识、用户偏好、项目背景存起来在需要时通过相似度检索召回。值得强调的是记忆子系统非常考验写策略。不是每个历史片段都值得存也不是每次对话都要先查一遍库。我踩过的一个典型坑是把全部聊天记录都灌进向量库结果每次查询召回一堆过时信息反而干扰模型判断。后来我加了写前过滤和写入摘要的环节只用经过提炼的事实性结论入库召回准确率立刻上了两个台阶。2.4 工具网关统一所有动手能力的入口工具网关可以理解成 Agent 的功能插线板。任何外部能力——查数据库、发 HTTP 请求、操作文件、调用某个内部 API——都要通过网关注册成一个带描述的方法模型才知道现在有哪些工具可以用、各自需要什么参数。为什么要加这一层而不是让模型直接写代码调 API因为安全和抽象都卡在这一层。网关可以做参数校验、超时控制、调用频率限制、结果裁剪甚至返回错误信息给模型进行二次修正。没有网关的 Agent工具调用就像裸奔模型生成什么参数它就传什么参数遇到 502 错误也不知道怎么转译成下一步决策整个循环很容易卡死在调用失败 - 重试 - 再失败的死胡同里。我见过不少项目把网关定义为简单的tools: List[Tool]数据类这方向不错但记得给每个工具补上退避重试策略和错误信息格式化否则生产环境会很难看。2.5 可观测性没有日志的 Agent 等于在迷雾里开车我始终认为可观测性不是可选项而是让 Agent 真正敢上业务线的门票。一个成熟的 Harness至少要记录三类信息决策链路模型每次输出什么意图、工具链路哪个工具被调用、参数是什么、耗时多久、结果如何、成本链路每一步消耗了多少 token 和费用。有一次我在排查 Agent 为什么反复给同一个工单重复发邮件翻日志才发现是状态管理里漏更新了邮件已发送的标志位导致循环每次都以为还没发出去。这种问题如果没有完整日志单靠猜能把人逼疯。所以搭建 Harness 的第一天就应该把结构化日志挂上最好能自动输出 JSON 格式的 trace后面无论是调试还是做数据复盘都好办得多。2.6 安全守卫权限、成本和失控循环的刹车把安全守卫放在第 6 位不代表它不重要恰恰是因为它太容易被忽略才值得专门拿出来说。Agent 一旦具备操作真实系统的能力权限模型的复杂度会直线上升哪些指令是只读的哪些操作需要二次确认多轮循环里每次工具调用的成本上限是多少对用户敏感数据的访问范围如何界定我的经验是先立三条硬规则默认只读、高危操作必须人工确认、单次任务设置成本熔断阈值。就像给自动驾驶配刹车平时没人管它可一旦模型在某个步骤陷入循环比如对着同一个接口疯狂重试熔断机制能直接把整个任务停掉避免烧光预算。这条规则在把 Agent 接到支付、发文、转账这类高影响系统前更要优先级拉满。2.7 插件/生态层把扩展能力从改主代码变成插即用最后是插件/生态层它的价值在于降低扩展成本。Harness 的核心主循环、状态管理和安全守卫都应该保持稳定而新增能力时最好是通过插件协议往工具网关里挂新的技能包。社区里那些harness failed to load plugins的报错绝大多数都出在这一层。插件包的加载顺序、入口声明、宿主版本匹配每一项都可能让一次看起来人畜无害的插件安装翻车。我后面会专门讲这一块的排查链路这里先记住一个原则插件协议要一开始就定义好包括插件描述文件格式、入口函数签名、依赖声明、版本兼容规则不然插件多了以后维护成本会爆炸。3. 一条真实任务在 Harness 里的完整接力从帮我分析服务器日志说起前面讲了七个子系统是静态的解剖这一节用一个真实任务把它们跑起来看看动态过程长什么样。假设你给自己的 Harness 配了一个运维助手 Agent用户对它说帮我分析一下最近一小时 Nginx 的错误日志总结主要异常并生成一份处理建议。3.1 第一步意图解析并拆解计划编排总线先拿到用户请求通过一次模型调用把任务拆成一个大致的计划读取日志文件、过滤最近一小时记录、归类异常类型、生成建议。这个计划不一定准确没关系编排层只要拿到一个最小可执行的下一步就够了。通常我会要求模型输出一个结构化的 JSON包含steps数组和当前执行序号方便状态管理保存进度。3.2 第二步状态检查与记忆召回在真正执行第一步读取日志之前状态管理会先检查当前任务是否已经做过这一步避免重复执行。与此同时记忆子系统会快速检索看用户是不是之前已经提到过Nginx 日志在 /var/log/nginx/error.log主要关注 5xx 错误如果是这些历史偏好会被拼进上下文让模型在后续决策里更贴合实际情况。3.3 第三步工具网关调用 Shell 读取日志编排总线把读取日志这个意图转成交给工具网关执行。网关在注册表里找到了一个名为read_log_file的工具参数是文件路径和时间范围。它做三轮检查第一参数里的路径是否在白名单内防止 Agent 读取系统敏感文件第二这个操作是否只读确认不需要人工审批第三调用前记录一条日志 trace。然后才真正执行命令把日志尾部的内容截取出来同时裁剪到适合模型上下文的大小返回给编排层。3.4 第四步模型分析结果并输出中间结论这时候编排放上一次读取日志的返回内容重新发给模型让它总结主要的异常类型和频次。注意这一步本身没有新的工具调用模型只是在消化上一步的结果。Harness 会把模型吐出的这段中间结论写进状态管理的任务变量里防止下一步丢失。3.5 第五步安全守卫检查再决定是否发消息任务进行到生成处理建议后编排层可能会调用一个send_report工具把建议发到团队的某个群。安全守卫在这里会拦一道因为send_report属于对外发送类操作一旦触发不可撤回它会要求用户确认。于是 Harness 暂停主循环把待发送的文本展示给用户得到确认后才继续。整个过程可观测性都在记录每一步的决策理由都留下了可追溯的日志。这个接力的意义在于它不是模型一次生成就交付的幻觉式完成而是每一步都落地到真实环境真实环境的结果又反过来驱动下一步的模型决策。七个子系统在这里各司其职编排总线推流程状态管理记进度记忆子系统补背景工具网关动手安全守卫踩刹车可观测性留证据。缺一个环节任务都会以不同姿势崩掉。4. 自己从 0 搭一个最小可用 Harness思路和关键代码如果你已经在用现成的 Agent 框架比如 LangChain、LlamaIndex甚至社区里比较火的 DeepSeek Harness 一类的开源项目这一节可以当作底层原理来读。但如果你想彻底掌控自己的 Agent我强烈建议哪怕只写一个 300 行的骨架也要把七个子系统在代码里各留一个接口位置。4.1 主循环骨架可以非常短但不能没有状态我先给你看一个极简的编排总线实现。它不处理复杂分支但足够把循环决策这件事跑起来。import json from dataclasses import dataclass, field dataclass class ToolResult: ok: bool content: str meta: dict field(default_factorydict) class Harness: def __init__(self, model, tool_gateway, memory, state, guard): self.model model self.tools tool_gateway self.memory memory self.state state self.guard guard def run(self, user_request: str) - str: # 初始化任务状态 self.state.reset() self.state.set(user_request, user_request) history self.memory.recall(user_request) while True: # 1. 组装上下文 context self.state.snapshot() history # 2. 让模型输出下一步决策 decision self.model.decide(context) if decision.get(action) finish: return decision.get(answer) # 3. 安全守卫检查允许执行 if not self.guard.allow(decision): return 操作被安全策略拦截 # 4. 调用工具网关执行 result: ToolResult self.tools.execute( decision[tool_name], decision[params], ) # 5. 状态管理记录结果供下一步决策使用 self.state.step(decision, result) # 6. 可观测性输出一条结构化日志 self.emit_trace(decision, result)这段代码的逻辑非常直白模型负责决定下一步做什么Harness 负责保障这个决定能被执行、被执行后能产生反馈。你用任何大模型 API 都能填进self.model.decide里关键是要诱导它输出结构化决策而不是自由散文。实践中我会用一个 System Prompt强制模型用 JSON 格式回答包含action、tool_name、params和reason四个字段。4.2 工具网关和插件协议把能用变成可扩展工具网关上我建议用一个大字典做注册表每个工具只需要提供名字、描述、参数 schema 和执行函数。这里有个容易踩坑的地方参数 schema 一定要写得非常详细因为模型是靠这个描述来生成参数的写得太模糊它就会凭空发明参数名。class ToolGateway: def __init__(self): self._tools {} def register(self, tool_name: str, description: str, params_schema: dict, handler): self._tools[tool_name] { description: description, params_schema: params_schema, handler: handler, } def execute(self, tool_name: str, params: dict) - ToolResult: tool self._tools.get(tool_name) if not tool: return ToolResult(False, f未注册的工具: {tool_name}) # 参数校验 try: validated self._validate(params, tool[params_schema]) content tool[handler](**validated) return ToolResult(True, content) except Exception as e: return ToolResult(False, f工具调用异常: {e})至于插件/生态层本质上就是给register提供一种外部装载机制。一个插件包通过描述文件声明我是谁、我提供哪些工具、我的入口是谁Harness 在启动时扫描插件目录按声明把工具挂进网关注册表。这样新增能力就不需要改 Harness 主代码了。4.3 为什么建议你自己先搭一遍骨架我知道很多人会觉得有现成框架不用自己造轮子干嘛。但这轮子特殊它决定了你对整套体系的理解深度。自己写完这个 300 行骨架后你再去看 DeepSeek Harness 这类项目的源码一眼就能认出它的子模块边界在哪里配置项是干什么用的出问题了该去哪个目录翻日志。这种知其然也知其所以然的能力在实际调优和定位问题时价值极高。反过来说如果你只是想验证某个 Agent 想法能不能跑通那直接用现成框架省时间毫无疑问是对的。两种选择没有优劣关键是你搞没搞清楚 Harness 的核心机制在自己手里还是框架手里。5. 本地部署与插件加载那些容易让人摔跤的坑随便翻一下相关热词就能看到大量用户卡在harness failed to load plugins、web boot: 2 entries did not activate、安装失败、本地部署失败这一类问题上。我自己在给项目接插件体系时也翻过车而且踩的坑非常有代表性值得拆开讲。5.1 插件入口没激活一个声明问题引发的连锁反应failed to load plugins最常见的成因就是插件描述文件里的入口声明与实际模块不一致。比如插件描述写的是主入口main:start_plugin但实际代码里函数名或模块路径稍有偏差宿主加载器在冒烟阶段找不到入口就会把整个插件包判为未激活。排查链路可以照着这个顺序走先看插件包的目录结构确认入口文件存在且路径与描述文件完全一致。检查宿主版本和插件要求的版本范围是否匹配很多加载器对 SemVer 前缀要求很严格^0.4.0和0.4.2看着挺像但加载逻辑可能只认主版本。手动在命令行尝试导入入口模块比如python -c import myplugin.main这一步能直接暴露依赖缺失或语法错误。看启动日志中跳过或did not activate之前的上下文通常会明确指出是入口缺失还是验证函数返回 false。我见过最无语的一次是插件包里带了一个本地配置文件而插件入口函数在初始化时要open(config.yaml)用的是相对路径。工作目录一换文件找不到初始化直接抛异常入口激活失败。解决方案很简单入口函数里统一用Path(__file__).parent定位配置文件而不是依赖系统当前工作目录。5.2 本地部署时最容易忽略的隔离问题再说本地部署。新手拿到 DeepSeek Harness 一类的项目最常犯的错就是直接用系统 Python 环境跑结果依赖冲突把整个环境搞坏。这类 Harness 项目依赖的包数量通常不少其中很多版本对 Python 版本敏感硬装在一起非常容易出幺蛾子。我的做法是坚持三步走先建虚拟环境再固定 Python 小版本最后按项目给的 lock 文件安装依赖。别嫌麻烦这一步能帮你省掉至少 80% 的装完启动报错类问题。如果你是在 Windows 上用 WSL 跑热词里也有不少人问 Windows 子系统的安装特别注意路径转换问题Windows 路径和 Linux 路径的\与/混用经常会让配置解析器莫名其妙地找不到文件。安装完成后我还会先跑一个冒烟测试。不用跑完整业务只需把 Harness 启动起来加载一个最简单的内置插件调用一次工具确认日志输出正常。这个过程能提前暴露大部分部署问题而不是等你写完一长串 Agent 配置后才发现底层加载就不对。5.3 配置项能看懂再改别乱抄网上的优化配置我注意到很多讨论帖里有人直接复制别人的 Harness 配置改个模型名字就开跑结果报错一头雾水。Harness 的配置项和模型本身无关的其实占了大多数比如插件目录、日志级别、状态存储路径、工具白名单、成本阈值。这些配置都跟你的运行环境强相关抄别人的配置等于抄别人的服务器路径不炸才怪。我的建议是拿到一个 Harness 项目第一件事不是改模型而是先把日志级别调到 DEBUG、把插件目录指到本地实际路径、把状态存储位置建好。确认这些本地路径都通了再动模型参数。这个顺序能保证任何报错都能快速定位而不是模型配置和环境配置混在一起排查起来头都要大两圈。6. 从单体 Harness 到 Harness Engineering下一站是编排与可观测如果把 Harness 搭到能跑通单 Agent 任务你已经领先很多人了。但真实业务里单 Agent 往往不够你迟早会遇到多个 Agent 协同Agent 与既有系统串接长期稳定运行不偏离轨道这类问题。这时候围绕 Harness 的工程化能力会比 Agent 本身的模型能力更重要。6.1 多 Agent 编排Harness 是宿主Agent 是租户所谓多 Agent 编排本质上是在一个更大的 Harness 里再套一层调度逻辑。有些任务拆给数据分析 Agent有些拆给文案 Agent它们共享同一个基础设施层工具网关、状态管理、可观测性但各自的上下文、记忆和工具权限是隔离的。我建议先别急着上复杂的多 Agent 框架。先用你的 Harness 跑通一个调度 Agent 两个执行 Agent的最小模型调度 Agent 负责拆任务、发任务、汇总结果执行 Agent 只负责干具体脏活。这一步看起来简单但能逼你把任务边界和结果协议定义清楚。很多多 Agent 项目崩掉不是因为模型不够聪明而是因为 Agent 之间没有统一的交接协议——A 的输出格式 B 解析不了整个链条就断了。6.2 可观测性体系再进阶用指标衡量 Harness 健康度当你在一个 Harness 上运行大量 Agent 任务不能再用看几条日志的方式运维了。需要沉淀一批核心指标我平时会盯这几项指标计算方式看什么任务完成率成功终结任务数 / 总任务数整体可用性工具调用成功率成功的工具调用数 / 总调用数工具网关和提示词质量上下文利用率单次决策消耗 token / 上下文窗口状态管理和记忆摘要有无失效重试次数分布每个任务中工具重试的次数是否陷入反复失败循环安全拦截次数守卫拦截的操作数权限策略有没有过度或漏拦有了这些指标你就可以像对待一个普通服务那样针对 Harness 做告警和调优。比如发现工具调用成功率低大概率是工具描述写得不够清楚或者参数 schema 和实际执行函数逻辑不符。发现重试次数异常就得去看是不是编排层的重试策略有问题抑或目标服务本身不稳定。6.3 我的一个心法让 Harness 的每一层都可以单独替换玩到后期你会发现Harness 的架构魅力在于层与层之间可替换。模型可以换工具网关可以换记忆库可以换只要接口协议不变其他层完全无感。这是不是和依赖倒置那套设计思想如出一辙对Harness 工程化到最后就是一套围绕 LLM 应用的健壮后端架构。所以我的建议是选型任何 Harness 框架时都先问三个问题工具网关能否方便注册自定义工具状态管理和记忆能否接外部存储可观测性是否能输出自定义指标三个答案都是是的框架值得深度投入如果某一个是否劝你慎重因为那意味着你将来想扩展的时候必须靠改主代码来补那可太痛苦了。从我个人的实际操作体会来说Agent 能力的上限从来不是模型本身而是它背后那个 Harness 能把模型抬多高。七个子系统听起来很多但真正动手搭一遍你会发现其中一半以上都是不复杂但必须认真的基础工程。先把编排、状态、工具网关这三件套立稳再逐步补齐记忆、安全和可观测性你的 Agent 就能从会聊天跨进能干活的阵营。最后再分享一个小技巧每次给 Harness 加新子系统时先把对应的 DEBUG 级日志和一份简单的测试用例写了后面每次升级模型或改配置你都会感谢当初这个习惯。