Agent / Harness 工具链研究：从会调用工具的 LLM，到可观测、可验证、可交付的智能体系统

TL;DR：为什么 Agent 不能只看模型？

先亮几组硬核判断。

当大模型真正接入真实工程链路——代码仓库、CI/CD流水线、生产数据库——问题立刻集中爆发：上下文被污染、工具被胡乱调用、流程陷入死循环、权限越界、甚至没有回滚机制。模型再强，也难以弥补这些系统性短板。

结论很清晰：生产级智能体的核心，根本不在“模型能不能答对”，而在于背后的Harness能否把“任务规格、上下文、工具、状态、权限、沙箱、记忆、观测、验证、评测、交付”这十一件事全部做扎实。未来一年的竞争焦点，会从模型层显著转向Harness层。

本文用 Agent = Model + Harness + Environment 这条主线，拆解八层工具链。会涉及OpenAI Agents SDK（2025-03发布，2026-04新增原生沙箱；v0.14.2，22k Star）、LangGraph、Microsoft Agent Framework、Pydantic AI、MCP（Anthropic 2024-11发布，2026年已成“实际生产力”）、A2A（Google 2025-04-09开源，50+合作伙伴）、LangSmith、Braintrust、Inspect AI。文末也会附上Ja va后端的5个低风险落地场景，以及从H0到H3的成熟度模型。

TL;DR：为什么 Agent 不能只看模型？

一句话总结：生产级Agent不是“更聪明的聊天机器人”，而是“把模型放进一个可控的执行系统里”。

模型负责语言理解、推理、生成和部分决策，这是它的强项。但模型之外，必须有一层Harness，负责上下文、工具、状态、权限、沙箱、记忆、观测、验证、评测和交付。

有个简单的公式便于理解：

Agent = Model + Harness + Environment

Model是大脑，Harness是神经系统和执行约束，Environment则是真实操作对象——代码仓库、浏览器、数据库、云平台、CI/CD、业务系统，都属于它的范畴。

如果只有模型，Agent容易闹出各种问题：调错工具、忘记上一步状态、无限循环、生成看似合理但毫无验证的结果、把错误结果写入文件或系统、拿到过大权限后误操作生产环境。所以说，今天研究Agent工具链，重点不是看“哪个框架更火”，而是看完整链路能否做到：可控、可恢复、可观测、可验证、可评测、可交付。

Agent 和 Harness 分别是什么？

普通聊天机器人主要是“输入文本，输出文本”，但Agent不止于此，它有三个关键特征。

首先是工具调用能力——能不能搜索信息、读取文件、执行命令、查询数据库、调用MCP工具、触发CI/CD。其次是任务状态管理——它得知道自己做到了哪一步，哪些成功、哪些失败，下一步该做什么。最后是围绕目标执行多步动作——不是告诉你“怎么做”，而是真地去创建分支、修改代码、跑测试、分析日志、生成报告、提交PR。

那Harness呢？它是模型之外的工程底座，不是某个具体框架，而是一组工程能力的集合：

• 任务规格：用户要做什么，成功标准是什么。
• 上下文选择：哪些文件、文档、日志、历史记录该进入上下文。
• 工具注册：Agent能调用哪些工具，参数、权限、返回值是什么。
• 状态管理：当前执行到哪一步，发生过哪些动作。
• 记忆系统：长期经验、项目约定、用户偏好、错误记录怎么保存。
• 执行环境：文件系统、Shell、浏览器、数据库、容器、沙箱。
• 权限控制：哪些操作自动执行，哪些必须人工审批。
• 失败恢复：工具失败、测试失败、网络失败、模型走偏后怎么处理。
• 验证系统：如何证明任务完成，而不是模型自己说完成。
• 观测系统：每一步模型输出、工具调用、耗时、成本、错误如何记录。
• 评测系统：如何用任务集判断Agent是否变好。
• 交付系统：如何进入CI/CD、灰度、回滚和审计。

这些就是demo Agent和工程化Agent之间的分水岭。

八层 Agent / Harness 工具链

第 1 层：模型与推理层

这一层提供基础的智能能力。典型选择包括OpenAI GPT系列、Anthropic Claude、Google Gemini、Qwen、DeepSeek、Llama、Mistral，以及本地部署的vLLM、llama.cpp、SGLang、TensorRT-LLM。

选择时要关注上下文长度、工具调用能力、结构化输出能力、代码能力、多模态能力、推理速度、成本、隐私和本地部署能力。

但说句实话，单独比较模型有点片面。同一个模型，在不同Harness下表现可能天差地别。差的Harness会让强模型乱调用工具、重复执行、污染上下文；好的Harness则能让普通模型稳定完成局部任务。

第 2 层：Agent 编排层

编排层决定了Agent如何拆解任务、流转状态、调用工具、处理多Agent协作。

典型工具包括OpenAI Agents SDK、LangGraph、CrewAI、AutoGen、Microsoft Agent Framework、Pydantic AI、Semantic Kernel、LlamaIndex Workflows、Haystack Agents。

OpenAI Agents SDK适合快速构建基于OpenAI生态的生产Agent。官方文档围绕Agent、tools、handoffs、guardrails、tracing、sessions/state等能力组织，从简单工具调用到多Agent handoff都能覆盖。

LangGraph更偏可控编排。官方文档强调durable execution、persistence、human-in-the-loop和long-running workflows。它把Agent执行过程建模为图——节点是步骤，边是流转，状态在图中传递，特别适合长任务、复杂状态、可恢复执行和人工审批。

CrewAI更强调角色化多Agent协作，Crew和Flow分别面向角色协作与流程控制。适合研究、内容生产、业务流程自动化。但有一点要提醒：多Agent并不天然更可靠，角色越多，成本和不确定性越高。

Pydantic AI的优势在于Python类型系统、schema校验和结构化输出，适合需要强类型、可测试、可维护的业务Agent。

所以选型时别问“哪个最强”，而要问“任务形态是什么”。

第 3 层：工具与协议层

Agent真正产生价值，靠的是工具。没有工具的Agent只是会说话的模型；有工具的Agent才能读文件、改代码、查数据库、发请求、控制浏览器、调用云资源。

工具层常见方式有三种：框架内置工具（搜索、文件、Shell、浏览器、代码执行）、业务自定义工具（查询订单、创建工单、读取日志、触发Jenkins、调用内部API）、以及协议化工具，最典型的就是MCP。

MCP的意义在于，它把tools、resources、prompts等能力标准化了。一个MCP Server可以暴露给多个Agent客户端使用，而不需要每个框架单独写插件。你可以把它理解为“Agent访问外部世界的USB-C接口”。

A2A解决的则是另一个问题：Agent和Agent之间怎么协作。MCP是Agent到工具，A2A是Agent到Agent。未来企业里可能不是一个超级Agent包打天下，而是代码Agent、测试Agent、安全Agent、发布Agent、运维Agent、文档Agent彼此协作。

第 4 层：上下文与记忆层

Agent的质量，很大程度上取决于上下文质量。但上下文不是越多越好。上下文窗口变大后，把文件、日志、文档都一股脑塞进去，反而会让模型注意力分散。

上下文工程要解决三个问题：给什么？什么时候给？以什么形式给？

对代码Agent来说，上下文可能包括需求、相关文件、调用链、测试、错误日志、项目规范、历史提交、接口文档。对业务Agent来说，上下文则可能是用户输入、业务规则、知识库文档、权限信息、当前工作流状态、人工审批记录。

记忆层分为短期记忆和长期记忆。短期记忆是当前任务内的状态，比如“已经修改A文件，测试失败原因是B，下一步检查C”。长期记忆是跨任务复用的信息，比如“这个项目用Ja va 17”“测试命令是mvn test”“线上发布必须先灰度”“用户偏好Markdown输出”。

记忆系统不能无脑保存，错误记忆会污染后续任务。好的记忆系统必须有来源、更新时间、适用范围、冲突处理、人工纠正、过期机制和审计。

第 5 层：执行环境与沙箱层

Agent一旦能执行工具，就具备了破坏能力。它可能删除文件、泄露密钥、调用危险命令、误操作生产环境、无限循环消耗资源，甚至被prompt injection诱导执行非预期动作。

所以执行环境必须有边界：容器沙箱、只读文件挂载、临时工作区、命令白名单、网络访问限制、环境变量隔离、密钥最小权限、工具级权限控制、人工审批断点、执行超时、token/步骤/成本预算、回滚机制——这些都是必需品。

对代码Agent，基本安全边界是：独立workspace、创建分支、不直推主干、跑测试、提交PR、不直接合并。对DevOps Agent，查看日志和生成建议可以自动，但生产发布、回滚、扩容、删除资源、修改安全策略必须审批。对数据库Agent，默认只读，写操作必须显式审批，并要求SQL预览、影响范围和回滚方案。

第 6 层：观测与追踪层

普通应用出了问题，可以看日志、指标和链路追踪。Agent出了问题，只看最终输出远远不够。Agent的错误可能发生在任何环节：意图理解、上下文检索、工具参数、工具返回理解、中间状态、记忆保存、循环、验证条件。

一次高质量trace至少应该包含：用户原始输入、系统指令版本、模型版本、提示词版本、上下文摘要、检索命中资料、每次模型输出、每次工具调用、工具参数和返回值、错误栈、状态变化、人工审批记录、耗时、token、成本、最终输出和验证结果。

LangSmith、OpenAI Agents SDK tracing、Braintrust、AgentOps、OpenTelemetry、Logfire这些工具的价值就在这里。没有trace的Agent不适合上线，因为不可复现、不可解释、不可优化。

第 7 层：评测与验证层

Agent不能靠感觉上线。普通LLM eval主要评估回答质量，Agent eval则复杂得多，因为它评估的是过程和结果：任务是否完成？工具调用是否正确？是否遵守权限？是否陷入循环？是否能从失败中恢复？是否生成可执行产物？是否通过测试？是否产生副作用？是否可审计？

典型工具包括Inspect AI、LangSmith、Braintrust、Promptfoo、DeepEval、SWE-bench、Terminal-Bench、OSWorld等。

评测Agent时，不能只看最终成功率。还要看平均步骤数、token消耗、耗时、工具调用成功率、重复调用率、失败恢复率、人工介入率、权限拦截次数、验证通过率、成本收益比。一个Agent版本是不是更好，不是看一次demo，而是看固定任务集、固定环境、固定预算下是否稳定提升。

第 8 层：CI/CD 与软件交付层

Agent最终要进入工程流程，而不是停留在notebook或demo里。软件交付链路包括需求、代码、测试、审查、安全扫描、构建、发布、灰度、监控、回滚和复盘。AI编码工具提高的是写代码速度，但软件交付的瓶颈远不止写代码。

真正AI-native的SDLC不是“AI替代程序员”，而是让Agent进入完整链路：

代码生成 -> 测试 -> 修复 -> PR -> 审查 -> 安全扫描 -> 发布 -> 灰度 -> 监控 -> 回滚 -> 复盘 -> 记忆

这也是Harness在Agent工程中的核心位置：它把Agent从“单次执行工具”推进到了“持续软件生产系统”。

典型 Agent / Harness 方案怎么选？

如果只是一次模型调用加几个工具，不需要复杂框架。OpenAI Agents SDK或轻量自研封装就够。

如果任务需要复杂状态流转、恢复、暂停、人工审批，LangGraph更合适。

如果强调角色协作、内容生产、研究分析，CrewAI或AutoGen类框架更顺手。

如果在微软生态、企业内部系统、Azure或.NET/Python混合团队里，Microsoft Agent Framework、Semantic Kernel和AutoGen系列更自然。

如果是Python工程，重视schema、结构化输出、依赖注入和测试，Pydantic AI很适合。

如果重点是工具接入和跨客户端复用，优先考虑MCP。

如果重点是Agent评测和回归，Inspect AI、LangSmith、Braintrust、Promptfoo、DeepEval这类工具要尽早纳入。

Agent 系统为什么容易失败？

Agent失败通常不是因为模型完全不会，而是因为Harness没有把任务约束清楚。

第一，目标不明确。用户说“帮我优化一下项目”，范围太宽。好的Harness要把它转成可验证任务：优化接口响应时间、修复某个测试失败、为某个模块补测试、提升某个页面Lighthouse分数。

第二，上下文污染。Agent读了太多无关文件，反而忽略关键文件。解决方式是分阶段检索：先定位模块，再读相关文件，再读调用链和测试，最后读项目规范。

第三，工具设计不良。坏工具返回一大段日志。好工具返回错误类型、错误位置、可能原因、关键日志片段、建议下一步和原始日志引用。工具接口要为Agent设计，不能简单地把人类接口暴露给模型。

第四，无权限边界。默认策略应该是：读多写少，本地多生产少，建议多自动少，低风险自动，高风险审批，可回滚自动，不可回滚审批。

第五，无验证闭环。Agent说“已修复”没有意义。必须用测试、构建、格式、接口返回、SQL只读检查、部署健康、监控恢复等结果证明。

第六，无trace。没有trace，就不知道Agent为什么失败。上线Agent必须记录输入、上下文、工具调用、状态变化、输出、验证结果、成本和错误。

一个可落地的 Agent Harness 参考架构

可以设计一个面向软件工程的Agent Harness：

用户需求 -> 任务解析器 -> 任务规格化：目标、范围、验收标准、风险等级 -> 上下文检索：代码、文档、日志、测试、历史记录 -> 计划生成器：拆分步骤 -> 权限检查：哪些可自动执行，哪些需审批 -> 执行器：读文件、改代码、跑测试、查日志、调接口 -> 状态管理：记录每一步结果 -> 失败恢复：重试、换路径、请求人工、降级 -> 验证器：测试、构建、规则、人工验收 -> 产物输出：补丁、报告、PR、部署单 -> Trace / Eval / Memory

在这个架构里，模型只负责部分节点：理解任务、生成计划、选择工具、解释工具结果、生成修改、总结报告。关键控制权在Harness手里——任务边界由它规定，工具权限由它控制，执行状态由它保存，验证标准由它执行，上线流程由它接管。

这就是工程化Agent和demo Agent的区别。

Ja va 后端场景怎么落地？

对于Ja va后端开发者来说，别一上来就追求“全自动程序员”。更现实的切入点是低风险、高重复、有验证标准的任务。

日志分析Agent：读取错误日志、链路追踪、服务名、时间范围和版本，输出异常类型、影响接口、可能原因、代码位置、排查步骤和是否需要回滚。工具以ES、Loki、SkyWalking、Jaeger、Kubernetes日志、Git提交记录为主。风险较低，适合只读自动化。

MyBatis SQL分析Agent：读取慢SQL、mapper文件、表结构、索引信息和执行计划，判断是否走索引、是否有N+1、分页问题、是否需要改SQL或加索引。默认只读，不自动改生产库。

PR Review Agent：读取代码diff、项目规范、历史bug、测试结果，输出潜在bug、安全风险、性能问题、可维护性问题和测试缺口。适合进入CI做advisory comment。

测试补全Agent：读取目标类、已有测试、覆盖率报告和业务规则，生成单元测试、边界用例、异常用例和Mock设计。可以自动生成PR，但需要人审。

发布排障Agent：读取流水线失败日志、构建环境、变更记录和依赖版本，判断失败阶段、直接原因、修复方式、是否可重试。读取和分析可以自动，但重跑、回滚、发布必须审批。

这些场景有一个共同点：输入明确、工具明确、验证明确、风险可控。

成熟度模型：不要一开始就追求全自动

H0：脚本式调用。一个prompt，一次模型调用，少量工具，无状态，无trace。适合个人临时工具。

H1：工具调用型Agent。支持function calling，有工具schema，有基本日志，能完成短任务。适合查询类助手和轻量自动化。

H2：状态编排型Agent。有状态机、持久化、人工审批、trace、验证器。适合代码修改、流程自动化和复杂任务执行。

H3：生产Harness。有完整权限系统、评测体系、观测体系，接入CI/CD，支持灰度、回滚、审计，持续从失败中学习。适合企业级Agent平台。

大多数团队不应该直接从H3开始，而应该从H1/H2做起。先选一个明确场景，把任务规格、工具、权限、验证、trace做扎实，再慢慢扩展。

最终判断：未来会从模型竞争转向 Harness 竞争

未来一年，模型仍然会变强。但Agent工程的核心差异，会越来越体现在Harness上。

谁能把上下文组织好，谁的Agent更稳。

谁能把工具设计好，谁的Agent更有用。

谁能把权限收敛好，谁的Agent更安全。

谁能把trace做好，谁的Agent更容易debug。

谁能把eval做好，谁的Agent更容易迭代。

谁能把CI/CD接好，谁的Agent更接近生产。

Agent的本质，不是“让模型自己干活”，而是“把模型放进一个可控的执行系统里”。

Harness的本质，也不是某个框架，而是模型之外的完整工程底座。它负责状态、工具、权限、上下文、记忆、观测、验证、评测、交付和治理。

真正生产级Agent的判断标准，不是看起来聪明，而是：能不能稳定执行，能不能限制权限，能不能恢复失败，能不能验证结果，能不能追踪过程，能不能持续评测，能不能进入交付链路。

一句话总结：未来的Agent工程，不是单纯训练更强的模型，而是建设更强的Harness。

参考来源

• OpenAI Agents SDK 官方文档：openai.github.io/openai-agen…
• LangGraph 官方文档：docs.langchain.com/oss/python/…
• Model Context Protocol 官方文档：modelcontextprotocol.io/
• Agent2Agent Protocol 官方文档：a2a-protocol.org/
• Inspect AI 官方文档：inspect.aisi.org.uk/