万字长文！大模型Agent开发宝典：深度解析Anthropic Agent架构与实践！

本文系统介绍了Anthropic的大模型Agent技术架构与实践，涵盖上下文工程核心概念、Claude Agent SDK使用方法、Agent Skills设计理念、MCP代码执行优化策略、高级工具使用技术及长时间运行Agent解决方案。文章强调Agent通过文件系统环境自主探索需求，而非一次性加载所有提示和工具，体现了Anthropic对通用Agent的架构设计和实践思路。

bugyinyin

418人浏览 · 2026-01-12 09:00:00

bugyinyin · 2026-01-12 09:00:00 发布

Effective context engineering

for AI agents

Effective context engineering for AI agents

www.anthropic.com/engineering/effective-context-engine

1. 上下文工程与提示词工程的区别

**上下文工程（context engineer)是提示词工程(prompt engineer)的自然延伸。**提示词工程指的是编写和组织 LLM 指令以实现最佳结果的方法。上下文工程指的是在 LLM 推理过程中，用于管理和维护最佳token（信息）集的一系列策略，包括提示之外可能出现的所有其他信息。

在早期使用LLM进行工程设计时，Prompt是人工智能工程工作中最重要的组成部分，因为大多数多轮会话之外的应用场景都需要有一次性分类或文本生成任务优化的Prompt。顾名思义，提示词工程的主要重点在于如何编写有效的提示词(Prompt)，尤其是System Prompt。

然而，随着Agent的发展，Agent需要在多轮推理和更长的时间跨度内运行。开发者需要管理整个上下文状态（系统指令、工具、MCP、外部数据、消息历史记录等)的策略。

一个循环运行的Agent会生成越来越多的数据，这些数据可能与下一轮的推理相关，因而这些信息必须不断进行提炼。上下文工程的艺术和科学在于——如何从不断演进的浩瀚信息海洋中，筛选出哪些信息能够进入有限的上下文窗口。

我的理解：Agent的执行过程是一个Loop, 这个Loop过程中会产生大量的信息，一部分是模型输出的，更多的是工具的response导致的。但上下文的窗口有限，如何工程化地管理这些信息，将哪些信息添加到上下文窗口中，就是所谓的上下文工程。

2. 注意力资源是稀缺的

这种注意力稀缺源于 LLM 的架构限制。LLM 基于Transformer 架构，这使得每个 token 能够关注整个上下文中的其他 token。这导致 n 个 token 之间存在 n² 对关系。

随着上下文长度的增加，模型捕捉这些成对关系的能力会逐渐捉襟见肘，从而在上下文大小和注意力焦点之间形成了一种自然的张力。此外，模型会根据训练数据分布来发展其注意力模式，而这些分布中较短的序列通常比较长的序列更常见。这意味着模型对于上下文范围的依赖关系的经验较少，并且针对这些依赖关系的专用参数也较少。

鉴于 LLM 受到有限的注意力预算限制，良好的上下文工程意味着找到尽可能小的高信号 token 集，以最大化某个期望结果的可能性。

3. System Prompt的复杂度

System Prompt应极其清晰、使用简洁的语言，并以适合Agent理解的方式呈现概念。

这种“合适的程度”介于两种常见糟糕的情况之间：

一种极端情况是，工程师在提示中硬编码复杂而脆弱的逻辑，以精确地引导Agent的行为。这种方法会造成系统的脆弱性，并随着时间的推移增加维护的复杂性。

另一种极端情况是，工程师有时提供模糊不清、过于笼统的指导，无法为LLM提供期望输出的具体信号，或者错误地假设上下文。

System Prompt最佳的编写复杂程度应达到平衡：既要足够具体以有效引导Agent行为，又要足够灵活以提供强大的启发式方法来指导Agent的行动轨迹。

启发式方法是我之前在阅读Anthropic博客时经常看到的一个词，这里说说我的理解：给一个明确的行动宗旨，然后让模型根据这个宗旨自由思考和发挥。这里可以联想到“第一性原理“，如果你可以给模型一些本质性的提示，然后让模型围绕着原理去行动，那可能可以通过短小的提示词达到不错的效果。

文中建议将提示信息组织成不同的部分（例如<background_information>、<instructions>、## Tool guidance、## Output description等），并使用 XML 标记或 Markdown 标题等技术来区分这些部分。尽管随着模型功能的增强，提示信息的确切格式可能变得不那么重要了。

我的理解是，大段的文本可能很难让模型找到当前推理next token时应该回顾哪些信息（很多信息是无用的），这种强调可以提高某些情况推理时的注意力权重，并且让模型把某部分语句视为一个整体。

4. 工具

工具定义了智能体与其信息/行动空间之间的契约，工具的两个原则：一是返回高效的信息，二是鼓励Agent采取高效的行为。

与精心设计的代码类似，工具也应具备自包含性、容错性强，并且其预期用途清晰明确。同样，输入参数也应具有描述性、无歧义，并能充分发挥模型的固有优势。

如果人类工程师都无法明确判断在特定情况下应该使用哪个工具，就不能指望Agent做得更好。为Agent精心挑选一套最小可行工具集，也有助于在长期交互过程中更可靠地维护和精简上下文信息。

5. Few-shot

提供示例，也称为few-shot，是一种众所周知的最佳实践，我们始终强烈建议这样做。然而，有的团队通常会在提示中塞入一长串边缘情况，试图阐明 LLM 在特定任务中应遵循的所有规则。文中不建议这样做。相反，作者建议努力整理一组多样化、规范的示例，以有效地描述Agent的预期行为。对于 LLM 来说，示例胜过千言万语。

应该告诉Agent你应该做什么，而边缘case并不是Agent在大多数行动条件下会用到的情况，相反还会干扰正常的行为？

6. 信息检索

本文倾向于为Agent提供一个简单的定义：在循环中自主使用工具的 LLM。

Anthropic 的智能体编码解决方案Claude Code就采用了这种方法，对大型数据库进行复杂的数据分析。该模型可以编写目标查询、存储结果，并利用 Bash 命令（例如 head 和 tail）来分析海量数据，而无需将完整的数据对象加载到上下文中。

这种方法类似于人类的认知：我们通常不会记忆整个信息库，而是会引入外部组织和索引系统（例如文件系统、收件箱和书签）来按需检索相关信息。

让Agent自主导航和检索数据还能实现「渐进式信息披露」——换句话说，允许Agent通过探索逐步发现相关Context。每次交互都会产生Context，为下一步决策提供参考：文件大小暗示复杂性；命名约定暗示目的；时间戳可以作为相关性的指标。Agent可以逐层整合理解，只在工作记忆中保留必要的内容，并利用笔记策略来增强持久性。这种自主管理的Context Window使Agent能够专注与当前工作相关的信息子集，而不是淹没在详尽但可能无关的信息中。

运行时检索数据比使用预先提供的数据要慢（直接放到上下文中的数据）。因此需要经过深思熟虑的工程设计，以确保LLM)拥有合适的工具和启发式方法，从而有效地驾驭信息。如果没有适当的指导，Agent可能会因为滥用工具、钻牛角尖或无法识别关键信息而浪费信息。

使用混合策略的Agent：预先检索一些数据以提高速度，然后根据自身判断进行进一步的自主探索。自主程度的“合适”界限取决于具体任务。Claude Code 就是一个采用这种混合模型的Agent：CLAUDE.md文件会被预加载到上下文中，而像glob和grep这样的基本工具则允许它导航环境并即时检索文件，从而有效地绕过了过时的索引和复杂的语法树等问题。

在Claude Code的工程实践中，这实际上是文件系统。

7. 针对长周期任务的上下文工程

长周期任务要求智能体在一系列动作中保持连贯性、上下文关联性和目标导向行为，即使动作数量超过了 LLM 的上下文窗口。对于持续数十分钟到数小时的连续工作任务，例如大型代码库迁移或综合研究项目，Agent需要专门的技术来克服上下文窗口大小的限制。

压缩：压缩是指在对话接近上下文窗口上限时，对其进行总结，并使用该总结内容重新启动一个新的上下文窗口。压缩通常是上下文工程中实现更佳长期一致性的第一步。其核心是以高保真度的方式提取上下文窗口的内容，使Agent能够以最小的损失继续运行。

清除工具调用和结果就是一个很容易实现的冗余内容示例——一旦某个工具在消息历史记录中被调用过，Agent为什么还需要再次查看原始结果呢？清除工具结果是最安全、最轻量级的压缩方式之一。

实际上是上下文工程中的移除，虽然没有单独列出来，被当成了压缩的一种，但是我倾向于它和压缩不一样。

结构化笔记：结构化笔记，或称Agent Memory，是一种让Agent定期记录笔记并将其存储在上下文窗口之外的记忆中的技术。这些笔记会在稍后被调回上下文窗口。

sub-agent架构：sub-agent架构提供了另一种绕过上下文限制的方法。与其让单个agent尝试维护整个项目的状态，不如使用专门的sub-agent，利用清晰的上下文窗口来处理重点任务。主agent负责协调高层次的计划，而agent则执行深度技术工作或使用工具查找相关信息。每个子agent可能会进行广泛的探索，使用数万个或更多的token，但最终只会返回其工作的精简摘要（通常为 1,000-2,000 个token）。

感想：一篇总结性文章，基本没有新的信息。system prompt, tool, note\filesystem\remove & compact如果有agent开发经验的话会和自己脑子中的概念联系在一起，有种豁然开朗的感觉。

这份完整版的大模型 AI 学习和面试资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】

在这里插入图片描述

Building agents with the

Claude Agent SDK

原本对这篇文章内容不感兴趣，我认为最好的方式还是自己构造一个完全由自己控制的Agent，这样自由性最高也最可控。（不喜欢被束缚的感觉）

但是最近工作中有造配置化Agent轮子的需求，因此还是读一读。

https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk

www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk

1. 赋予Agent使用计算机的能力

Claude Code 的功能已经远远超越了编程工具的范畴。在 Anthropic内部，除了将其用于深度研究、视频制作和笔记记录以外，还将其应用于无数其他非编程场景。事实上，CC几乎已经成为Anthropic内部所有主要Agent循环的驱动框架。

Claude Code的架构其实很通用和合理，我认为是目前最好的Agent架构，它给了Agent一套可用的环境（一台电脑），这给予了Agent充分的自主探索的能力，非常通用和有效。这也是它具有高可迁移性的原因。

Claude Code 的核心设计原则是，它需要使用程序员日常使用的工具——需要能够在代码库中找到合适的文件，编写和编辑文件，检查代码、运行代码、调试代码，进行编辑，有时还需要循环执行这些操作，直到代码运行成功。

Anthropic团队发现，通过让 Claude 访问用户的计算机（通过Terminal），它就拥有了像程序员一样编写代码所需的条件。但这也使得 Claude Code 中的 Claude 能够高效地完成非编程性的任务。通过赋予它运行 bash 命令、编辑文件、创建文件和搜索文件的工具，Claude 可以读取 CSV 文件、搜索网络、构建可视化图表、解读指标，以及执行各种其他数字工作——简而言之，就是创建具有使用计算机能力的通用Agent。

Claude Agent SDK 背后的关键设计原则是赋予使用Agent计算机的能力，使其能够像人类一样工作。

理论上来说，给人一个电脑，它可以做无数工作，那么给Agent一台电脑，它也可以做无数的事情。

2. 创建新的Agent

给Claude配备一台电脑，就能让他构建出比以往更高效的Agent。例如，借助SDK，开发者可以构建：

金融Agent：构建能够理解您的投资组合和目标，并通过访问外部 API、存储数据和运行代码进行计算来帮助您评估投资的Agent。

个人助理Agent 。构建Agent，通过连接到您的内部数据源并跟踪跨应用程序的上下文，帮助您预订旅行和管理日程安排，以及安排预约、编写简报等等。

**客服Agent：**构建能够处理高度模糊的用户请求（例如客户服务工单）的Agent，通过收集和审查用户数据、连接到外部 API、向用户发送消息并在需要时升级到人工处理。

DeepResearch Agent：构建能够对大型文档集合进行全面研究的Agent，通过搜索文件系统、分析和综合来自多个来源的信息、跨文件交叉引用数据以及生成详细报告来实现。

3. Building Your Agent Loop

在 Claude Code中，Claude 通常在一个特定的反馈循环中运行：收集上下文 -> 采取行动 -> 验证工作 -> 重复。

本文中以构造一个Email Agent为例说明了这个过程：

收集信息：文件系统代表可能会引入模型上下文的信息。当 Claude 遇到大型文件（例如日志文件或用户上传的文件）时，它会使用诸如grep和tail之类的 bash 脚本来决定如何将这些文件加载到其上下文中。本质上，Agent的文件夹和文件结构就成为了一种上下文工程。

Email Agent可能会将之前的对话存储在一个名为“Conversations”的文件夹中。这样，当被问及相关内容时，它就可以搜索之前的对话以了解其上下文。

文件系统是对计算机文件的模拟，符合给Agent一台电脑的概念，也是动态加载上下文的一种抽象。

语义搜索：通常比Agent搜索速度更快，但准确性更低、维护难度更大、透明度也更低。它涉及将相关上下文“分块”，将这些块嵌入为向量，然后通过查询这些向量来搜索概念。鉴于其局限性，我们建议先使用Agent搜索，仅在需要更快的搜索结果或更多搜索变体时才添加语义搜索。

就是SDK里封装了RAG

subagents:Claude Agent SDK 默认支持subagents。

subagents主要有两个优点。首先，它们支持并行化：你可以启动多个子agent同时处理不同的任务。其次，它们有助于管理上下文：子agent使用各自独立的上下文窗口，并且只向协调器发送相关信息，而不是完整的上下文。这使得它们非常适合需要筛选大量信息（其中大部分信息无用）的任务。

在设计email agent时，我们可以为其添加“search subagent”功能。这样，邮件Agent就可以并行启动多个搜索子Agent，每个subagent针对您的邮件历史记录运行不同的查询，并仅返回相关的摘要，而不是完整的邮件线程。

subagents实际上是一个很微妙的场景，在过去几个月的工作中，我见到了大量不必要的subagent引入（实际上我认为这些工作给主agent提供一些工具就能完成），我困惑于到底什么场景需要引入subagent。现在我复读一下文中的观点：subagents适合需要筛选大量信息的任务。

compact: 当agent长时间运行时，上下文维护变得至关重要。Claude Agent SDK 的compact功能会在上下文接近限制时自动汇总之前的消息，从而避免agent因上下文窗口耗尽而中断。

4. Take Action

对于我们的Email Agent，我们可能会将“fetchInbox”或“searchEmails”等工具定义为Agent的主要、最频繁的操作。

(1)Bash

在我们的邮件Agent中，用户可能在附件中存储了重要信息。Claude可以编写代码下载 PDF 文件，将其转换为文本，然后通过调用相应的函数搜索其中的有用信息，如下所示：

(2)Code Gen

Claude Agent SDK 在代码生成方面表现出色——它生成的代码精确、可组合且可无限重用，是需要可靠执行复杂操作的Agent的理想输出。

例如，我们最近在Claude.AI中推出的文件创建功能完全依赖于代码生成。Claude 会编写 Python 脚本来创建 Excel 电子表格、PowerPoint 演示文稿和 Word 文档，从而确保格式一致并实现其他方式难以实现的复杂功能。

在我们的Email Agent中，我们可能希望允许用户创建入站邮件规则。可以编写代码在该事件发生时运行(onEmailRecived())

(3)MCP

MCP提供与外部服务的标准化集成，自动处理身份验证和 API 调用。这意味着您可以将Agent连接到 Slack、GitHub、Google Drive 或 Asana 等工具，而无需编写自定义集成代码或自行管理 OAuth 流程。

5. 检查和改进自身工作

能够检查并改进自身输出的Agent从根本上来说更加可靠——它们能在错误累积之前发现并纠正，在偏离目标时进行自我纠正，并在循环过程中不断优化。

(1)Defining rules

最好的反馈方式是为输出结果提供明确定义的规则，然后解释哪些规则失效以及失效的原因。

code linting是一种极佳的基于规则的反馈方式。反馈越深入越好。例如，通常情况下，生成 TypeScript 代码并进行代码检查比生成纯 JavaScript 代码更好，因为它能提供多层额外的反馈。

生成电子邮件时，您可能希望 Claude 检查电子邮件地址是否有效（如果无效，则抛出错误），以及用户以前是否向其发送过电子邮件（如果是，则抛出警告）。

这里相当于一些硬编码的规则，比如在构造react agent时，一个好的实践就是当它输出了不符合你要求的内容时，你硬编码一段提示告诉它为什么输出不对（类似给人类的UI错误信息），这样它下一轮循环就会规避这个错误。

(2)Visual feedback

视觉反馈：当使用Agent完成诸如用户界面生成或测试之类的视觉任务时，视觉反馈（以屏幕截图或渲染图的形式）会很有帮助。例如，如果要发送带有 HTML 格式的电子邮件，您可以截取生成的电子邮件的屏幕截图，并将其提供给模型进行视觉验证和迭代改进。然后，模型会检查视觉输出是否与请求的内容相符。

使用像 Playwright 这样的 MCP 服务器，可以自动执行此视觉反馈循环——截取渲染 HTML 的屏幕截图、捕获不同的视口大小，甚至测试交互元素——所有这些都可以在Agent的工作流程中完成。

(3)LLM as a judge

你还可以让另一个LLM根据模糊规则评测Agent的输出。这种方法通常不够稳定，而且可能会带来严重的延迟，但对于那些任何性能提升都值得付出代价的应用来说，它还是很有帮助的。

我们的Email Agent可能会安排一个单独的subagent来判断邮件草稿的语气，看看它们是否与用户之前的消息相符。

(2)和(3)都属于用LLM在运行中在线检验结果，我认为(2)更倾向于让Agent自评，(3)是引入额外的LLM和提示词进行检查。

6. 测试和改进Agent

改进Agent的最佳方法是仔细查看其输出，特别是失败的情况，并设身处地地站在Agent的角度思考：它是否拥有完成任务所需的工具.

如果您的Agent误解了任务，可能会遗漏关键信息。您能否调整搜索 API 的结构，使其更容易找到所需信息？

如果您的Agent反复无法完成某项任务，您能否在工具调用中添加正式规则来识别并修复该故障？

如果你的Agent无法纠正其错误，你能否为其提供更有用或更具创造性的工具，使其以不同的方式解决问题？

如果随着添加功能，Agent的性能会发生变化，请根据用户的使用情况构建一个具有代表性的测试集，以进行评测。

Equipping agents for

the real world with Agent Skills

这篇文章发出来以后很火，创造了Skills的概念。这里再读一下。

我这里想讲一下我认为Skill被提出来的理由：尽管Claude Code只是一个Code Agent，因为太强大实际上经常作为一个通用Agent被用来干其他事，并且用来干事的人无法修改Claude Code的内置Prompt，但是可以通过创建一个文件夹指引它，我想这是Claude Code提出Skills而其他团队提不出来的理由。

结合上篇文章，我认为本文的Skill和上一篇文章的Claude SDK应该是Anthropic发现自己的Agent很强以后提出来的两种思路：(1)给一个通用的SDK屏蔽“为Claude提供一个Computer和上下文管理“所需要的复杂细节，快速搭建一个Agent；(2)复用Claude Code, 允许通过创建文件夹（Skills）的方式告诉Claude它需要的一切知识。

那基于我的假设，一个已有的Agent，如果不是抱着做通用Agent的念头，并且拥有非常通用的工具链，实际上是不值得引入Skills这个概念的。

Equipping agents for the real world with Agent Skills

www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

随着模型能力的提升，我们现在可以构建能够与功能齐全的计算环境交互的通用Agent。例如，Claude Code可以利用本地代码执行和文件系统完成跨领域的复杂任务。但随着这些智能体功能越来越强大，我们需要更具可组合性、可扩展性和可移植性的方法，为它们配备特定领域的专业知识。

这促使我们创建了Agent Skills——它是由指令、脚本和资源组成的有序文件夹，Agent可以动态发现并加载这些文件夹，从而更好地完成特定任务。Skills 通过将您的专业知识打包成可组合的资源供 Claude 使用，扩展了 Claude 的功能，将通用Agent转变为满足您需求的专用Agent。

一个没有背景知识的入职的新人，实际可以通过阅读公司电脑中的文档得知自己要干什么，我想大概是这个道理。

为Agent构建Skill就像为新员工编写入职指南。如今，无需再构建零散的、定制化的Agent，任何人都可以通过捕获和共享流程知识，为Agent添加可组合的功能。本文将解释什么是Skill，展示其工作原理，并分享构建Skill的最佳实践。

Skill是一个目录，其中包含一个 SKILL.md 文件，该文件包含组织有序的文件夹，其中包含指令、脚本和资源，这些指令、脚本和资源为Agent提供额外的功能。

这份完整版的大模型 AI 学习和面试资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】

在这里插入图片描述

1. Skill的例子

来看一个实际例子——Claude最近新增的文档编辑能力。Claude已经对 PDF 文件有一定的了解，但直接操作 PDF 文件的能力有限（例如，填写表单）。而这个PDF Skill赋予了Claude这些新能力。

简单来说，Skill就是一个包含SKILL.md file的目录。该文件必须以 YAML 前置元数据开头，其中包含一些必需的元数据：name和description。启动时，Agent会将每个已安装Skill的name和description预加载到其System Prompt中。

Skill.md的yaml元数据是「渐进式披露」(progressive disclosure)的第一层：它提供的信息恰到好处，足以让 Claude 知道何时应该使用每项技能，而无需将所有信息加载到上下文中。

文件的实际内容是第二层详细信息。如果 Claude 认为某项技能与当前任务相关，它会读取完整的SKILL.md文件并将其加载到上下文中。

随着Skill复杂性的增加，它们可能包含过多的上下文信息，无法全部放入单个SKILL.md中，或者某些上下文信息仅在特定场景下才相关。在这种情况下，技能可以在技能目录中捆绑其他文件，并在SKILL.md文件中按名称引用这些文件。这些额外的链接文件构成了第三层（及更多层）的详细信息，Claude 可以根据需要选择浏览和查找这些文件。

类似云文档里的员工手册，有跳链。

在下面的 PDF Skill例子中，SKILL.md引用了两个附件（reference.md和forms.md），作者选择将这两个文件与核心的SKILL.md文件一起打包。通过将表单填写说明放到了单独的文件（forms.md），这样作者可以保持Skill核心内容的简洁，并相信 Claude 只会在填写表单时阅读forms.md文件。

「渐进式披露」(progressive disclosure)是使Agent技能灵活且可扩展的核心设计原则。就像一本组织良好的手册，从目录开始，然后是具体章节，最后是详细的附录一样，这允许 Claude 仅在需要时加载信息：

拥有文件系统和代码执行工具的Agent在执行特定任务时，无需将Skill的全部内容读取到上下文窗口中。这意味着Skill中可以包含的上下文信息量实际上是无限的。

2. 技能和上下文窗口

在初始化时，上下文窗口会显示核心System Prompt和每个已安装Skill的元数据，以及用户的初始消息；然后Claude 通过调用 Bash 工具读取pdf/SKILL.md的内容来触发 PDF 技能；之后Claude选择阅读与该技能捆绑在一起forms.md文件；最后，Claude 从 PDF 技能中加载了相关说明后，便开始执行用户的任务。

3. 技能和代码执行

LLM在许多任务上表现出色，但某些操作更适合传统的代码执行。例如，通过生成token来对列表进行排序远比直接运行排序算法成本高得多。除了效率问题外，许多场景只有代码才能提供确定性与可靠性。

在我们的例子中，PDF Skill包含一个预先编写的 Python 脚本，该脚本读取 PDF 文件并提取所有表单字段。Claude 无需将脚本或 PDF 文件加载到上下文中即可运行此脚本。由于代码是确定性的，因此该工作流程具有一致性和可重复性。

skill的描述中说明了这个extract_fields.py这个python文件是干嘛的，Claude只需要运行extract_fields.py就可以得到结果，这实际上也是一种工具，但是是通过动态运行的代码文件实现的工具。

tool_name是extract_fields，两个param是pdf_path和output_json_path。

4. Skill的开发和评测

**(1)站在Claude的角度思考：**观察Claude在实际场景中如何使用你的Skill，并根据观察结果进行迭代：注意是否存在意料之外的轨迹或对特定情境的过度依赖。特别注意Skill的name和description。Claude会根据这些信息来决定是否在当前任务中触发该技能。

**(2)与 Claude 迭代：**在与 Claude 一起完成任务时，请 Claude 将成功的方法和常见错误记录下来，并将其转化为可复用的技能代码和上下文。如果它在使用技能完成任务时偏离了方向，请它进行自我反思，找出问题所在。这个过程将帮助你发现 Claude 实际需要的上下文，而不是试图预先预测它需要什么。

也是在前文中多次提到的站在agent的角度思考，以及让agent自己说自己缺少了什么。

Code Execution With MCP

Code execution with MCP: Building more efficient agents

www.anthropic.com/engineering/code-execution-with-mcp

MCP是一种用于将 AI Agent连接到外部系统的开放标准。传统上，将Agent连接到工具和数据需要针对每对组合进行定制集成，这造成了碎片化和重复工作，使得真正互联的系统难以扩展。MCP 提供了一种通用协议——开发者只需在Agent中实现一次 MCP，即可解锁整个集成生态系统。

开放是MCP的好处也是坏处。开放使得协议通用，开放也带来的工具定义不清晰，还有response的内容和格式不一定是你想要的。（因为不是你自己封装的工具，纯粹给LLM一大坨json response通常效果都是很差的）

本文探讨一种叫做Code execution的方式, 让MCP可以消耗更少的token.

1. 工具过度消耗token会降低Agent的效率

(1)工具定义占用上下文token

大多数 MCP client会预先将所有工具定义直接加载到上下文中，并直接把tool call语法暴露给模型。

工具描述会占用更多上下文窗口空间，从而增加响应时间和成本。如果agent连接到数千个工具，则在读取请求之前需要处理数十万个token。

(2)中间的工具结果会消耗额外的token

这里加了个限制词，“中间”，显然这里只讨论不直接使用工具response的情况。即你实际上只需要response的一部分或者response处理后的结果（比如avg,sum,cnt)

2. 使用MCP Code execution可以提高上下文的效率

随着代码执行环境在Agent中变得越来越普遍，一种解决方案是将 MCP 服务器呈现为代码 API，而不是直接调用工具。这样，Agent就可以编写代码与 MCP 服务器交互。

CodeAct的思路再次出现了？

这种方法解决了两个挑战：Agent可以只加载所需的工具，并在执行环境中处理数据，然后将结果返回给模型。

(1)MCP tool转文件树

一种可能的实现方式：从已连接的 MCP 服务器生成所有可用工具的文件树

servers├── google-drive│   ├── getDocument.ts│   ├── ... (other tools)│   └── index.ts├── salesforce│   ├── updateRecord.ts│   ├── ... (other tools)│   └── index.ts└── ... (other servers)
``````plaintext
每个工具对应一个文件。

Agent程序通过探索文件系统来发现工具：列出./servers/目录以查找可用服务器（例如google-drive和salesforce），然后读取所需的特定工具文件（例如getDocument.ts和updateRecord.ts）以了解每个工具的接口。这使得Agent程序仅加载当前任务所需的定义。这可以将token使用量从 150,000 个减少到 2,000 个，从而节省 98.7% 的时间和成本**。**

符合Skills一文中提到的「渐进式披露」，实际上就是让agent动态加载工具描述。

模型非常擅长浏览文件系统。将工具以代码形式呈现在文件系统中，可以让模型按需读取工具定义，而无需预先读取所有定义。

(2)通过代码对结果进行筛选和转换

处理大型数据集时，Agent可以在返回结果之前，通过代码对结果进行筛选和转换。例如，考虑获取一个包含 10,000 行的电子表格：

// Without code execution - all rows flow through contextTOOL CALL: gdrive.getSheet(sheetId: 'abc123')        → returns 10,000 rows in context to filter manually// With code execution - filter in the execution environmentconst allRows = await gdrive.getSheet({ sheetId: 'abc123' });const pendingOrders = allRows.filter(row =>   row["Status"] === 'pending');console.log(`Found ${pendingOrders.length} pending orders`);console.log(pendingOrders.slice(0, 5)); // Only log first 5 for review

agent程序看到的是 5 行而不是 10,000 行。类似的模式也适用于聚合、跨多个数据源的连接或提取特定字段——所有这些都不会使上下文窗口膨胀。

循环、条件语句和错误处理都可以使用熟悉的模式来实现，而无需逐个调用工具。例如，如果您需要在 Slack 中发送部署通知，agent可以这样编写：

let found = false;while (!found) {  const messages = await slack.getChannelHistory({ channel: 'C123456' });  found = messages.some(m => m.text.includes('deployment complete'));  if (!found) await new Promise(r => setTimeout(r, 5000));}console.log('Deployment notification received');

这种方法比在agent循环中交替调用 MCP 工具和sleep命令更有效。

(3)函数复用与Skill

agent还可以将自己的代码保存为可重用的函数。一旦agent为某个任务开发出可用的代码，它就可以保存该实现以供将来使用：

和voyager论文（agent玩Minecraft）那个一样的理念。

这与Skill的概念密切相关。“Skill”文件夹包含可重用的指令、脚本和资源，供模型用于提升特定任务的性能。在这些已保存的函数中添加 SKILL.md 文件，即可创建一个结构化的技能，供模型参考和使用。随着时间的推移，这将使您的agent能够构建一个包含更高级别功能的工具包，并不断完善其高效运行所需的框架。

请注意，代码执行本身会带来复杂性。运行Agent生成的代码需要一个安全的执行环境，并配备适当的sandbox、资源限制和监控机制。这些基础设施要求会增加运维开销和安全方面的考量，而直接调用工具则可以避免这些开销。

代码执行的优势——降低token成本、减少延迟和改进工具组合——应该与这些实现成本进行权衡。

Advanced Tool Use

Introducing advanced tool use on the Claude Developer Platform

www.anthropic.com/engineering/advanced-tool-use

本文介绍了三种辅助工具使用的能力（其实也是工具）

**工具搜索工具，**允许 Claude 使用搜索工具访问数千种工具，而无需占用上下文窗口。

程序化工具调用允许 Claude 在代码执行环境中调用工具，从而减少对模型上下文窗口的影响

工具使用示例，为演示如何有效使用特定工具提供了一个通用标准。

1. 工具搜索工具（Tool Search Tool）

工具搜索工具不会预先加载所有工具定义，而是按需发现工具。Claude 只会看到当前任务实际需要的工具。

工具搜索工具允许 Claude 动态发现工具，而无需预先加载所有定义。您需要向 API 提供所有工具定义，但要将工具标记为defer_loading: true，以便按需发现它们。延迟加载的工具最初不会加载到 Claude 的上下文中。Claude 只能看到工具搜索工具本身以及所有defer_loading: false工具(您最关键、最常用的工具)。

例如，如果 Claude 需要与 GitHub 交互，它会搜索“github”，但只会加载github.createPullRequest和github.listIssues，而不会加载来自 Slack、Jira 和 Google Drive 的其他 50 多个工具。

与任何架构决策一样，启用工具搜索功能也需要权衡利弊。该功能会在工具调用前增加一个搜索步骤，因此，当上下文节省和准确性提升带来的收益超过额外延迟时，它才能带来最佳的投资回报率。

2. 程序化工具调用(Programmatic Tool Calling)

Claude 不会将每个工具的Response都返回给 Claude，而是编写一个 Python 脚本来协调整个工作流程。该脚本在代码执行工具（一个沙盒环境）中运行，并在需要工具结果时暂停。当您通过 API 返回工具结果时，这些结果会由脚本处理，而不是被模型使用。脚本会继续执行，而 Claude 只能看到最终的输出。

适用场景：

处理大型数据集，而您只需要聚合或汇总结果
运行包含三个或更多依赖工具调用的多步骤工作流
在Claude看到结果之前，对工具结果进行筛选、排序或转换。
处理那些中间数据不应影响Claude推理的任务
对多个项目执行并行操作（例如，检查 50 个endpoint）

以下场景效果较差：

进行简单的单工具调用
Claude处理一些要求他能够看到并推断所有中间结果的任务。
快速查找，response较小

3. 工具使用示例（Tool Use Examples）

工具使用示例允许您直接在工具定义中提供示例工具调用。无需仅依赖schema，就能向 Claude 展示具体的用法。（下面的input_examples）

{    "name": "create_ticket",    "input_schema": { /* same schema as above */ },    "input_examples": [      {        "title": "Login page returns 500 error",        "priority": "critical",        "labels": ["bug", "authentication", "production"],        "reporter": {          "id": "USR-12345",          "name": "Jane Smith",          "contact": {            "email": "jane@acme.com",            "phone": "+1-555-0123"          }        },        "due_date": "2024-11-06",        "escalation": {          "level": 2,          "notify_manager": true,          "sla_hours": 4        }      },      {        "title": "Add dark mode support",        "labels": ["feature-request", "ui"],        "reporter": {          "id": "USR-67890",          "name": "Alex Chen"        }      },      {        "title": "Update API documentation"      }    ]  }
``````plaintext
从这个例子中，Claude学到了：

格式规范:日期采用 YYYY-MM-DD 格式，用户 ID 采用 USR-XXXXX 格式，标签采用 kebab-case 格式。
嵌套结构模式:如何构建带有嵌套联系人对象的报告者对象
可选参数关联:Critical bugs包含完整的联系信息和升级机制，并有严格的服务级别协议 (SLA)；feature requests包含报告人信息，但没有联系方式/升级机制；internal tasks仅包含标题。

在Anthropic自己的内部测试中，工具使用示例将复杂参数处理的准确率从 72% 提高到 90%。

Effective harnesses for

long-running agents

Effective harnesses for long-running agents

www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

随着AI Agent能力的不断提升，开发者们越来越多地要求它们承担复杂的任务，这些复杂任务可能需要数小时甚至数天才能完成。然而，如何让Agent在多个上下文窗口中持续取得进展仍然是一个尚未解决的问题。

感觉这是只有code agent需要迫切面对的问题，第一个会话写了一部分代码，第二个会话需要把之前进度续上。

长时间运行的agent面临的核心挑战在于，它们必须在离散的会话中工作，每个新会话开始时都对之前的工作一无所知。想象一下，一个软件项目由工程师轮班工作，每个新工程师都对上一班的工作内容毫无记忆。由于上下文窗口有限，而且大多数复杂项目无法在单个窗口内完成，agent需要一种方法来弥合会话之间的空白。

我们开发了一套双重解决方案，使Claude Agent SDK能够在多个上下文窗口中高效运行：一个initializer agent，用于在首次运行时设置环境；以及一个coding agent，负责在每个会话中逐步推进，同时为下一个会话留下清晰的痕迹。

1. 长时间运行的agent的问题

Claude的失败主要体现在两个方面。首先，agent倾向于一次性执行过多操作——本质上是试图一次性完成整个应用程序。这通常会导致模型在执行过程中失去上下文，使得下一个会话开始时，某个功能只实现了一半，而且没有文档说明。agent随后不得不猜测发生了什么，并花费大量时间试图让应用程序的基本功能重新运行。

即使使用了压缩（compact)机制，这种情况仍然会发生，因为压缩机制并非总是能将清晰明确的指令传递给下一个agent。

第二种故障模式通常会在项目后期出现。在某些功能已经构建完成后，后续的agent实例会检查项目进展，发现已经取得了一些进展，然后宣布任务完成。

作者将问题分解为两部分。首先，需要搭建一个初始环境，为给定提示所需的所有功能奠定基础，使agent能够逐步、逐个功能地完成任务。其次，应该引导每个agent逐步实现其目标，同时在会话结束时将环境清理干净。所谓“清理干净”的状态，是指代码适合合并到主分支：没有重大错误，代码结构清晰、文档齐全，通常情况下，开发人员可以轻松地开始开发新功能，而无需先清理无关的混乱代码。

initializer agent：第一个agent会话使用一个特殊的提示符，要求模型设置初始环境：一个init.sh脚本、一个 claude-progress.txt 文件（用于记录Agent执行的操作）以及一个初始 git 提交（用于显示已添加的文件）。
coding agent：后续每个会话都要求模型取得增量进展，然后留下结构化的更新信息

关键在于找到一种方法，让agent在打开一个全新的上下文窗口时能够快速了解工作状态，这可以通过 claude-progress.txt 文件以及 Git 历史记录来实现。这些实践的灵感来源于了解高效软件工程师的日常工作。

2. 环境管理

为了解决agent一次性写完一个app或过早认为项目已完成的问题，我们要求初始化initializer agent编写一份全面的功能需求文件，以扩展用户的初始prompt。在实践中，可能分解超过200个功能点，这些功能点最初都被标记为“未完成”，以便后续的coding agent程序能够清楚地了解完整功能应有的样子。

Plan-And-Execute里的Plan?用Plan Agent生成初始的todo和准备环境？

一个例子：

{    "category": "functional",    "description": "New chat button creates a fresh conversation",    "steps": [      "Navigate to main interface",      "Click the 'New Chat' button",      "Verify a new conversation is created",      "Check that chat area shows welcome state",      "Verify conversation appears in sidebar"    ],    "passes": false  }

仅通过更改passes字段的状态(true/false)来引导coding agent编辑此文件。

并使用措辞强烈的指令，例如“删除或编辑测试是不可接受的，因为这可能导致功能缺失或出现错误”。经过一些实验，我们最终决定使用 JSON 格式，因为与 Markdown 文件相比，模型不太可能错误地更改或覆盖 JSON 文件。

3. 渐进式进展

在搭建好初始环境框架后，下一轮codingagent被要求每次只处理一个功能。这种增量式方法对于解决agent一次性处理过多任务的倾向至关重要。

即使采用增量式开发，模型在每次代码更改后保持环境的xlean状态仍然至关重要。在实验中，作者发现实现这一目标的最佳方法是要求模型使用描述性的提交信息将其开发进度提交到 Git，并在进度文件中写入进度摘要。这样，模型就可以使用 Git 回滚错误的代码更改，并恢复代码库的正常状态。

4. 测试

我们观察到的最后一个重要BUG是Claude倾向于在没有进行充分测试的情况下将某个功能标记为已完成。如果没有人类的明确提醒，Claude往往会修改代码，甚至使用单元测试或curl命令在开发服务器上进行测试，但他却无法意识到该功能并未全面正常运行。

在构建 Web 应用程序的过程中，一旦明确要求 Claude 使用浏览器自动化工具并像人类用户一样进行所有测试，Claude 在端到端验证功能方面大多表现良好。

为 Claude 提供这类测试工具显著提高了性能，因为agent能够识别并修复仅从代码中无法明显看出的错误。

5. 会话初始化信息

某些操作对于agent快速进入状态很有帮助，这是每个agent都应该做的，比如

运行 pwd 查看当前工作目录。您只能编辑此目录中的文件。
阅读 git 日志和进度文件，了解最近的工作进展。
阅读功能列表文件，选择尚未完成的最高优先级功能进行开发。

一个典型的会话开始时会显示以下助手消息：

[Assistant] I'll start by getting my bearings and understanding the current state of the project.[Tool Use] <bash - pwd>[Tool Use] <read - claude-progress.txt>[Tool Use] <read - feature_list.json>[Assistant] Let me check the git log to see recent work.[Tool Use] <bash - git log --oneline -20>[Assistant] Now let me check if there's an init.sh script to restart the servers.<Starts the development server>[Assistant] Excellent! Now let me navigate to the application and verify that some fundamental features are still working.<Tests basic functionality>[Assistant] Based on my verification testing, I can see that the fundamental functionality is working well. The core chat features, theme switching, conversation loading, and error handling are all functioning correctly. Now let me review the tests.json file more comprehensively to understand what needs to be implemented next.

写在最后

可以看出，与之前的文章相比，Claude在近期的文章都体现了他们对于通用Agent的野心。

Claude在近期的文章中反复提到一点：很好地把文件系统环境与Agent结合在了一起，让Agent自己探索和发现需要做的事情，而无需一次加载所有Prompt和Tool.（Skills, Advance Tool Use)

Anthropic显然认为自己的架构是强大而灵活的，并积极将这一架构扩展到更多领域，我也认为如此。