AI工程 27 分钟阅读

从 0 到 1 的 Agent 工程:基于 Claude Code 与 OpenAI Agents SDK 的技术地图与实战教程

#Agent #LLM #Claude Code #OpenAI Agents SDK #上下文工程 #MCP #多Agent
.md

从 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"的本质):

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。

最小可用例子:

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 里就是"以工具形式暴露给模型"的,模型自己决定要不要转交:

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():

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: 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 工程博客

Claude Code / Claude Agent SDK 文档

OpenAI

其他框架 / 标准

基础理论