---
title: "从 0 到 1 的 Agent 工程:基于 Claude Code 与 OpenAI Agents SDK 的技术地图与实战教程"
description: "梳理 agent 工程的技术演进(Prompt→RAG→Tool Use→ReAct→Workflows→Agents→上下文工程),教你手写 the loop 并用 OpenAI Agents SDK / Claude Agent SDK / LangGraph 从零搭建,并给出一套「按场景挑组件:哪些必备、哪些锦上添花」的选型决策框架,附 2026 最新技术(code execution with MCP、computer use、A2A、RL for agents)。"
pubDate: 2026-07-17
tags: ["Agent","LLM","Claude Code","OpenAI Agents SDK","上下文工程","MCP","多Agent"]
category: "AI工程"
lang: "zh"
math: false
---
# 从 0 到 1 的 Agent 工程:一份基于 Claude Code 与 OpenAI Agents SDK 的技术地图与实战教程

> 这篇文章想做三件事:**梳理 agent 工程的技术演进脉络**、**教你从零搭出一个能用的 agent**、并给出一套**"按场景挑组件"的选型决策框架**——哪些是必备地基,哪些是锦上添花。所有关键结论都尽量对齐到一手来源(Anthropic 工程博客、OpenAI / LangGraph 官方文档),文末附引用。

---

## 0. 先给结论:一句话看懂 agent

Anthropic 在《Building effective agents》里把 agent 收敛成一句定义:

> **Agent = LLM 在一个循环里自主地使用工具(LLMs autonomously using tools in a loop)。**

这句话是整篇文章的锚点。它同时告诉你三件事:

1. **核心是一个循环(loop)**,不是一次调用;
2. **循环里模型自己决定下一步做什么**(而不是你写死流程);
3. **模型通过"工具"与外部世界交互**,并根据工具返回的结果修正自己。

围绕这个循环长出来的所有东西——工具、上下文管理、记忆、子 agent、护栏、评测——就是"agent 工程"。下面我们先看它是怎么一步步演化成今天这样的。

---

## 1. 技术发展路径:从 Prompt 到 Agent 的六级台阶

理解"为什么是现在这样",比记住 API 更重要。这条路径大致是:

| 阶段 | 形态 | 解决的问题 | 遗留的问题 |
|---|---|---|---|
| ① Prompt Engineering | 一次性写好指令 | 让模型听话 | 知识过时、不能行动 |
| ② RAG(检索增强) | 检索 + 拼进上下文 | 补充私有/实时知识 | 索引会过时、检索不精准 |
| ③ Tool Use(函数调用) | 模型输出结构化调用 | 让模型能"行动" | 单步,不会规划 |
| ④ ReAct / 推理循环 | 思考→行动→观察 循环 | 多步推理 + 用环境反馈纠错 | 上下文会爆、会跑偏 |
| ⑤ Workflows(编排) | 用代码把 LLM 串成固定流程 | 可控、可预测、便宜 | 不够灵活,处理不了开放问题 |
| ⑥ Agents(自主) | 模型自己决定流程 | 开放式、长程任务 | 成本/延迟高、错误会累积 |

**关键分水岭在 ⑤ 和 ⑥ 之间**,Anthropic 给了一个精确区分:

- **Workflow(工作流)**:*LLM 和工具被"预定义的代码路径"编排*。流程是你写死的,模型只在节点里干活。
- **Agent(智能体)**:*LLM 动态地指挥自己的流程和工具使用,自己掌控如何完成任务*。

> ⚠️ **最重要的一条工程忠告**(来自 Anthropic):"找到最简单的解法,只在必要时才增加复杂度。这甚至可能意味着——根本不要构建 agent 系统。" 对很多应用,"用检索 + 示例优化单次 LLM 调用" 就够了。Agent 用性能换取了延迟和成本,不要为了炫技上 agent。

到了 2025-2026,行业的重心又从 ④⑤⑥ 的"编排"进一步下沉到一个新词:**上下文工程(Context Engineering)**——因为大家发现,决定 agent 成败的往往不是流程多聪明,而是**每一步喂给模型的那些 token 到底对不对**。这是第 4 节的主题。

---

## 2. 核心心智模型:The Loop(把循环拆开看)

不管你用哪个框架,agent 的引擎都是同一个循环。以 OpenAI Agents SDK 的 `Runner` 循环为例,它是最干净的教科书式描述:

1. 用当前输入调用 LLM;
2. 如果 LLM 产出了 **final output**(符合类型要求的文本、且没有工具调用)→ 结束,返回结果;
3. 如果 LLM 做了 **handoff**(转交给另一个 agent)→ 切换当前 agent,回到第 1 步;
4. 如果 LLM 产生了 **工具调用** → 执行工具、把结果追加进上下文、回到第 1 步;
5. 如果超过 `max_turns` → 抛异常。

Claude Code 用另一套语言描述同一件事——它把每一轮叫作 **turn**,并强调:"turn 会一直继续,**直到模型产出一个不含任何工具调用的回复**为止"。它把整个循环概括成三个交融的阶段:

> **收集上下文(gather context)→ 采取行动(take action)→ 验证结果(verify results)**,循环往复,直到任务完成。

用 ~15 行伪代码,你就能看清这个引擎(这也是"手写一个 agent"的本质):

```python
def run_agent(user_input, tools, system_prompt):
    messages = [system_prompt, user_input]
    while True:
        response = llm.call(messages, tools=tools)      # ①收集+推理
        messages.append(response)
        if not response.tool_calls:                      # ②没有工具调用→结束
            return response.text
        for call in response.tool_calls:                 # ③执行工具(行动)
            result = execute(call)
            messages.append(tool_result(call, result))   # 把结果喂回去(验证/反馈)
        # loop 继续,模型基于新结果决定下一步
```

**你会发现:所谓"框架",本质都是在这个 while 循环外面包装了不同的能力**——OpenAI Agents SDK 帮你管 handoff/session/guardrail;Claude Code(Agent SDK)帮你管上下文压缩、子 agent、权限;LangGraph 把循环显式画成状态图。理解了这一层,你看任何框架都是"换皮"。

---

## 3. 主线:从 0 到 1 搭一个能用的 Agent

这一节给你三条可直接抄的路径,从"纯手写"到"用生产级 SDK"。

### 3.1 地基:Augmented LLM(增强型 LLM)

Anthropic 把 agent 的最小构件叫 **augmented LLM** = 一个 LLM + **检索 + 工具 + 记忆**。在你上任何框架之前,先确认这三样各自能独立跑通、能被模型正确调用。**先直连 LLM API 手写循环,再考虑框架**——这是官方明确建议,因为框架会把底层 prompt 藏起来,新手容易连"到底发生了什么"都看不清。

### 3.2 路径 A:OpenAI Agents SDK(最轻量,最好上手)

设计哲学:*"够用的功能,但原语少到能快速学会"* + *"Python 优先——用语言本身来编排,而不是逼你学一堆新抽象"*。它只有一小把原语:**Agents / Handoffs / Guardrails / Sessions / Tools / Runner / Tracing**。

最小可用例子:

```python
from agents import Agent, Runner, function_tool

@function_tool                       # 任意 Python 函数 → 工具,自动生成 schema
def get_weather(city: str) -> str:
    return f"{city}: 晴, 26°C"

agent = Agent(
    name="assistant",
    instructions="你是一个简洁的助理,需要时调用工具。",
    tools=[get_weather],
)

result = Runner.run_sync(agent, "北京天气怎么样?")
print(result.final_output)
```

加一个**多 agent 转交(handoff)**——注意:handoff 在 SDK 里就是"以工具形式暴露给模型"的,模型自己决定要不要转交:

```python
zh_agent = Agent(name="zh", instructions="只用中文回答")
en_agent = Agent(name="en", instructions="Reply only in English")
triage = Agent(
    name="triage",
    instructions="根据用户语言,转交给对应 agent。",
    handoffs=[zh_agent, en_agent],   # 生成 transfer_to_zh / transfer_to_en 工具
)
```

再加**会话记忆(Sessions)**,自动跨轮维护历史,不用手动拼 `to_input_list()`:

```python
from agents import SQLiteSession
session = SQLiteSession("user-123")
Runner.run_sync(triage, "我叫小明", session=session)
Runner.run_sync(triage, "我叫什么?", session=session)  # 自动记得
```

**Responses API vs Chat Completions**:OpenAI 自家应用推荐走 **Responses API**(有状态,服务端用 `previous_response_id` 串多轮,还能跨工具轮持久化 reasoning 推理项,更省 token,并内置 web search / file search / computer use 等服务端工具)。Chat Completions 是无状态的,每轮你自己重发全部历史。

### 3.3 路径 B:Claude Agent SDK(把 Claude Code 当库用)

如果你要的是"**开箱即带一整套编码/研究 harness**"——内置 Read/Edit/Write/Bash/Grep/Glob/WebSearch、自动上下文压缩、子 agent、权限系统——那就用 Claude Agent SDK(原 Claude Code SDK)。它的定位就是:*"把 Claude Code 当作库,拿到驱动 Claude Code 的同一套工具、agent 循环和上下文管理,可在 Python / TS 里编程调用"*。

它和"自己写工具循环"的本质区别:

> **用 Client SDK(裸 API),你自己实现工具循环;用 Agent SDK,Claude 帮你把循环跑完。**

```python
# Python: claude-agent-sdk
from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="修复 auth.py 里的登录 bug 并跑测试",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash", "Grep"],
        permission_mode="acceptEdits",   # 自动批准文件编辑
        max_turns=30,
    ),
):
    print(message)
```

它的循环终点是一个 `ResultMessage`,带 `total_cost_usd`、`usage`、`num_turns`——生产级可观测性直接给你。控制旋钮:`max_turns`(只数工具轮)、`max_budget_usd`(成本上限)、`effort`(推理力度 low→max)、`permission_mode`(权限模式)。

### 3.4 路径 C:LangGraph(要显式控制流程/状态机时)

当你的流程需要**显式的图、可持久化的状态、断点续跑、人在环(human-in-the-loop)、时间旅行**,选 LangGraph。它自我定位是"底层编排运行时",而不是帮你藏 prompt:*"LangGraph 不抽象 prompt 也不抽象架构。"* 核心对象:`StateGraph` + 节点 + 边(含条件边)+ `.compile()`;状态用带 **reducer** 的 typed dict 合并;`checkpointer` 提供线程级短期记忆 + 断点续跑,`store` 提供跨线程长期记忆。执行模型借鉴了 Google Pregel 的"超步(super-step)"消息传递。

**一句话选型**:轻量任务/多 agent 转交 → OpenAI Agents SDK;编码/文件系统类 harness → Claude Agent SDK;长程、需强控制和持久化的状态机 → LangGraph。

---

## 4. 各方向细节(一):上下文工程 —— 2025 年最重要的范式转移

这是整篇文章我最想让你记住的一节。Anthropic 在《Effective context engineering》里把它定义为:

> **Context engineering = 在推理的每一步,策划(curate)并维护那组"最优 token 集合"的策略。** 它是 prompt engineering 的自然延续,但 prompt 是一次性写好,context engineering 是**每一步都要重新决定喂什么进去**。

### 4.1 为什么重要:上下文腐烂 与 注意力预算

两个必须记住的一手术语:

- **上下文腐烂(Context Rot)**:*随着上下文 token 数增加,模型从中准确召回信息的能力会下降。* 这在所有模型上都会出现。
- **注意力预算(Attention Budget)**:模型有一份有限的"注意力预算",每多一个 token 就消耗一点。根源是架构性的——注意力是 n 个 token 之间的 n² 两两关系,而训练数据里长序列偏少。

由此得到**上下文工程的第一性原理**:

> **找到能最大化预期结果概率的、最小的高信号 token 集合。**
> (Find the smallest possible set of high-signal tokens that maximize the likelihood of the desired outcome.)

注意:*"最小"不等于"最短"*——该给的背景和示例还是要给,只是不能塞垃圾。

### 4.2 有效上下文的解剖

- **System prompt 要在"正确的海拔"**:避开两个极端——把复杂脆弱的 if-else 逻辑写死(太低),或只给含糊的高层指导(太高),落在中间的"金发姑娘区(Goldilocks zone)"。用 `<background>`、`<instructions>`、`## Tool guidance`、`## Output` 等 XML/Markdown 分区。
- **工具要 token 高效、自洽、边界清晰**。反模式:臃肿、功能重叠的工具集。*"如果一个人类工程师都没法明确说出某个场景该用哪个工具,你不能指望 AI agent 做得更好。"*
- **示例(few-shot)给"经典、多样"的少数几个**,别堆一长串边角案例。"示例是胜过千言的图画。"

### 4.3 长程任务的三板斧(超出单个上下文窗口怎么办)

| 技术 | 做法 | 适用 |
|---|---|---|
| **压缩(Compaction)** | 对话接近窗口上限时,总结历史、用摘要重开一个新窗口。Claude Code 会保留"架构决策、未解决的 bug、实现细节",丢弃冗余工具输出,并带上**最近访问的 5 个文件**。最轻量的形式是 **tool-result clearing**(清掉历史里早已用过的工具原始返回)。 | 需要大量来回的任务 |
| **结构化笔记 / 智能体记忆(Structured note-taking)** | agent 把笔记持久化到上下文之外(如 `NOTES.md`、to-do 列表),需要时再读回。经典例子:Claude 玩宝可梦,跨数千步维护计数,context reset 后读回笔记继续。 | 有明确里程碑的迭代开发 |
| **子 agent 上下文隔离(Sub-agent)** | 专职子 agent 各自用干净的上下文窗口深挖(可能烧几万 token),**只把 1000–2000 token 的蒸馏结论返回给主 agent**。 | 复杂研究、可并行探索 |

### 4.4 即时检索(Just-in-time)vs 预检索(RAG)

新趋势是**用"轻量标识符 + 运行时按需加载"取代"预先embedding检索"**:agent 手里只攥着文件路径、查询、链接这类标识符,用工具在运行时动态把数据拉进上下文。这更像人的认知(你不会背下整个文件柜,而是靠标签现找)。它靠元数据(目录层级、命名、时间戳)做信号,支持**渐进式披露(progressive disclosure)**——通过探索逐步发现相关上下文。

**Claude Code 是个混合体的范例**:`CLAUDE.md` 一开始就朴素地塞进上下文(预加载),而 `glob`/`grep` 让它在运行时即时检索文件——**从而绕开了索引会过时的问题**。这个"预加载少量高价值 + 运行时按需捞"的混合策略,是当前最实用的默认解。

---

## 5. 各方向细节(二):工具设计 —— agent 的"手"

工具是 agent 唯一能改变世界的通道,Anthropic 专门写了《Writing effective tools for agents》。核心观点:

> **工具是一种新型软件,是"确定性系统"与"非确定性 agent"之间的契约。** 要为 agent 设计,而不是照搬给开发者用的 API。

五条原则:(1) 挑对要做的工具(以及不做哪些);(2) 用**命名空间**划清功能边界;(3) 给 agent 返回**有意义的上下文**;(4) 响应要 **token 高效**;(5) 认真给工具描述做 prompt engineering。

几个可落地的要点:
- **错误信息就是反馈**:让工具在失败时返回清晰、可操作的错误,agent 往往能自己纠正。Anthropic 让一个"工具测试 agent"去用有缺陷的工具、再改写工具描述,使后续 agent **任务完成时间下降 40%**。
- **工具格式工程**:有些格式对模型天然更难(如 diff 要先知道行数,代码塞进 JSON 要转义)。优先用"最接近模型在训练中见过的自然形态"的格式,并给模型足够 token 去思考。
- **并行安全**:只读工具(Read/Grep/Glob)可并发;改状态的工具(Edit/Write/Bash)要串行。设计工具时用 `readOnlyHint` 之类标注声明只读性。

---

## 6. 各方向细节(三):记忆系统

一个清晰的分层(源自 Lilian Weng 的经典 agent 综述 + Anthropic 生产实践):

- **短期 / 工作记忆** ≈ **上下文内学习(in-context learning)**,受窗口大小限制;
- **长期记忆** ≈ agent 可在查询时读取的**外部存储**。长期记忆又分:
  - **情景记忆(episodic)**:发生过的事、经历;
  - **语义记忆(semantic)**:事实、概念;
  - **程序性记忆(procedural)**:技能、惯例。

**2025 的重要转向**:从"纯向量检索(embedding + 向量库 + ANN)"转向**结构化/文件型记忆**(Anthropic 的 `memory` 工具、`NOTES.md` 便签)。结构化记忆的优势:**可读、可编辑、用文件系统语义(路径/命名/时间戳)当信号**,而不是不透明的向量相似度。

Claude Code 的记忆是两套并行、每次会话启动都加载:
- **`CLAUDE.md`**:你写的规则/指令(项目/用户/组织级);
- **自动记忆(auto memory)**:Claude 自己写的"学到的模式",按仓库持久化。

⚠️ 一条反直觉的关键点:CLAUDE.md 和记忆是**"上下文,不是被强制执行的配置"**。想要"无论模型怎么想都必须拦截 X"的确定性行为,得用 **PreToolUse hook**,而不是写在记忆里祈祷模型遵守。

---

## 7. 各方向细节(四):多 Agent —— 什么时候值得,什么时候是坑

这是最容易被滥用的方向。两篇文章代表两种立场,你必须都看:

### 7.1 支持派:Anthropic 的多 agent 研究系统

采用 **orchestrator-worker(编排者-工人)** 结构:一个 **LeadResearcher** 规划、**把计划存进 Memory 防止上下文超过 20 万 token 被截断**、并行派生多个 **Subagent**(各自独立上下文/工具/轨迹),最后一个 **CitationAgent** 补引用。

硬核数据:
- 多 agent(Opus 4 领导 + Sonnet 4 工人)在内部研究评测上**比单 agent Opus 4 高 90.2%**;
- 在 BrowseComp 上,**三个因素解释了 95% 的性能方差,其中光 token 用量就解释了 80%**。结论振聋发聩:*"多 agent 系统之所以有效,主要是因为它们帮忙花掉了足够多的 token。"*
- **成本**:agent 大约比聊天多烧 4× token,**多 agent 多烧约 15×**。所以只在"任务价值高到能付得起"时才用。

**适合多 agent**:广度优先、多个独立方向、信息量超过单窗口、要用很多复杂工具的场景(典型:研究/检索)。

### 7.2 反对派:Cognition《Don't Build Multi-Agents》

核心论点两条:**(1) 共享上下文**——要共享完整的 agent 轨迹,而不是零散消息;**(2) 行动隐含决策**——独立并行跑的子 agent 看不到彼此的上下文,它们各自做出的隐含决策会互相冲突,导致结果不一致、不连贯。因此对**写密集/编码类**任务(高相互依赖、易冲突),更推荐**单线程线性 agent**;上下文太长就用一个(可微调的)专用模型做**上下文压缩**。

### 7.3 怎么调和

一句话记忆:**读密集、可并行、低相互依赖 → 多 agent 划算;写密集、强相互依赖(尤其编码)→ 单线程更稳。** Anthropic 自己也承认:"多数编码任务里可真正并行的部分,比研究任务少得多,而且 agent 目前还不擅长实时协调和委派。"

---

## 8. 各方向细节(五):Hooks、护栏、权限、评测、可靠性

这些是让 agent 从"demo"走到"生产"的部分。

### 8.1 Hooks / Guardrails(拦截与校验)
- **Claude Code Hooks**:在生命周期特定点自动触发的用户自定义逻辑(shell / HTTP / LLM prompt),事件覆盖 `PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop`、`SessionStart/End` 等。关键:**hooks 跑在你的应用进程里,不进模型上下文窗口,因此不消耗 context**;`PreToolUse` 返回 `deny` 可直接阻断某次工具调用。这是实现"确定性拦截"的正道。
- **OpenAI Guardrails**:分**输入护栏**(只在首个 agent 上跑)和**输出护栏**(只在末个 agent 上跑),与 agent **并行**运行,命中 tripwire 就抛异常中断。设计意图很实际:用**便宜的小模型当护栏**去挡**贵的大模型**,省时省钱。

### 8.2 权限模型(以 Claude Code 为例)
三层叠加:`allowedTools`(白名单自动批准)、`disallowedTools`(硬阻断)、`permission_mode`(管没被规则覆盖的部分)。模式:`default`(询问)、`acceptEdits`(自动批准编辑)、`plan`(只探索不改)、`dontAsk`、`bypassPermissions`(全放行,危险)。外部副作用(如网络请求)无法被 checkpoint 回滚,所以这类默认要问。

### 8.3 评测(Evaluation)—— 别等完美才开始
- **立刻用小样本开始**:早期一个 prompt 微调可能把成功率从 30% 拉到 80%,**~20 个代表性 query 就够看出效果**。别信"必须几百个测试用例才有用"。
- **轨迹不可比**:agent 非确定性,同一起点可能走不同的合法路径,所以**评"结果 + 过程是否合理",而不是"是否走了标准步骤"**。
- **LLM-as-judge**:单个 LLM、单条 rubric、输出 0.0–1.0 分 + 通过/否,是最一致、最贴合人类判断的做法(评维度:事实准确性、引用准确性、完整性、来源质量、工具效率)。
- **人工评测抓 edge case**:人能发现评测漏掉的边角(幻觉、来源偏好偏差等)。

### 8.4 可靠性(生产)
> "最后一公里往往才是大部分路程。微小改动会级联成巨大行为变化。"

- **agent 有状态、错误会累积**——用**持久化执行 + 从失败点续跑(而非重启)+ 重试 + 定期 checkpoint**。
- **可观测性**:全链路 tracing(可只记决策模式、不读对话内容以保护隐私)。
- **部署**:agent 是"几乎持续运行的有状态网络",用**彩虹部署(rainbow deployment)**逐步切流量,别打断在途 agent。

---

## 9. 核心章节:按场景挑组件 —— 哪些必备,哪些锦上添花

这是全文最实用的部分。先给一个**通用的分层清单**,再给**场景 × 组件对照表**。

### 9.1 组件分层:地基 / 骨架 / 增强

**🔴 必备地基(没有它 agent 跑不起来)**
1. **一个明确的循环 + 终止条件**(`max_turns` / 预算上限)——防止无限循环和成本失控;
2. **System prompt 在正确海拔**——任务定义 + 边界 + 输出格式;
3. **一组最小、边界清晰的工具**——先只给完成任务真正需要的;
4. **基本的上下文管理**——至少要有"上下文会满怎么办"的答案(压缩或清理工具结果);
5. **错误处理**——工具失败要返回可操作的错误信息喂回模型。

**🟡 骨架(决定 agent 能不能上生产)**
6. **会话/记忆**——多轮场景必须有(短期);跨会话才需要长期记忆;
7. **权限 / 护栏 / 人在环**——只要 agent 能执行有副作用的动作(写文件、发请求、花钱),就必须有;
8. **评测集 + tracing**——想持续改进就必须有,越早越好(20 条起步);
9. **重试 / checkpoint / 持久化**——长程或高价值任务必备。

**🟢 锦上添花(特定场景才划算)**
10. **多 agent / 子 agent**——只在"读密集 + 可并行 + 值得烧 15× token"时;
11. **即时检索 / 结构化记忆 / 笔记**——长程、超窗口任务才需要;
12. **MCP 接入**——要复用大量外部工具/数据源时;
13. **Handoff / 路由**——有清晰可分类的多专家场景;
14. **Evaluator-optimizer 循环**——有明确评价标准且迭代能显著提质时(如翻译、代码)。

### 9.2 场景 × 组件对照表

| 场景 | 推荐骨架(Anthropic 模式) | 必备组件 | 锦上添花 | 通常**不要**上 |
|---|---|---|---|---|
| **客服 / FAQ 问答** | 单次 LLM + 检索;复杂再上 Routing | System prompt、检索、输出护栏 | 会话记忆、升级到人工的 handoff | 多 agent、长期记忆 |
| **内容分类 / 打标** | Routing(路由) | 分类 prompt、结构化输出 | 便宜模型分流(Haiku 处理简单、Sonnet 处理难) | agent 循环(根本不需要) |
| **固定多步处理(如"翻译→校对→润色")** | Prompt chaining + gate 校验 | 链式步骤、中间校验 | evaluator-optimizer | 自主 agent |
| **编码 agent(改多文件、修 bug)** | 自主 agent 循环(单线程) | 文件工具(Read/Edit/Grep/Bash)、权限、测试作为验证器、checkpoint | 上下文压缩、子 agent 做只读探索 | **并行多 agent 写代码**(易冲突) |
| **深度研究 / 竞品调研** | Orchestrator-workers 多 agent | 领导 agent + 并行只读子 agent、引用 agent、web 工具 | 结构化笔记、压缩 | 强一致性要求的写操作 |
| **数据分析 / 报表** | 自主 agent + 代码执行 | 代码执行工具(sandbox)、结构化输出 | 即时检索(大数据集在环境里过滤) | 多 agent |
| **GUI / 电脑操作自动化** | 自主 agent(computer use) | 截图+鼠标键盘工具、强护栏、人在环、sandbox | checkpoint、彩虹部署 | 无护栏放飞 |
| **长程任务(数小时,代码迁移)** | 单线程 + 记忆 | 压缩、结构化笔记(NOTES.md)、从失败点续跑 | 子 agent 做局部探索 | 一把梭塞进单窗口 |

### 9.3 三个决策问题(选组件时反复问自己)
1. **这真的需要 agent 吗?** 能用"单次 LLM + 检索 + 示例"解决,就别上循环。能用固定 workflow,就别上自主 agent。
2. **这一步真的需要多 agent 吗?** 问:子任务能并行吗?相互依赖强吗?值得烧 15× token 吗?——三个"是"才上。写密集任务默认单线程。
3. **这个组件是在减小上下文还是在增加噪声?** 上下文工程第一性原理:每加一个东西(工具、示例、记忆、MCP server),都在花注意力预算。加之前先算这笔账。

---

## 10. 最新技术(2026):你现在应该知道的前沿

### 10.1 Code Execution with MCP(工具即代码)—— 省 token 的杀手锏
2025 年 11 月 Anthropic 提出:当你接入几百个 MCP 工具时,两个问题会炸上下文——(1) 工具定义本身就吃掉几十万 token;(2) 中间结果反复穿过模型。解法是**把 MCP server 表示成文件系统上的代码 API(一个工具一个文件),让 agent 写代码来调用**:
- **渐进式披露**:agent 先 `ls ./servers/`,只读它需要的工具文件;
- **结果在执行环境里先过滤/变换再返回**(如在代码里过滤一万行表格);
- **头条数据:token 从 150,000 降到 2,000,省了 98.7%**。Cloudflare 的同类做法叫 "Code Mode"。

这标志着一个趋势:**从"把工具塞进上下文"转向"把工具当代码库,让 agent 现用现取"**。

### 10.2 Computer Use / GUI Agent
让模型通过截图 + 鼠标键盘直接操作电脑/浏览器,做通用 GUI 任务。是"自主 agent"的标志性用例,也是护栏和 sandbox 最不能省的场景。

### 10.3 编码 agent 与 SWE-bench
编码被公认是 agent 的理想领域——**结果可被自动化测试客观验证**。SWE-bench Verified(直接从 PR 描述解真实 GitHub issue)是当前主导基准。"用测试结果作为反馈迭代"的**验证器(verifier)模式**是这里的核心可靠性手段。

### 10.4 长程自主(Long-horizon Autonomy)
"跨越长交互保持连贯"是当前中心难题。收敛的解法就是第 4 节三板斧的组合:**压缩 + 结构化记忆 + 子 agent**,把任务撑过固定窗口,支撑"数十分钟到数小时"的任务。

### 10.5 RL for Agents / Rollouts
用"多步工具使用轨迹 + 结果奖励"训练模型。Anthropic 的发现——"token 用量解释 80% 的性能方差"、"模型升级是效率倍增器(Sonnet 4 的收益 > 给 Sonnet 3.7 双倍 token 预算)"——指向:**RL 调过的推理与工具使用,比堆脚手架更是那根真正的杠杆。**

### 10.6 两个标准:MCP 与 A2A
- **MCP(Model Context Protocol)**:AI 应用连接外部系统的开放标准,官方比喻是"AI 应用的 USB-C 口",暴露**工具、资源(数据)、prompts(工作流)**。已被 Claude、ChatGPT、VS Code、Cursor 及主流框架(LangGraph/CrewAI/Pydantic AI/Google ADK/LlamaIndex)广泛采用。**MCP 管"纵向":agent 向下够到工具和数据。**
- **A2A(Agent2Agent)**:让不同框架、不同厂商、不同服务器上的 agent 之间**作为 agent(而非工具)互相通信协作**的开放协议,靠 **Agent Card**(能力发现)+ JSON-RPC 交换任务,现由 Linux Foundation 托管。**A2A 管"横向":agent 之间跨运行时联邦。**

---

## 11. 框架全景速查(选型时扫一眼)

| 框架 | 一句话定位 | 独特点 |
|---|---|---|
| **OpenAI Agents SDK** | 最轻量、原语最少 | Agents/Handoffs/Guardrails/Sessions;Python 优先;Swarm 的生产级继任者 |
| **Claude Agent SDK** | 把 Claude Code 当库 | 自带完整编码 harness、上下文压缩、子 agent、权限 |
| **LangGraph** | 底层编排运行时 | 显式状态图、checkpointer、断点续跑、人在环、时间旅行 |
| **CrewAI** | 编排自主 agent 团队 | Crews(角色协作)+ Flows(事件驱动工作流),独立于 LangChain |
| **AutoGen / AG2** | 微软多 agent 框架 / 社区分叉 | 事件驱动 Core + 对话式 AgentChat;GroupChat 多 agent |
| **LlamaIndex Agents** | 数据/RAG 优先 | 工具可以是完整查询引擎;事件驱动 Workflows |
| **Pydantic AI** | "GenAI 界的 FastAPI" | 全类型安全、依赖注入、Logfire(OTel)追踪 + Evals |
| **Google ADK** | 代码优先、多语言 | 多 agent、Gemini Live、原生 A2A |
| **Mastra** | TypeScript 原生框架 | JS/TS 生态、Agent+Tool+Workflow+RAG+Evals |

**框架都在收敛于同一套模式**:工具调用循环、结构化输出、多 agent 编排(handoff/supervisor/group chat/graph)、记忆分层(短期线程 + 长期跨线程)、流式、评测/追踪。所以**先吃透"循环 + 上下文工程"这层原理,框架只是选型题**。

---

## 12. 一张学习路线图(从 0 到 1 的顺序)

1. **手写 the loop**:直连一个 LLM API,写出第 2 节那 15 行循环,接 1–2 个工具。目标:亲眼看见"模型→工具→喂回→再决策"。
2. **上一个轻量 SDK**:用 OpenAI Agents SDK 复刻上一步,再加 session、加一个 handoff。目标:理解原语。
3. **做上下文工程**:给你的 agent 加压缩策略、把 system prompt 调到正确海拔、砍掉冗余工具。目标:体会"减法"带来的提升。
4. **加护栏 + 评测**:写 20 条评测 query + 一个 LLM-judge,加输入/输出护栏。目标:能量化改进。
5. **按场景做选型**:对照第 9 节的表,决定你的场景要不要记忆、要不要多 agent、要不要 MCP。目标:会做减法与加法的取舍。
6. **上前沿**:需要大量工具就试 code-execution-with-MCP;要跨 agent 协作看 A2A;长程任务上三板斧组合。

---

## 结语

Agent 工程走到 2026,最反直觉也最重要的一课是:**它主要不是"让 agent 更聪明"的工程,而是"精确控制每一步喂进去什么 token"的工程**。循环是引擎,上下文工程是油门和方向盘,工具是手,记忆是笔记本,护栏是刹车,评测是仪表盘。多 agent、MCP、computer use 这些光鲜的东西,都要先过"这真的减小了上下文噪声、值得这份成本吗"这一关。

先把最简单的东西做对,只在必要时增加复杂度——这既是 Anthropic 的第一条忠告,也是这份教程的最后一句话。

---

## 参考来源

**Anthropic 工程博客**
- Building effective agents (2024-12-19): https://www.anthropic.com/engineering/building-effective-agents
- Effective context engineering for AI agents (2025-09-29): https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- How we built our multi-agent research system (2025-06-13): https://www.anthropic.com/engineering/multi-agent-research-system
- Writing effective tools for agents — with agents (2025-09-11): https://www.anthropic.com/engineering/writing-tools-for-agents
- Code execution with MCP (2025-11-04): https://www.anthropic.com/engineering/code-execution-with-mcp

**Claude Code / Claude Agent SDK 文档**
- How Claude Code works: https://code.claude.com/docs/en/how-claude-code-works
- Agent SDK overview / agent loop / subagents / tools / hooks / mcp / memory / skills / context window: https://code.claude.com/docs/en/agent-sdk/overview

**OpenAI**
- OpenAI Agents SDK: https://openai.github.io/openai-agents-python/
- Swarm(实验性前身): https://github.com/openai/swarm
- Responses API guide: https://platform.openai.com/docs/api-reference/responses

**其他框架 / 标准**
- LangGraph: https://docs.langchain.com/oss/python/langgraph/overview
- CrewAI: https://docs.crewai.com/en/introduction · AutoGen: https://microsoft.github.io/autogen/stable/ · Pydantic AI: https://ai.pydantic.dev/ · Google ADK: https://google.github.io/adk-docs/ · Mastra: https://mastra.ai/docs
- MCP: https://modelcontextprotocol.io/ · A2A: https://a2a-protocol.org/

**基础理论**
- Lilian Weng, LLM Powered Autonomous Agents (2023-06-23): https://lilianweng.github.io/posts/2023-06-23-agent/
- Yao et al., ReAct (arXiv:2210.03629): https://arxiv.org/abs/2210.03629
- Cognition / Walden Yan, Don't Build Multi-Agents (2025): https://cognition.ai/blog/dont-build-multi-agents