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

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

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

• 场景：把 LLM 放进真实工程链路（代码仓库、CI/CD、生产数据库）后，模型能力只是冰山一角；上下污染、工具乱用、循环消耗、权限越界、回滚缺失等问题集中爆发。
• 结论：生产级 Agent 的核心不在"模型能不能答"，而在 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 的定位；附 Java 后端 5 个低风险落地场景与 H0–H3 成熟度模型。

摘要：很多人谈 Agent 时仍然只盯模型：会不会推理、会不会规划、会不会调用工具。但真正落地时，难点往往不在"模型能不能回答"，而在"系统能不能控制它怎么执行"。Agent 需要工具、状态、权限、沙箱、记忆、观测、评测和交付链路。本文用Agent = Model + Harness + Environment作为主线，拆解 Agent / Harness 工具链的八层结构，并给出 OpenAI Agents SDK、LangGraph、CrewAI、Microsoft Agent Framework、Pydantic AI、MCP、A2A、LangSmith、Braintrust、Inspect AI、CI/CD 等工具的定位。

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

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

模型负责语言理解、推理、生成和部分决策。但模型之外，还需要一层 Harness，负责上下文、工具、状态、权限、沙箱、记忆、观测、验证、评测和交付。

可以用一个公式理解：

Agent = Model + Harness + Environment

Model 是大脑，Harness 是神经系统和执行约束，Environment 是真实操作对象，例如代码仓库、浏览器、数据库、云平台、CI/CD、业务系统。

如果只有模型，Agent 可能会：

• 调错工具。
• 忘记上一步状态。
• 无限循环。
• 生成看似合理但没有验证的结果。
• 把错误结果写入文件或系统。
• 拿到过大权限后误操作生产环境。

所以今天研究 Agent 工具链，重点不只是"哪个框架更火"，而是完整链路能不能做到：可控、可恢复、可观测、可验证、可评测、可交付。

Agent 和 Harness 分别是什么？

Agent 不是普通聊天机器人。普通聊天机器人主要是"输入文本，输出文本"。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 客户端使用，而不是每个框架都单独写插件。

可以把 MCP 理解为"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"。

长期记忆是跨任务复用信息，例如"这个项目使用 Java 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：任务边界由 Harness 规定，工具权限由 Harness 控制，执行状态由 Harness 保存，验证标准由 Harness 执行，上线流程由 Harness 接管。

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

Java 后端场景怎么落地？

对 Java 后端开发者来说，不要一上来追求"全自动程序员"。更现实的切入点是低风险、高重复、有验证标准的任务。

日志分析 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 官方文档：https://openai.github.io/openai-agents-python/
• LangGraph 官方文档：https://docs.langchain.com/oss/python/langgraph/overview
• Model Context Protocol 官方文档：https://modelcontextprotocol.io/
• Agent2Agent Protocol 官方文档：https://a2a-protocol.org/
• Inspect AI 官方文档：https://inspect.aisi.org.uk/

作者：武子康的个人博客