《工具包即产品：智能体AI中工具包的实用指南》
了解什么是智能体工具包及其七个组成部分，包括工具、上下文、约束条件、评估标准，以及值得了解的子智能体、故障模式和框架。
来源: The Harness Is the Product: An End-to-End Guide to Harnessing in Agentic AI
想象将同一个语言模型交给两个不同的团队。A团队开发出一个能够修复庞大代码库中的错误、运行测试套件并提交规范拉取请求的自动化工具；而B团队则打造了一个聊天助手，它仅仅几条消息后就记不住对话内容，还擅自编造公司政策。尽管权重完全相同，但两者的成果却天差地别。
“框架”指的是围绕模型构建的所有组件。它包括让模型能够运行的循环结构、模型可以调用的工具、上下文窗口的管理方式、防止其做出错误行为的约束机制，以及告知其是否成功的反馈机制。接下来的内容将从零开始，介绍什么是智能体，逐步讲解框架的各个组成部分、子智能体和数据压缩等开发模式、一些知名的系统以及目前可用的框架。无需任何先前的智能体使用经验。
基础知识
智能体 AI 的含义
抛开炒作不谈，智能体其实很简单：
智能体是一种在循环中运行的语言模型，它会使用各种工具，直到实现目标为止。
这需要三个要素：一个能够进行推理并选择下一步行动的模型，模型可以调用的工具，如网络搜索、文件访问、代码执行、数据库查询或发送邮件，以及一个循环结构，将每个工具的运行结果反馈给模型，以便其决定下一步该做什么。
聊天机器人只会回复一次然后停止，而智能体则会持续运作：它执行某个动作，查看结果后再次采取行动。正是这种循环使得文本预测工具能够真正完成工作，本文的其余部分将对此进行进一步阐述。
什么是“马具”？
可以把“马具”视为那个循环的运行环境。模型负责决定下一步该做什么，而“马具”则负责将其执行，并确保整个过程的安全、高效、可监控且可控制。这个名字让人联想到软件测试中的测试框架，或是马背上的马具：原始的力量需要结构化的引导才能用于有意义的工作。
具体而言，该框架负责执行模型请求的工具调用，控制模型在每一步所看到的内容，实施权限管理，处理故障、重试及无限循环问题，跟踪进度，并判断任务何时完成或何时需要停止并寻求人工干预。
一个便于理解的方式是：模型在每次调用之间没有记忆。每次被调用时，它都从空白状态开始，读取给定的文本并输出一个结果。其余的一切——脚本、辅助工具、运行环境以及安全机制——都属于该框架。如果调整这些要素，同一个“演员”的表现也会截然不同。
为何框架如此重要
主要有三个实际原因。
模型本身的性能会逐渐趋同，而支撑框架的优化效果则不会。各前沿模型的原始能力越来越接近。在那些用于衡量解决实际软件问题的测试中，同一个模型由于所依赖的工具、提示词和反馈机制的不同，其表现可能会出现显著差异。到了某个阶段，支撑框架便成了决定性能差异的关键因素。
长任务会放大微小的错误。如果某个模型每一步的可靠性为99%，那么在50步的任务中，其成功率仅约为60%，因为0.99的50次方大约等于0.605。验证、重试、检查点以及路径修正等机制就是用来应对这种累积效应的支撑框架组件，它们能将演示版本与最终产品区分开来。
自由需要约束。任何能够执行shell命令、转移资金或与客户交互的智能体都必须设有权限限制、沙箱环境以及审计日志。这些功能都存在于控制框架中，而模型本身并不提供任何此类功能。
控制框架的构成
编程智能体、研究智能体和支持智能体通常都包含七个组成部分，下面将逐一介绍。
1. 系统提示，即基本准则
在这里，智能体会被告知其角色、权限限制、行为规范以及各类工具的用途。在成熟的产品中，这类文本长达数千字，其编写方式与源代码一样严谨，会涉及语气、安全性、何时先提问以及如何处理模糊的指令等内容。
新手可能会写一句，称该工具是实用的编程助手。而正式的提示则会明确说明操作流程：编辑前先打开文件，尽量进行小幅度修改，每次修改后都要运行测试，若两次测试均失败则停止并报告问题，绝不能直接将修改内容推送到主分支，此外还有许多类似的规则。
2. 工具层，即操作手段
工具是模型可以被调用的函数，它由名称、描述以及参数的类型结构来定义。模型以结构化格式请求调用工具，随后工具执行相应操作并将结果返回。
工具设计是一门常被低估的技艺。它实际上就是为非常具体的用户设计的API：
- 描述相当于提示词。模型会根据描述来选择工具，因此模糊的描述会导致选择错误的工具。
这方面的一个重要进展是模型上下文协议，Anthropic在2024年底将其开源，目前许多行业都已采用。该协议规范了工具提供方向任何智能体暴露工具的方式，大致相当于一种通用连接器：只需实现一次集成，即可将其接入任何框架中。
3. 上下文管理，即工作记忆
上下文窗口就是模型所感知的整个世界。通常情况下，这些窗口的容量在数十万到一百万个标记之间，听起来似乎很大，但当一个智能体已经读取了四十个文件并执行了六十条命令后，这个容量其实也就足够了。
决定模型在每一步能看到什么内容，可能是该系统中最具价值的关键因素，从业者现在将此称为上下文工程，它已基本取代提示工程，成为核心技能。相关技术从简单到复杂不等：包括截断（仅保留最近的消息或文件的一部分）、检索（对知识库进行索引，仅提取当前所需的资料）以及压缩。在压缩机制下，当上下文窗口接近满载时，模型会撰写会话摘要，该摘要会取代原始记录，随后工作可以继续进行。正是通过这种方式，智能体才能持续处理任务数小时之久。
4. 内存：长期存储机制
上下文仅持续一个会话，而记忆则会保留。通常会分层利用这些记忆：
- 项目记忆，例如仓库中的指令文件，用于向编程智能体传授相关规范和构建命令，并在会话开始时被读取；
- 用户记忆，即通过多次对话积累的偏好设置；
- 情景记忆，用于记录过去的运行情况，通常存储在向量数据库中，以便在类似情况再次出现时检索。
5. 规则约束、权限控制与沙箱机制，即制动装置
安全层会持续判断某个操作是否真的应该执行。实际上这意味着：
- 权限层级。读取操作可自由进行，写入操作需通过策略检查，而部署、发送、删除或支付等不可逆操作则需要获得人工的明确批准。
6. 验证与反馈，监督之眼
没有什么比能够测试自身输出的方法更能可靠地提升智能体的性能了。编程型智能体会在每次编辑后进行编译、代码检查并运行测试；研究型智能体会对比多个来源的信息以验证结论；浏览器型智能体则会截取屏幕画面，确认实际加载的内容。有些框架还会加入审核机制，即另一个模型会在接受第一个模型的答案之前，根据特定标准对其进行评分。
这直接解决了累积误差的问题——能够发现自己出错的智能体可以重新尝试，而无法察觉错误的智能体则可能会直接输出错误结果。
7. 可观测性，即飞行记录仪
在实际应用中，每一个模型请求、每一次工具调用以及每消耗一个令牌都会被记录下来。借助这些追踪信息，你可以重新运行出错的流程，找出出问题的环节，进而修正有问题的提示词、工具或策略。围绕这一理念诞生了诸多产品，包括LangSmith、Langfuse、Braintrust，以及用于生成式AI的OpenTelemetry规范——因为在没有日志的情况下调试智能体，就如同在没有日志的情况下调试分布式服务一样困难。
高效循环运行
为各组成部分命名是相对简单的部分。能够承受演示场景考验的框架与能够应对正常工作日挑战的框架之间的差异，就在于以下这些实践方法。
计划、执行、验证
简单的智能体可以立即投入工作。而成熟的框架则会设定一定的工作节奏：通过将目标分解为任务列表来制定计划，逐步推进，每完成一步后都检查结果，然后再调整计划并继续执行。书面计划具有双重作用——因为它会在每轮迭代中被重新阅读，从而使模型始终专注于长期任务；同时，它还能让观察者实时看到进展，其价值远超预期。
结构化输出
每当程序需要使用模型的输出时，都应通过架构对其进行约束。目前的 API 支持强制调用工具以及基于架构的验证生成。散文是为人类准备的；代码则应当具备结构。
成本与延迟
智能体会快速消耗令牌，这使得经济模型设计成为一个重要问题。在多轮对话中，将大的静态前缀（系统提示语加上工具定义）缓存起来，其成本远低于每次重新发送，这对于长时间对话而言是巨大的优势。路由机制会将常规步骤交给小型、响应快速的模型处理，而将需要推理的步骤留给高级模型处理。诸如读取十个文件或查询五个信息源之类的独立子任务可以同时进行。
多智能体系统及更高级的应用
子智能体与协调机制
当任务超出单个上下文窗口的容量时，就需要采用多智能体系统。协调器会将目标拆分，然后创建多个子智能体，每个子智能体都有独立的上下文、通常更有限的工具集以及明确的任务要求。每个子智能体仅完成自己的工作并返回结论，而不需要提交完整的处理历史记录。
真正的优势并不像速度那样显而易见：每个子代理都在独立的上下文中工作，而非仅仅并行处理。十个子代理可以各自用一个子系统填满整个窗口，而协调器只需保留十个简短的总结。
常见的架构包括协调器与工作节点（最为常见）、诸如草拟、评审和修改之类的流程，以及辩论小组——在这种模式下，多个代理独立处理问题，由一名裁判综合各方的答案。辩论方式成本较高，但适合处理高价值的问题。
完成这份报告的团队总结出了一些宝贵的经验：
- 需明确每项任务所需的投入程度，否则即便是简单的问题也可能引发数十次搜索。
- 撰写的任务说明应详尽且自成一体，因为子代理无法看到上级任务的上下文。
检查点与持久性
长时间运行的代理可能会因崩溃、速率限制或重启而在中途失败。生产环境会利用检查点状态，记录对话内容、任务列表及工具运行结果，这样就可以从第37步继续执行，而无需重新开始。这正是持久性工作流引擎的职能范畴，也有不少代理框架就是直接基于这类机制构建的。
Evals：该工具的测试套件
智能体行为具有概率性，因此周一有效的提示词可能在周二失效。优秀的团队会维护一套评估体系，其中包含数十到数千个真实的任务，其结果可以自动检测。测试是否通过？是否找到了正确答案？成本是否控制在预算范围内？在发布之前，所有提示词修改、新工具的引入以及模型更换都需经过这套评估体系。它发挥着其他领域中CI/CD所承担的作用，跳过它就意味着在没有任何检测工具的情况下工作。
计算机的使用，最终的考验
在最前沿的方案中，智能体会被配备屏幕、键盘和鼠标，能够运行任何应用程序，无论其是否具备API。这加剧了之前所有问题的难度：屏幕截图会消耗大量令牌，因此必须严格控制上下文；一次错误的点击就可能造成严重后果，所以权限管控更为严格；而验证则意味着需要在每一步之后实际查看屏幕内容。
现有系统如何应用这些理念
Claude Code，一款编程辅助工具。它堪称设计理念的典范。该工具集精简而高效，具备文件读取、写入和编辑功能，以及shell命令和代码搜索功能，而非数百种微型工具。验证是其核心功能：它会运行编译器、代码检查工具和测试程序，一旦出现故障就会进行迭代优化。项目指令文件则起到记忆存储的作用。这些功能均不属于模型本身的能力，正因如此，同一个模型在其中的表现会有所不同。
深度研究产品，一种研究工具套件。大型实验室的研究工具能够将一个查询转化为持续数分钟的自主调查，最终生成一份附有引用来源的报告。这类工具的典型特点是会事先制定研究计划，有时还会提交审批，从而在成本高昂的工作开始之前，以最低代价让人类参与其中。搜索流程会不断读取信息、发现缺失之处并再次搜索，而引用元数据则会与事实一同贯穿整个处理流程。
Manus与上下文工程学派。 Manus团队在2025年产品发布前后发布了关于其内部机制极为坦诚的说明，其中几点已被广泛传播。应将KV缓存视为一种设计约束：保持提示语的开头部分稳定（系统提示语顶部不得包含时间戳），因为输入标记的数量很可能远远超过输出标记的数量。避免在会话过程中添加或删除工具，否则会导致缓存失效，而且当之前的调用中提到已消失的工具时，会令模型困惑；应保持工具列表不变，并对当前可选择的工具进行隐藏处理。
光标与集成开发环境框架。这款专为人工智能设计的编辑器展现了截然不同的深度环境集成理念。它利用代码库的语义索引实现快速检索，将修改以可审查的差异形式呈现，从而使负责批准合并的人成为以界面形式呈现的权限控制机制；同时在独立分支上运行后台任务，并将代码检查工具和类型检查器的输出反馈回循环流程中。这七大组件只是以不同的形式存在罢了。
在那些注重合规性的企业中，支撑工具的作用在于确保合规性。面向客户的客服人员则会调整优先级：避免错误操作比单纯的能力更重要。因此他们从约束条件入手：操作范围限定在已批准的知识范围内，所有操作都要依据业务系统架构进行验证（如退款金额有限制、需先确认身份），在信心不足时必须交由其他人处理，并且要保留完整的审计日志。在受监管的行业里，这类支撑工具实际上就是产品本身。
现有的框架与工具
如今很少再仅通过原始API调用来构建支撑工具了。以下是按设计理念大致分类的常见选项：
- Claude Agent SDK。这是Claude Code背后的支撑工具，以库的形式提供，包含循环处理、工具功能、子代理、权限控制以及数据压缩功能。最适合在Claude平台上快速构建功能完善的智能代理。
- OpenAI Agents SDK。 提供用于智能体、任务交接、约束机制、会话管理及追踪的轻量级功能。非常适合 OpenAI 生态系统中的多智能体应用。
- LangGraph。 将智能体视为显式状态机，具备检查点功能、人工干预中断机制以及持久化执行能力。最适合复杂、可控制且需要长时间运行的工作流。
- CrewAI。 支持基于角色的团队协作，如研究员和撰稿人角色。非常适合快速构建多智能体原型及内容处理流程。
- AutoGen、AG2 和 Semantic Kernel。 以对话为中心的多智能体工作模式，可逐步发展为企业级工具。最适合 .NET 和 Azure 环境下的应用以及研究实验。
- smolagents。 一个极简化的库，允许智能体通过编写代码来执行操作。非常适合使用开放模型进行可定制化的开发。
- Pydantic AI。具备类型安全特性、以模式定义优先的智能体，能生成经过验证的输出。最适合需要严格类型控制的 Python 团队。
- Vercel AI SDK。以 TypeScript 为基础的底层组件，支持智能体循环控制。最适合 JavaScript 生态系统中的 Web 开发者和产品工程师。
围绕这些技术还存在一些连接性组件：用于标准工具的 MCP、追踪与评估平台、可靠的执行引擎以及用于安全代码执行的沙箱服务。
选择建议：在学习阶段，可以先自己用模型 API、while 循环和两个工具写一次简单的循环代码，大概一百行左右。这样之后就不会觉得任何框架都有魔法般的效果了，而这正是学习的意义所在。在正式部署时，则应选择与模型提供商及所用语言最为匹配的框架，把节省下来的时间用于构建框架无法提供的东西，也就是你自己的工具、评估机制以及规范约束。
# The whole idea, in miniature
while not done:
response = model.generate(context, tools) # model decides
if response.tool_calls:
results = execute(response.tool_calls) # harness acts (safely!)
context = manage(context + results) # harness curates memory
else:
done = verify(response) # harness checks the work
故障模式
以下是智能体常见的故障方式，每种都配有相应的解决方案：
- 上下文恶化。窗口中逐渐充斥过时的工具输出，质量不断下降，几小时后目标就会被遗忘。解决方案：对内容进行压缩、记录要点，并定期重申目标。
- 死循环。同一个有问题的指令不断重复执行，每次尝试的成本仅为几美分。解决办法：检测循环、设定迭代次数限制，并强制调整策略。
- 工具泛滥。面对四十种类似的工具，模型会在最糟糕的时刻选择错误的工具。解决方案：使用数量更少但功能更精准、且有明确说明的工具。
需牢记的事项
模型提供智能，而框架则将其转化为实际功能。框架由一个循环结构及七个核心组件构成：指令集、工具、上下文管理、内存、约束机制、验证功能以及可观测性。围绕这些组件还有执行长任务的流程模式，如规划、执行与验证、数据压缩、检查点设置、子代理以及评估功能。大多数代理系统的故障源于框架问题，而大多数改进也体现在框架层面。因此当代理系统表现不佳时，应首先检查框架结构，然后再考虑更换模型。
相关阅读
- 实际应用中的子代理：角色、预算、限制与隐性故障 —— 如何编写持久稳定的 Claude Code 子代理：包括角色设定、交接文件、运行状态管理、预算控制、限制措施、隐性故障检测机制，以及基于 Copilot 的辅助方案，这些内容均来自在十余个代码仓库中实际使用的子代理案例。
- 代理式分析远不止文本转 SQL：来自 Anthropic 的启示 —— Anthropic 的自助分析相关文章阐述了语义层、技能模块、评估标准及数据基础的重要性，同时解释了为何仅依靠文本转 SQL 会给人一种虚假的精确感。