0. AI Agent 框架全景：五层架构地图
从裸API调用到成品工具，一张图看清所有选项的定位
构建AI Agent时，你面对的不是"选哪个框架"的单选题，而是在五层架构中定位自己的需求。不同层级对应不同的控制粒度、抽象程度和运维复杂度。
本课目标：30分钟内建立AI Agent框架选型的完整心智模型，能独立判断"什么场景该用哪一层"。
1. 什么是AI Agent框架？
从"调用一次LLM"到"LLM自主调用工具并循环决策"
一个AI Agent能够自主感知环境、做出决策、调用工具并迭代执行以完成目标的AI系统和"调用一次ChatGPT API"的本质区别在于工具调用循环（Tool Loop）。普通API调用是"一问一答"；Agent则是"LLM判断→选择工具→执行工具→观察结果→再判断→……→最终回复"。
① 工具定义与注册 — 声明Agent可以调用哪些函数/API
② LLM调用与解析 — 发送请求并解析LLM返回的工具调用指令
③ 工具执行循环 — 执行工具→获取结果→送回LLM→判断是否继续
④ 上下文与状态管理 — 在多轮工具调用中维护对话历史和中间状态
| 对比维度 | 直接API调用 | Agent框架/SDK | 成品Agent工具 |
|---|---|---|---|
| 工具循环归属 | 你的应用代码自行管理 | 框架/SDK内置管理 | 产品内部封闭管理 |
| 定制灵活性 | 最高，完全控制 | 高，通过配置和扩展 | 低，受产品功能边界限制 |
| 开发成本 | 高，需手写循环逻辑 | 中，框架封装了循环 | 极低，开箱即用 |
| 典型代表 | OpenAI SDK + 自建循环 | Pydantic AI / Claude Agent SDK | Claude Code |
核心洞见 选择框架层级 = 选择"控制 vs 便利"的平衡点。越底层越灵活但越费劲；越上层越省力但越受限。不存在"最好"的层级，只存在"最匹配你当前需求"的层级。
2. 五层架构详解
每一层的运行方式、进程模型和适用场景
主张：AI Agent方案可按"产品/SDK/框架/传输"轴分为五层 → 证据：官方文档明确区分了各层级的运行边界——Direct API由应用持有循环，Claude Agent SDK启动独立CLI子进程，Codex SDK通过JSON-RPC控制本地app-server → 前提：基于各产品官方reference的架构描述。
运行方式：进程内（in-process）。你的Python/TypeScript应用直接pip install openai或pip install anthropic，在代码中调用API。
工具循环：你完全拥有。你定义function schema，解析LLM返回的tool_calls，在你的代码中执行对应函数，把结果作为新消息追加到上下文，再调用API——循环直到LLM不再返回tool_calls。
状态管理：你维护消息列表（messages array），每次API调用你决定传哪些历史。
适用：需要最大控制权的场景——定制化工具执行逻辑、特殊的错误处理、与现有业务系统深度集成。
运行方式：进程内（in-process），pip install pydantic-ai，import pydantic_ai。
核心特性：模型/提供商无关（可切换OpenAI、Anthropic、Groq等），类型化输出（用Pydantic模型约束LLM响应结构），内置Agent循环（自动处理工具调用的迭代），MCP集成（可作为MCP客户端连接工具服务器）。
工具循环：框架管理。你只需用装饰器注册工具函数，框架自动处理"LLM判断→调用工具→获取结果→继续"的循环。
适用：需要快速构建生产级Agent，想要类型安全和提供商灵活性，不想从头写工具循环。
Claude Agent SDK：TypeScript包@anthropic-ai/claude-agent-sdk和Python包claude-agent-sdk。它启动独立的claude CLI子进程通过stdio通信——不是进程内调用。它暴露了驱动Claude Code的工具、Agent循环和上下文管理能力，但以SDK形式供你编程调用。注意与Managed Agents区分。
OpenAI Codex SDK：TypeScript包@openai/codex-sdk包装本地codex CLI，通过stdin/stdout交换JSONL；Python包openai-codex通过JSON-RPC控制本地Codex app-server。Codex-as-MCP-server是可选编排路径，不是SDK的默认架构。
关键区分：OpenAI Codex SDK（coding-agent专用SDK）≠ OpenAI Agents SDK（通用编排框架）。前者针对代码生成场景，后者是通用Agent编排。
本质：一个已完成的Agentic Coding产品，提供CLI和IDE体验。它可交互使用，也可脚本化处理软件工程任务，但本身不是用来抽象任意业务Agent的通用框架；构建客服或数据分析Agent应选通用框架，编程复用Claude Code能力则使用Claude Agent SDK。
提供商支持：支持第三方提供商路由访问Claude模型。不要简单标签化为"仅限Anthropic"。
适用：开发者需要直接使用一个强大的AI编码助手，而非构建新的Agent系统。
MCP（Model Context Protocol）：一个开放协议，定义了LLM与外部工具/数据源之间的通信标准。Pydantic AI内置MCP集成。Codex-as-MCP-server是Codex的可选编排路径——你可以把Codex作为MCP服务器使用，但这不是Codex SDK的默认工作方式。
JSON-RPC / stdio：Claude Agent SDK使用stdio启动子进程通信；OpenAI Codex Python SDK使用JSON-RPC控制app-server。这些都是传输机制，不是Agent方案本身。
关键认知：传输层是你连接Agent组件的方式，不是你选择的Agent方案。先确定你需要的Agent层级（L1-L4），再考虑传输方式。
交互演示：Agent 工具调用循环
点击"下一步"观察一个典型Agent如何处理"北京天气"查询。蓝色=LLM推理，青色=工具调用，橙色=上下文状态。
LLM 推理层
工具调用队列
上下文状态
演示流程：用户查询 → LLM判断需调用工具 → 执行get_weather("北京") → 工具返回数据 → LLM综合回复 → 最终答案
3. 六大方案深度对比
产品 vs SDK vs 框架 vs 传输 — 一张表看清所有差异
主张：按产品/SDK/框架/传输轴区分六大方案能准确指导选型 → 证据：各官方文档对运行方式（in-process/subprocess/CLI product）有明确描述 → 前提：基于2025年各产品官方reference的最新架构信息。
| 方案 | 类型 | 语言 | 运行方式 | 工具循环归属 | 状态管理 | 适用场景 |
|---|---|---|---|---|---|---|
| OpenAI SDK + Responses API | 直接API | Python / TS | 进程内 | 应用自行管理 | 应用维护messages数组 | 需要最大控制权的定制Agent |
| Anthropic Messages API | 直接API | Python / TS | 进程内 | 应用自行管理 | 应用维护context | 深度集成Claude的定制Agent |
| Pydantic AI | 通用框架 | Python | 进程内 | 框架内置 | 框架管理 | 快速构建生产级、多模型Agent |
| Claude Code | 成品工具 | CLI / IDE | 独立产品 | 产品内部封闭 | 产品内部管理 | 直接使用AI编码助手 |
| Claude Agent SDK | 专用SDK | Python / TS | 启动独立CLI子进程（stdio） | SDK管理 | SDK+子进程管理 | 编程调用Claude Code能力 |
| OpenAI Codex SDK | 专用SDK | Python / TS | JSONL stdio 或 JSON-RPC | SDK管理 | SDK+本地app-server | Coding-agent编程集成 |
定制Agent = L1/L2 · 编码助手 = L3/L4 · 快速体验 = L4
Claude Code是面向终端用户的产品——你在终端输入claude，它帮你写代码。它是封闭的、开箱即用的体验。
Claude Agent SDK是面向开发者的编程接口——你在自己的代码中import它，通过它以编程方式驱动一个claude CLI子进程。它暴露了工具、循环和上下文管理能力，让你能把Claude Code的强大能力嵌入到你自己的应用或工作流中。
简单类比：Claude Code是"用Photoshop修图"；Claude Agent SDK是"在你的App里调用Photoshop引擎的API做批量修图"。
OpenAI Codex SDK：coding-agent专用SDK。TypeScript版通过@openai/codex-sdk包装本地codex CLI，用stdin/stdout交换JSONL；Python版通过openai-codex用JSON-RPC控制本地Codex app-server。专注代码生成场景。
OpenAI Agents SDK：通用Agent编排框架，用于构建各种类型的Agent（客服、分析、自动化等），不限于代码生成。
Codex-as-MCP-server是可选路径——你可以把Codex作为MCP服务器暴露给其他Agent使用。但这不是Codex SDK的默认架构，不要在未验证的情况下假设Codex SDK是HTTP MCP/uvicorn服务。
模型取舍与边界
| 维度 | L1 直接API | L2 通用框架 | L3 专用SDK | L4 成品工具 |
|---|---|---|---|---|
| 控制粒度 | 极细，每行代码可控 | 细，框架提供钩子 | 中，SDK封装核心循环 | 产品级交互，可配置与脚本化 |
| 学习成本 | 高，需理解完整Agent循环 | 中，需学习框架抽象 | 中，需学习SDK接口 | 低，开箱即用 |
| 提供商灵活性 | 绑定单一API | 模型无关 | 绑定特定产品 | 绑定产品 |
| 运维复杂度 | 高，需自行管理状态/重试/错误 | 中，框架处理大部分 | 中，需管理子进程 | 极低，产品负责 |
| 典型故障模式 | 状态混乱、循环死锁 | 框架配置错误 | 子进程通信断开 | 产品功能不满足需求 |
4. 实战代码示例
同一任务（查询天气Agent），三种层级的实现对比
import openai
client = openai.OpenAI()
messages = [{"role": "user", "content": "北京今天天气如何？"}]
# 定义工具
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"parameters": {"city": {"type": "string"}}
}
}]
# 应用自行管理循环
while True:
resp = client.responses.create(
model="gpt-4o",
input=messages,
tools=tools
)
if not resp.tool_calls:
break # LLM不再调用工具，循环结束
for tc in resp.tool_calls:
if tc.function.name == "get_weather":
result = my_weather_func(tc.function.arguments)
messages.append({
"role": "tool",
"tool_call_id": tc.id,
"content": str(result)
})
print(resp.output_text) # 最终回复关键点：while True循环由你的应用代码编写和管理。每一步的工具执行、结果追加、循环判断都是你的责任。
执行链路追踪（Execution Chain #1）— 直接API的Agent循环
Step 1：应用构建messages，包含用户查询"北京天气"。
Step 2：调用client.responses.create()，传入messages和tools定义。
Step 3：LLM返回tool_calls: [{function: "get_weather", arguments: {city: "北京"}}]。
Step 4：应用代码解析tool_calls，执行my_weather_func("北京")，获得结果{temp: 22}。
Step 5：应用将tool结果作为新消息追加到messages，再次调用API。
Step 6：LLM不再返回tool_calls，返回自然语言回复："北京今天22°C，晴"。
循环结束。整个过程中应用持有并管理所有状态。
from pydantic_ai import Agent
weather_agent = Agent(
"openai:gpt-4o",
system_prompt="你是一个天气助手。"
)
@weather_agent.tool
async def get_weather(city: str) -> str:
# 实际调用天气API
return f"{city}: 22°C, 晴"
# 一行调用，框架自动处理工具循环
result = await weather_agent.run("北京今天天气如何？")
print(result.data) # "北京今天22°C，晴"关键点：没有显式的while循环。agent.run()内部自动处理了LLM调用→工具执行→结果回传的完整循环。你用装饰器注册工具，框架接管一切。
执行链路追踪（Execution Chain #2）— Pydantic AI框架循环
Step 1：调用weather_agent.run("北京今天天气如何？")。
Step 2：框架内部构建prompt，调用OpenAI API（或配置的其他提供商）。
Step 3：LLM返回tool_call: get_weather(city="北京")。
Step 4：框架自动匹配到@weather_agent.tool装饰的get_weather函数，执行它。
Step 5：框架将工具返回值自动追加到上下文，再次调用LLM。
Step 6：LLM综合后返回最终文本。框架将result.data设为回复字符串。
关键差异：所有循环逻辑、状态管理、工具匹配都由框架完成，开发者只需定义工具和调用run()。
from claude_agent_sdk import ClaudeAgent
# SDK启动独立claude CLI子进程，通过stdio通信
agent = ClaudeAgent()
# 编程方式驱动Agent
result = agent.run(
prompt="分析当前目录的代码结构并给出优化建议",
working_dir="./my-project"
)
print(result.output)
# 注意：这不是进程内调用！
# agent.run() 启动了独立的 claude 子进程关键点：不是进程内调用。SDK启动独立claude CLI子进程，通过stdio管道交换数据。这提供了进程隔离，但也意味着你需要管理子进程的生命周期。
5. 常见误区与选型边界
这些直觉会让你选错方案，但它们看起来都"说得通"
Claude Code首先是面向软件工程的成品工具，不是抽象任意业务Agent的通用框架。它支持配置和脚本化使用；如果要在应用中编程复用其Agent循环、工具和上下文管理能力，应使用Claude Agent SDK。客服或数据分析Agent则通常选择通用Agent框架。
它们是两个完全不同的产品。Codex SDK是coding-agent专用SDK，专注于代码生成；Agents SDK是通用Agent编排框架。如果你要构建代码生成Agent用Codex SDK；如果你要构建通用Agent（客服、RAG、工作流编排）用Agents SDK。
不是。Claude Agent SDK启动独立的claude CLI子进程，通过stdio通信。这是进程外（out-of-process）模式。Pydantic AI是进程内（in-process）模式，在同一个Python进程中运行。进程外意味着：额外的启动开销、进程间通信延迟、需要管理子进程生命周期——但也有更好的隔离性。
Codex SDK的默认架构不是HTTP MCP/uvicorn服务。TypeScript版通过stdin/stdout交换JSONL，Python版通过JSON-RPC控制本地app-server。Codex-as-MCP-server是可选编排路径——你可以把Codex配置为MCP服务器，但这不是SDK的默认工作方式。不要在没有验证的情况下假设传输方式。
成品工具（L4）最省力，但功能边界最严格。如果你的需求超出了Claude Code的设计范围（比如需要自定义工具、特殊状态管理、嵌入到现有系统），你会被卡住。选型是"控制 vs 便利"的权衡——没有普适最优解。
选型决策树
Q1: 你需要的是一个可以直接使用的工具，还是需要编程构建Agent？
→ 直接使用工具：→ Claude Code（L4） — 确认你的需求在代码生成范围内
→ 编程构建Agent：继续 Q2
Q2: 你需要最大控制权，还是希望框架帮你管理工具循环？
→ 最大控制权：→ 直接API层（L1） — OpenAI SDK 或 Anthropic Messages API
→ 希望框架管理循环：继续 Q3
Q3: 你需要提供商灵活性（切换模型），还是绑定特定生态？
→ 提供商灵活、类型安全：→ Pydantic AI（L2）
→ 绑定Claude/Codex生态：继续 Q4
Q4: 你需要的是编码Agent能力还是通用Agent能力？
→ 编码Agent：→ OpenAI Codex SDK 或 Claude Agent SDK（L3）
→ 通用Agent：→ OpenAI Agents SDK 或回到 Pydantic AI（L2）
扩展路径
掌握框架选型后，可以深入：Pydantic AI的类型化输出和依赖注入系统、Claude Agent SDK的托管部署（Hosting）、OpenAI Agents SDK的多Agent编排模式、MCP协议的服务端与客户端实现、以及如何将Agent框架与LangChain/LlamaIndex等工具链集成。
6. 掌握检查
4 道诊断题，测试你的框架选型理解深度
1. 以下哪项是成品工具而非Agent框架/SDK？
2. Claude Agent SDK的运行方式是什么？
3. OpenAI Codex SDK与OpenAI Agents SDK的关系是？
4. 关于Pydantic AI的描述，哪项是正确的？
课程完成
确认以下每一项你都能做到，再继续深入。
扩展路径
掌握框架全景后，可以继续深入：Pydantic AI的依赖注入和类型系统、Claude Agent SDK的托管部署（Hosting）、OpenAI Agents SDK的多Agent编排、MCP协议的完整实现、以及LangChain/LlamaIndex与这些框架的互操作模式。
学习记录
进度加载中...
将下载的 JSON 文件放在课件旁，下次 AI 可以读取它来了解你的学习状态。