1.1 核心概念与发展历程
1.1 核心概念与发展历程
本节摘要：学 SDK 先装三个核心概念：Agent（智能体）、Runner（运行器）、Tools（工具）。本节用"外包团队"类比讲清三者分工，再简述 SDK 的发展背景（从 Chat Completions 到 Agent 原生），并给出第一段可运行的 Python 代码，帮你建立"这套 SDK 到底解决什么"的认知。
本节目标
阅读完本节，你应当能够：
- 说出 SDK 的三个核心概念
- 用类比解释三者的分工
- 理解 SDK 要解决的问题
- 说清它与传统 API 调用的差异
- 建立对官方 SDK 的整体认知
一、问题与直觉
传统大模型调用是"一问一答"：你发请求，模型回文本。但真实任务往往是多步骤的——查资料、算数据、再回答，还要在过程中调用工具。openai-agents-python 把这件事"产品化"了：Agent 是工人（有职责），Tools 是工具（会干活），Runner 是调度台（管流程）。三件套一装，多步骤任务就变成标准流水线。
为什么需要专门一套 SDK？因为"让模型调用工具"这件事，自己做起来比想象中麻烦：模型第一次返回的不是答案，而是"我想调用 get_weather，参数是 city=北京"这样的意图；你要解析这个意图、执行真实函数、把结果拼成一条新消息再发给模型；模型可能又返回第二个工具意图，循环直到它满意为止。这套循环写一次不难，难的是每个项目都写一遍、还要处理异常和超时。SDK 的价值，就是把这段最容易写错的胶水代码封装起来。
二、核心原理
2.1 三个核心概念
三个概念的配合像一支外包团队：
| 概念 | 类比 | 职责 | 代码里的角色 |
|---|---|---|---|
| Agent | 工人 | 定义智能体的行为与边界 | 配置对象 |
| Runner | 调度台 | 执行对话、调用工具、返回结果 | 执行入口 |
| Tools | 工具箱 | 提供模型之外的行动能力 | 可调用函数 |
2.2 它解决什么问题
传统方式：手动循环（发请求 → 看是否要工具 → 调工具 → 再请求） 官方 SDK：Runner 自动处理这个循环，开发者只管"定义 + 接收结果"
把同样一件事写成代码，差别一目了然。手动方式要维护循环状态、拼接历史消息、处理工具返回；SDK 方式只需要定义 Agent 和工具，然后调一次 Runner。
💡 关键直觉：SDK 的价值是"把工具调用循环封装进运行器"——你定义智能体和工具，Runner 负责"该用工具时自动用"。省掉的正是最容易写错的那段胶水代码。
2.3 发展脉络
从"纯对话 API"到"智能体原生 SDK"，演进路线可以概括为三个阶段：
| 阶段 | 形态 | 能力 | 开发者的痛点 |
|---|---|---|---|
| Chat Completions | 单轮对话 | 文本生成 | 只能问答，不能做事 |
| Function Calling | 函数调用 | 模型可声明调函数 | 循环逻辑要自己写 |
| Agents SDK | 智能体框架 | 自动循环、多智能体、可观测 | 上述痛点被框架吸收 |
三、工程实践要点
3.1 第一段可运行代码
from agents import Agent, Runner # 定义智能体：给它人设和边界 agent = Agent( name="greeter", instructions="你是一位友好的助手，用中文回答，不要编造事实。", ) # 交给运行器执行 result = Runner.run_sync(agent, "你好，介绍一下你自己") print(result.final_output)
这段代码只有五步：导入、定义 Agent、运行、拿结果、打印。没有循环、没有消息拼接——因为 Runner 把循环藏起来了。
3.2 概念对照速查
| 你要做什么 | 用哪个概念 |
|---|---|
| 给智能体定人设 | Agent 的 instructions |
| 让智能体查资料 | Tools（function_tool 装饰器） |
| 跑一次对话 | Runner.run_sync |
| 多个智能体配合 | handoffs（第 3 章详述） |
| 看执行过程 | Tracing（第 3 章详述） |
3.3 一个概念的直觉
from agents import Agent, Runner, function_tool @function_tool def get_order_status(order_id: str) -> str: """查询订单状态。""" return f"订单 {order_id} 已发货" agent = Agent( name="客服助手", instructions="先查订单再回答，查不到就如实说明。", tools=[get_order_status], ) result = Runner.run_sync(agent, "帮我查一下订单 10086 的状态") print(result.final_output)
3.4 学习提醒
⚠️ 常见误区：把 Agent 当成"一个人"。Agent 是"一段可配置的行为流程"——它由模型 + 指令 + 工具组成，不是独立存在的个体。同一个 Agent 对象可以反复运行，每次运行都是新的对话；理解这点，后面所有概念都顺。
⚠️ 另一个误区：以为 Tools 是模型自带的。模型只会"生成文本"，不会真的查数据库、发请求。所谓"模型调用工具"，是模型输出一个调用意图，真正执行的是你的函数——工具能力全部来自你的代码。
要点速记
- 要点一：三概念——Agent（工人）、Runner（调度）、Tools（工具）
- 要点二：SDK 把工具调用循环封装进 Runner
- 要点三：从对话 API 到 Agent SDK 是自然演进
- 要点四：Agent = 模型 + 指令 + 工具
- 要点五：工具能力来自你的代码，模型只输出调用意图
- 要点六：概念清楚，后面才顺
概念装好了，下一节看它好在哪、用在哪——关键优势与应用场景。