01 它是干嘛的
Agents SDK 是给开发者搭「智能体」用的框架。它把大模型和真实世界连起来：模型不只会说话，还能调用工具（查数据库、发邮件、跑代码），并根据调用结果决定下一步。框架负责把「思考 → 调用 → 观察 → 再思考」这个循环管起来。
02 为什么会有它
光会说话的 AI 帮不上忙，能动手的 AI 才有用
一个大模型再聪明，它本质上也只能「输出文字」。你让它帮你订机票，它只能写一段「你可以去某某网站订」的话，它自己上不了网、点不了按钮、查不了价格。它像个只会纸上谈兵的顾问，说得头头是道，却一步都动不了。
想让 AI 真正干活，就得给它配「工具」：能查天气的接口、能读写数据库的接口、能发邮件的接口。模型自己挑用哪个工具、填好参数，程序去执行，再把执行结果拿回来喂给模型，模型据此决定下一步。这个「想一想、用个工具、看看结果、再想一想」的循环，就是智能体（Agent）的核心。
麻烦的是，这个循环里有一堆琐事要管：工具的说明书怎么写、模型填的参数对不对、调用失败了怎么重试、多个智能体互相怎么交接、跑到一半该不该停。Agents SDK 就是把这一整套架子搭好，开发者只要写清「有哪些工具、什么规则」，剩下的循环交给框架跑。
03 它怎么工作
智能体的本质是一个循环，模型负责决定下一步做什么，框架负责真的去做并把结果回填，如此往复直到任务完成。工具的描述写得越清楚，模型用得越准。
智能体的循环：思考、调用、观察、再思考
- 1① 交代目标与工具
你把任务和可用工具清单交给智能体，每个工具都附有一段说明，讲清它是干什么的、需要哪些参数。
- 2② 思考并决定
模型基于目标判断「现在该用哪个工具、参数填什么」，这一步输出的是结构化的调用指令，而不是随便一句话。
- 3③ 调用工具
框架按照模型的指令真的去执行——查数据库、调接口、算数据，把参数传进去。
- 4④ 观察结果
执行结果（成功的数据或失败的报错）被翻译回模型能读懂的文本，连同之前的上下文一起交回给模型。
- 5⑤ 再思考，直到收尾
模型看到结果后决定继续用别的工具、修正参数、还是给出最终答复。循环可能跑几轮，直到它判定任务完成或需要人来接管。
04 谁在用它
读邮件、查订单系统、回复客户、登记到表格，把跨系统的重复劳动串成一个智能体。
一个智能体先理解诉求，再决定是查知识库回答、还是转交人工、还是调接口办业务。
让智能体自己查数据库、算出结果、画成图表，人用自然语言提问即可。
拆成「接单的、查资料的、写结论的」几个角色，各管一段，互相交接。
审批、对账、批量录入这类规则清楚但操作琐碎的工作，交给智能体反复执行。
05 怎么用
面向开发者，需要会写 Python（或 TypeScript）；好处是脚手架齐全，几十行代码就能跑出一个能调工具的智能体。
- 01安装 SDK 并配置模型密钥。
- 02定义工具：每个工具就是一个普通函数，写明它做什么、需要什么参数。
- 03创建智能体，把目标说明和工具列表交给它。
- 04运行一次任务，观察它如何选择工具、调用、并根据结果继续。
- 05加上护栏与终止条件，防止它陷入死循环或做出危险操作。
- 06接入日志与追踪，看清每一轮它想了什么、调了什么、花了多少钱。
from agents import Agent, Runner, function_tool
@function_tool
def get_weather(city: str) -> str:
"""查询指定城市的当前天气。"""
return f"{city} 今天晴，26 摄氏度"
agent = Agent(
name="助手",
instructions="你是一个助手，需要查天气时调用工具，不要凭空猜测。",
tools=[get_weather],
)
result = Runner.run_sync(agent, "北京今天天气怎么样？")
print(result.final_output)避坑提示
- !工具描述就是接口：描述越清楚，模型选得越准；写糊了它就会乱调甚至不调。
- !一定设终止条件和最大轮数，否则它可能反复调用同一个工具停不下来。
- !让智能体在动真格之前先申请确认，尤其是转账、删除、发消息这类不可逆操作。
- !记录每一轮的输入输出，出问题时能回放它到底想了什么、错在哪一步。
06 关键概念
- 智能体（Agent）
- 能自己决定用哪个工具、并根据结果继续行动，直到完成任务的 AI 程序。
- 工具调用（Tool Calling）
- 模型不再只输出文字，而是输出「调用某个工具、参数是这些」，由程序去执行。
- 工具描述
- 每个工具附的一段说明文字，模型全靠它判断该不该用、怎么用，所以说「描述就是接口」。
- 护栏（Guardrail）
- 给智能体设的限制与检查，防止它做出越界或危险的行为。
- 循环（Loop）
- 思考、调用、观察来回若干轮的过程，是智能体干活的基本节奏。