2.1 架构设计总览
2.1 架构设计总览
本节摘要：先看地图再走路。本节画出 SDK 的组件地图与数据流——一次用户请求如何从"定义"走向"执行"、经过哪些组件、最后如何返回结果。看懂这张图，后面每个组件都是在"地图上放大"。
先说结论
阅读完本节，你应当能够：
- 画出组件地图
- 跟踪一次请求的数据流
- 说出各组件的位置与职责
- 理解"定义与执行"的分层
- 用架构视角理解整个 SDK
一、问题与直觉
"SDK 那么多类，先学哪个？"——先看整体，再学局部。openai-agents-python 的架构其实很清晰：你定义（Agent），它执行（Runner），模型做思考，工具做动作。一张数据流图，胜过背十个类名。
理解这套架构，最关键的是接受一个事实：Agent 不是程序，是配置。你写 Agent(name="客服", instructions="...", tools=[...])，得到的只是一个描述"应该怎么干活"的对象，它自己不会运行。真正让事情发生的是 Runner——它读取 Agent 的定义，循环地调用模型、执行工具，直到产出最终答案。这个"定义与执行分离"的设计，是整个架构的第一性原理。
二、核心原理
2.1 组件地图
四个组件、两条回路：外层回路是"开发者定义 → Runner 执行 → 结果返回"；内层回路是"Runner ↔ 模型 ↔ 工具"，也就是工具调用循环。内层回路是 SDK 的魔法所在，外层回路是开发者每天打交道的界面。
2.2 一次请求的数据流
用户输入 → Runner 启动 → 带着 Agent 定义调模型 → 模型返回（文本 或 工具调用意图） → 要调工具 → Runner 执行工具 → 结果回传模型 → 模型继续 → 直到输出最终答案 → Runner 返回结果对象
注意"模型返回文本"和"模型返回工具调用意图"是两种出口。如果模型决定调工具，Runner 不会把意图直接给用户，而是自己执行工具、把结果回传，再让模型继续思考——这个循环可能发生多次，全在 Runner 内部完成。
2.3 用一段代码观察架构
from agents import Agent, Runner, function_tool @function_tool def add(a: float, b: float) -> float: """两个数相加。""" return a + b agent = Agent( name="calculator", instructions="用户给算式时用工具计算，并解释过程。", tools=[add], ) result = Runner.run_sync(agent, "3.5 加 4.5 等于多少？") print(result.final_output)
运行后观察 result：final_output 是最终回答，items 里包含完整的消息序列——你可以看到模型先输出"调用 add"的意图、工具执行的结果消息、模型最后的总结。这一条数据流，就是架构图的实际运行版本。
💡 关键直觉：Runner 是"司机"，Agent 是"导航"——导航告诉你该往哪走（定义），司机负责开车（循环执行）。理解这个分工，架构就通了。
三、工程实践要点
3.1 组件职责速查
| 组件 | 职责 | 类比 | 对应代码 |
|---|---|---|---|
| Agent | 行为定义 | 岗位说明书 | Agent(...) |
| Runner | 执行调度 | 部门主管 | Runner.run_sync(...) |
| Model | 思考引擎 | 大脑 | model 参数 |
| Tools | 行动能力 | 手脚 | tools=[...] |
| Tracing | 过程记录 | 监控摄像头 | result.trace_id |
3.2 数据流的三个循环
外层：用户 → Runner → 结果 内层：模型 ↔ 工具（自动循环） 记录：全程 → Tracing（第 3 章）
三层循环各司其职：外层是业务视角，内层是机制视角，记录层是排错视角。排查问题时，按这三层逐个检查：外层看结果对不对，内层看工具调用顺不顺，记录层看过程有没有异常。
3.3 用架构思维排查问题
| 现象 | 该看哪 |
|---|---|
| 智能体不听指令 | Agent 的 instructions |
| 工具没被调用 | Agent 的 tools 配置 + 模型是否决定调用 |
| 流程卡住 | Runner 的执行日志与循环次数 |
| 结果不对 | 模型与工具返回的内容 |
⚠️ 常见误区：以为"定义好 Agent 就完事了"。Agent 只是定义，真正干活的是 Runner 循环——排查问题要同时看"定义对不对"与"执行顺不顺"，只看一边容易漏。
⚠️ 常见误区：把架构图背下来。架构的价值是"定位工具"——遇到问题知道该去哪一层找答案，而不是背下每个箭头。多跑几次代码，让数据流变成直觉。
3.4 架构视角的收益
带着架构视角写代码，收益在三个时刻体现。写代码时：你会清楚"这段逻辑属于定义层还是执行层"，避免把业务状态塞进 Agent 配置。排错时：报错或行为异常，你能第一时间判断问题在哪一层——指令问题查定义，循环问题查执行，数据问题查模型与工具。设计时：新需求来了，你能快速判断"改配置就能满足，还是需要新增组件"，而不是推翻重写。架构不是考试题，是日常开发的思维脚手架。
重点提炼
- 要点一：分层架构——定义层（Agent）与执行层（Runner）
- 要点二：模型思考，工具动作，Runner 调度
- 要点三：内层"模型-工具"循环是核心魔法
- 要点四：Tracing 全程记录（第 3 章详述）
- 要点五：问题排查按组件定位
- 要点六：先看地图再学局部
地图看清了，下一节放大第一个组件——Agent 智能体核心。