Anthropic Agent 工程实战笔记（一）架构与选型

本模块主要参考（官方）

• 1\] [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)（Anthropic Engineering，Dec 2024）

---

本模块在整体中的位置

架构与选型是整条学习路径的起点 ：不先搞清楚「要不要 Agent、要哪种形态」，后面工具、上下文、长任务都会失去前提。Anthropic 的观察 [1] 是：最成功的落地案例往往用的是简单、可组合的模式 ，而不是一上来就上复杂框架或多 Agent。本模块要建立三个习惯：（1）能用简单方案就不加复杂度；（2）能说清 Workflow （预定义步骤编排 LLM 与工具）与 Agent （模型自主决定步骤与工具）的差别，并会选 Building Block（可组合的编排模式，见 §3）；（3）把工具当作 Agent--计算机接口（ACI）来设计，为模块二打基础。

---

逻辑线索（本模块阅读顺序）

1. 先判断：当前需求是否单轮 LLM + 检索/示例就能满足？若够用，不必上 Agent。
2. 再选形态：若需多步，是可枚举的固定步骤（Workflow）还是不可预测步骤（Agent）？对应到 §3 的 Building Blocks 表。
3. 再考虑框架与接口 ：用框架要理解底层；工具要当 ACI（Agent--计算机接口，见 §6）设计，避免「格式化苦力」与模糊描述。

---

1. 核心结论 [1]

• 能用简单方案就不用复杂方案：先考虑单轮 LLM 调用 + 检索/示例优化，仅当明显不足时再上多步或 Agent。
• Workflow vs Agent ：
  • Workflow = 预定义代码路径编排 LLM 与工具。
  • Agent = 模型动态决定过程与工具使用。
  • 很多场景只需「定义良好的 Workflow」，不必上完全自主 Agent。
• 框架使用 ：框架能快速搭起来，但容易掩盖底层 prompt/响应，难调试。建议先用 LLM API 直接实现核心模式（往往几行代码），若用框架务必搞清底层在做什么；对「框架黑盒」的错误假设是常见事故来源。这样做的原因 是：很多客户问题来自「以为框架做了 X，其实做了 Y」------只有理解底层，出问题时才能查 transcript（单次运行中对话与工具调用的完整轨迹记录）、改对地方。
• Building Blocks ：从「增强型 LLM 」（在单次 LLM 调用上挂载检索、工具、记忆等能力，见 §2）出发，再按需组合；关键是先测效果再加复杂度。
• Agent 的代价 [1]：多步与自主会带来更高延迟、更高成本，以及错误在多步间传播的风险；因此「先简单验证、再加复杂度」能避免过早背上技术债。

1.1 何时不必上 Agent [1]

在以下情况，优先考虑不要先上 Agent，而是用更简单方案验证：

情况	建议
单轮 LLM + 检索/示例已能达到可接受效果	先不引入多步或 Agent，只做 prompt 与检索优化
任务步骤固定、可枚举	用 Workflow（如 Prompt chaining、Routing）即可，不必上自主 Agent
对延迟或成本非常敏感	多步与 Agent 通常更贵、更慢，先评估单轮或轻量 Workflow
无法明确「成功」如何衡量	先定义清楚再上 Agent，否则难以评测与迭代

一句话：先问「单轮 + 检索能不能顶住？」能的话先不 Agent；若必须多步，再看步骤能否写死（Workflow）还是必须动态（Agent）。

1.2 选型总流程图 [1]

从需求到形态的决策可归纳为下图；§1.3 为「单轮不引入 Agent」示例，§3.8 为 Workflow（链式/路由）与自主 Agent 的可运行代码示例。
是
否
是
否
需求
单轮+检索\n是否够用?
不引入 Agent\n只做 prompt/检索优化
步骤是否\n可枚举?
Workflow
自主 Agent
选 Building Block
Prompt chaining
Routing
Parallelization
Orchestrator-Workers
Evaluator-Optimizer
工具+环境+沙箱+评测

1.3 单轮 LLM 示例（不引入 Agent）[1]

当「单轮 + 检索/示例」就够用时，不必上多步或 Agent。下面是最小单轮调用：一次 API、无工具、无循环。需 pip install anthropic 并设置 ANTHROPIC_API_KEY。示例使用稳定快照模型 ID；当前最新型号见 Anthropic Models。

from anthropic import Anthropic

client = Anthropic()
resp = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=512,
    messages=[{"role": "user", "content": "用一句话说明何时不必上 Agent。"}],
)
print(resp.content[0].text)

若效果已可接受，就保持单轮并优化 prompt/检索；只有明显不足时再考虑 §3.8 的 chaining、routing 或 agent 循环。

（可选）LangGraph 1.0 单轮等价 ：使用 langchain-anthropic + langgraph 时，单轮可写为 ChatAnthropic(model="claude-sonnet-4-20250514", max_tokens=512).invoke([HumanMessage(content="...")]).content。链式、路由与 Agent 循环的完整 LangGraph 1.0 示例见 延伸阅读 的「五、LangGraph 1.0 对照代码」一节。

---

2. 基础构建块：增强型 LLM [1]

据 [1]，所有多步形态的起点都是「增强型 LLM 」：在单次 LLM 调用上挂载检索、工具、记忆 等能力。模型可以自己生成查询、选工具、决定保留什么信息。实现方式之一是通过 Model Context Protocol (MCP) 接入第三方工具，用统一的 client 与 LLM 对话。下文的 Workflow 与 Agent 都假设「每次调用」已经是这种增强型 LLM。

                    ┌─────────────────────────────────────┐
                    │          Augmented LLM              │
                    │  (检索 + 工具 + 记忆 等)             │
                    └─────────────────────────────────────┘

---

3. Building Blocks 速查与流程图 [1]

以下模式与典型用法据 [1] 整理；对应可运行代码见 §1.3（单轮）与 §3.8（链式/路由/Agent）。

模式	何时用	典型例子
Prompt chaining	任务可拆成固定子步骤，每步一个 LLM 调用	先写大纲→检查→再写正文；先写文案→再翻译
Routing	输入分类型，不同类型走不同下游	简单问题走 Haiku、难问题走 Sonnet；客服按类型分流
Parallelization（Sectioning）	子任务独立，可并行	多维度 evals 各维度一 call；guardrails 与主流程分开
Parallelization（Voting）	需要多视角或多次尝试	内容合规多票；多 prompt 审代码漏洞
Orchestrator--Workers	子任务不可提前枚举，由中心动态分解	多文件代码修改；多源检索与综合
Evaluator--Optimizer	有明确评估标准，迭代改进有价值	多轮搜索+评估是否继续；文学翻译+评估反馈
自主 Agent	步骤数不可预测、需模型自主决策	Computer use、SWE-bench（基于真实 GitHub issue 的代码修复评测）式多文件修 bug

3.1 Prompt chaining（链式调用）

任务拆成固定步骤，每步一次 LLM 调用，可在任一步加门控（gate）做程序化检查，确保没跑偏再继续。
通过
不通过
输入
LLM 步骤1
门控检查
LLM 步骤2
输出

何时用 ：任务能清晰拆成固定子步骤，且希望用「多步、每步更简单」换更高准确率。
例子：先写大纲 → 检查大纲是否符合要求 → 再根据大纲写正文；先生成营销文案 → 再翻译成另一语言。

3.2 Routing（路由）

先用分类（LLM 或传统分类器）决定类型，再走不同下游（不同 prompt、不同模型或不同工具链）。
输入
分类器
分支 A
分支 B
分支 C
输出

何时用 ：任务有明确几类，且不同类适合不同处理方式；分类本身要足够准。
例子：简单问题走 Haiku、难问题走 Sonnet；客服按「一般咨询 / 退款 / 技术支援」分流到不同流程与工具。

3.3 Parallelization（并行）

Sectioning ：把任务拆成独立子任务，并行跑多个 LLM，再程序化汇总。
Voting：同一任务跑多次（或多 prompt），按投票或阈值决定结果。
输入
LLM 1
LLM 2
LLM 3
汇总/投票
输出

何时用 ：子任务可并行以提速，或需要多视角/多次尝试以提高置信度。
例子：Evals 里各维度分别一 call；主流程与 guardrails 分开跑；内容合规多票；多 prompt 审代码漏洞。

3.4 Orchestrator--Workers（编排--工人）

中心 LLM（Orchestrator）动态分解任务、派给多个 Worker LLM、再综合结果。和 Parallelization 的差别是：子任务不是事先定死的，由 Orchestrator 根据输入现场决定。
输入
Orchestrator
Worker 1
Worker 2
Worker ...
综合输出

何时用 ：子任务数量和形态无法提前枚举，需根据输入动态决定。
例子：多文件代码修改（改哪些文件、怎么改每次不同）；多源检索后综合回答。

3.5 Evaluator--Optimizer（评估--优化循环）

一个 LLM 生成，另一个 LLM 评估并反馈，形成迭代改进 loop；适合「人类给反馈能明显改进行为」且「模型也能给出类似反馈」的任务。
否
是
输入
Generator
Evaluator
满意?
输出

何时用 ：有清晰评估标准，且迭代能带来可衡量的提升。
例子：多轮搜索 + 每轮评估是否继续搜；文学翻译 + 评估反馈再改。

3.6 自主 Agent

模型在「用户指令 + 环境反馈」下自主决定是否调用工具、调用哪些、何时停止；可设检查点让人介入，或设最大步数防止失控。
用户
Agent
工具调用
环境

何时用 ：步骤数不可预测、路径无法写死，且能接受一定自主性与成本。
例子 ：Computer use、按 issue 描述改多文件的 Coding Agent（如 SWE-bench）。需配合沙箱（执行隔离环境，见 06）与评测（见 05）。

3.7 组合使用 [1]

上述 Building Blocks 可组合、可定制，不是单选一；例如先 Routing 再对某一路做 Orchestrator--Workers，或 Prompt chaining 里某一步用 Evaluator--Optimizer。关键是先测效果再加复杂度，按业务选组合方式。

3.8 可运行代码示例 [1][2]

以下为最小可运行 示例，需安装 anthropic（pip install anthropic）并设置环境变量 ANTHROPIC_API_KEY。对应上面「总流程图」中的 Workflow（链式、路由）与自主 Agent 循环。

示例 1：Prompt chaining（两步链式调用）

第一步生成大纲，第二步根据大纲写正文；第二步的输入依赖第一步的输出。

import os
from anthropic import Anthropic

client = Anthropic()  # 默认读 os.environ["ANTHROPIC_API_KEY"]

# 步骤 1：生成大纲
step1 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "请为《如何做 Agent 选型》写一个 3 个小节的提纲。"}],
)
outline = step1.content[0].text

# 步骤 2：根据大纲写正文（可在此前加门控检查）
step2 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=2048,
    messages=[
        {"role": "user", "content": f"根据以下提纲写正文：\n\n{outline}"},
    ],
)
final_text = step2.content[0].text
print(final_text[:500])

示例 2：Routing（按类型分流）

先分类再走不同下游；这里用 LLM 做分类，实际可用传统分类器或规则。

from anthropic import Anthropic

client = Anthropic()

def route_and_respond(user_input: str) -> str:
    # 分类
    route_msg = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=64,
        messages=[{"role": "user", "content": f"仅用一词回答：以下问题属于哪类？technical / billing / other\n\n{user_input}"}],
    )
    kind = route_msg.content[0].text.strip().lower()

    # 按类型选 prompt 并调用
    if "technical" in kind:
        prompt = f"【技术支援】请专业、简洁地回答：{user_input}"
    elif "billing" in kind:
        prompt = f"【账单与付费】请礼貌、清晰地回答：{user_input}"
    else:
        prompt = f"【一般咨询】请友好地回答：{user_input}"

    resp = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}],
    )
    return resp.content[0].text

示例 3：最小自主 Agent 循环（带一个工具）

模型可决定是否调用工具；这里只给一个 get_time 工具，循环直到模型不再返回 tool_use。响应可能含多个 content block（如先 text 再 tool_use），需遍历全部 block、收集所有 tool_use 并一次性回传所有 tool_result，符合 官方 Tool use 约定。实际应用见（二）工具设计 的工具设计。

from anthropic import Anthropic
from datetime import datetime, timezone

client = Anthropic()

tools = [{
    "name": "get_time",
    "description": "返回当前 UTC 时间，用于需要时间的对话。",
    "input_schema": {"type": "object", "properties": {}, "required": []},
}]

messages = [{"role": "user", "content": "现在几点了？请用工具确认后告诉我。"}]
max_turns = 5

for _ in range(max_turns):
    resp = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        messages=messages,
        tools=tools,
    )
    tool_results = []
    for block in resp.content:
        if getattr(block, "type", None) == "text":
            print("Assistant:", block.text)
        if getattr(block, "type", None) == "tool_use":
            result = datetime.now(timezone.utc).isoformat()
            tool_results.append({"type": "tool_result", "tool_use_id": block.id, "content": result})
    if not tool_results:
        break
    # 将本轮 assistant 的完整 content 加入历史（若 SDK 要求 dict 列表，可用 [b.model_dump() for b in resp.content]）
    messages.append({"role": "assistant", "content": list(resp.content)})
    messages.append({"role": "user", "content": tool_results})
else:
    print("达到最大轮数")

以上三例可直接复制运行（需有效 ANTHROPIC_API_KEY）；更多工具设计见（二）工具设计。LangGraph 1.0 下链式、路由与带工具 Agent 循环的完整可运行代码见 延伸阅读 的「五、LangGraph 1.0 对照代码」。

---

4. 用 Agent SDK 快速上手 [2]

在理清「要哪种形态」之后，可用 Building agents with the Claude Agent SDK 把选定的模式落地。建议做法：

• 先定模式再写代码：对照上文 Building Blocks 表，确定是 chaining、routing、还是自主 Agent，再用 SDK 实现对应循环（LLM 调用 + 工具解析 + 下一轮）。
• 配合官方 Cookbook ：patterns-agents-basic-workflows 有示例实现，可先跑通再按需求改。
• GitHub 源码 ：anthropics/claude-agent-sdk-python（Agent SDK）、anthropics/anthropic-sdk-python（Messages API，本文示例所用）、anthropics/claude-quickstarts（autonomous-coding / customer-support-agent 等可运行项目）。
• 理解底层：SDK 封装了调用与 tool 解析，但出问题时仍需能看 transcript、改 prompt；避免把 SDK 当黑盒。

这样可以在「符合第一性原理」的前提下，快速搭出最小可行 Agent，再按 02～06 模块深化工具、上下文与评测。

---

5. Agents in practice：两类高价值场景 [1]（原文附录）

Anthropic 与客户落地中，有两类场景特别适合 Agent，且都满足：对话 + 动作 、成功可衡量 、有反馈环 、有人类监督。

5.1 客服（Customer support）

• 界面是对话，但需要查数据、执行动作（退款、改工单、查订单）。
• 成功可定义：用户认可解决、工单关闭等。
• 工具可接入：客户信息、订单、知识库、退款/改单 API。
• 已有团队用「按成功解决付费」的模式，说明对效果有信心。

5.2 Coding Agent

• 输出可客观验证：测试通过、lint 通过、行为符合需求。
• 问题空间相对清晰；Agent 可用测试结果做反馈、迭代。
• Anthropic 自家实现已能在 SWE-bench Verified 上仅凭 PR 描述修真实 GitHub issue；但自动化测试只能验证功能，业务与架构是否合理仍需人工审查。

---

6. 工具即 Agent--计算机接口（ACI）[1]

工具是 Agent 与环境的合约；投入应接近为人机界面（HCI）所做的努力：文档、参数命名、错误信息都当「给新手写的 docstring」来写。

6.1 工具格式怎么选 [1]（原文 Appendix 2）

同一动作常有多种写法，但对模型难度差很多：

能力	较难的做法	更友好的做法
文件编辑	让模型写 diff（要先算准行数、chunk header）	整段/整文件重写，或接口不要求行号
结构化输出	要求把代码放在 JSON 里（转义换行、引号）	放在 Markdown 代码块里（训练数据更常见）
推理与行动	一步到位、容易写死	给足够 token 让模型「先想再写」

原则：少做「格式化苦力」 、格式贴近训练数据 、先想再写。

6.2 Poka-yoke（防错设计）[1]

通过参数设计让错误更难发生。

• 例子 [1]：SWE-bench 里，模型在离开项目根目录后常把相对路径用错；把工具改成强制绝对路径后，误用明显减少。

6.3 描述与测试 [1]

• 描述 [1]：像给新人写 docstring------写清用途、参数含义、边界、示例；参数名无歧义（如 user_id 而非 user）。
• 迭代 [1]：在 Workbench 等环境多跑用例，看模型常犯哪些错，再改工具定义。
• 原文 [1] 指出：做 SWE-bench 时，花在优化工具上的时间比优化主 prompt 还多，且收益明显。

工具设计细节见（二）工具设计。

---

7. 参考文献（本模块）

编号	来源	链接
[1]	Anthropic, Building effective agents	https://www.anthropic.com/engineering/building-effective-agents
[2]	Anthropic, Building agents with the Claude Agent SDK	https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk

---

8. 实战自检清单

• 当前需求是否已用「单轮 LLM + 检索/示例」验证过？若够用，不急于上 Agent。
• 若上多步：是可枚举的固定步骤（Workflow）还是不可预测步骤（Agent）？选对应 Building Block。
• 若用框架：是否理解底层 prompt、tool 解析与调用链？是否有办法在出问题时查 transcript？
• 工具命名、参数、错误信息是否对「新手」友好？是否做了防错设计（如绝对路径）？

---

9. 本模块要点回顾（便于自检与分享）

• 原则：能用简单方案就不用复杂方案；先测效果再加复杂度；Agent 有延迟/成本/错误传播代价，先简单验证再上。
• 何时不必上 Agent：单轮+检索够用、步骤可枚举用 Workflow、对延迟成本敏感、成功难以衡量时，优先不 Agent。
• 概念：Workflow = 预定义路径编排 LLM 与工具；Agent = 模型动态决定过程与工具；很多场景只需 Workflow。
• Building Blocks：从增强型 LLM 出发，按需选 Prompt chaining、Routing、Parallelization、Orchestrator--Workers、Evaluator--Optimizer，可组合；最后才是自主 Agent。
• SDK 上手：先定模式再写代码；配合 Cookbook；理解底层便于排查。
• 框架：可加速搭建，但需理解底层；否则调试与排错困难。
• 工具（ACI）：工具是 Agent 与环境的合约；要像给人写 docstring 一样写描述与错误信息，并做防错设计（如绝对路径）。

---

10. 延伸

• Agents in practice（原文附录）：客服（对话+动作、可衡量成功、可接入工具）与 Coding Agent（可测、可迭代、可验证）是两个典型高价值场景。
• Cookbook ： patterns-agents-basic-workflows 有示例实现。
• GitHub ： claude-agent-sdk-python / claude-agent-sdk-demos / claude-quickstarts（索引有「GitHub 与官方源码」汇总表）。
• 下一模块：（二）工具设计（工具描述、评测驱动迭代、返回格式与 token 效率）。