GuidesAgents
用 OpenAI Agents SDK 跑一个最小 Agent
安装 openai-agents,用 Agent + Runner 跑通最小文本 Agent,再加一个函数工具。
基于 OpenAI Agents SDK 整理 · 官方资料 ↗
Responses API 适合你自己掌控循环、工具分发和状态。如果你希望运行时帮你管多轮、工具执行、handoff 或 session,OpenAI Agents SDK 更合适:抽象很少,但把 Agent 运行时打包好了。
这篇按官方 Python Quickstart:建虚拟环境、安装 openai-agents、配置 OPENAI_API_KEY,然后用 Agent + Runner 跑通最小例子,再给 Agent 挂上一个函数工具。
先把“一个 Agent 完整跑完并打印 final_output”做成肌肉记忆,再去看 handoff、Sandbox 或 Realtime。
什么时候用 Agents SDK
官方对比很直接。工作流短、主要返回模型回答、你想自己拥有循环与状态时,直接用 Responses API。需要运行时管理 turns、工具执行、guardrails、handoffs、sessions,或要跨多步协调时,用 Agents SDK。
SDK 默认用 Responses API 调 OpenAI 模型,但把调用包进更高层运行时。两者不必二选一:托管工作流走 SDK,底层路径仍可直接打 Responses。
创建环境并安装 SDK
官方 Quickstart 建议先建项目目录和虚拟环境,再安装依赖。每次新开终端都要重新 activate。
macOS / Linux
mkdir my_project
cd my_project
python -m venv .venv
source .venv/bin/activate
pip install openai-agents
export OPENAI_API_KEY=sk-...Windows PowerShell
python -m venv .venv
.venv\Scripts\activate
pip install openai-agents
$env:OPENAI_API_KEY = "sk-..."没有 API Key 时,先按 OpenAI 控制台创建。Key 只放环境变量,不要写进仓库。
定义并运行第一个 Agent
Agent 至少要有 name 和 instructions。用 Runner.run 异步执行,拿回 RunResult;同步场景也可用 Runner.run_sync。
官方 Quickstart:History Tutor
import asyncio
from agents import Agent, Runner
agent = Agent(
name="History Tutor",
instructions="You answer history questions clearly and concisely.",
)
async def main():
result = await Runner.run(agent, "When did the Roman Empire fall?")
print(result.final_output)
if __name__ == "__main__":
asyncio.run(main())跑通的标志很简单:进程正常结束,final_output 是一段与历史问题相关的回答。若报认证错误,先回到 OPENAI_API_KEY。
给 Agent 挂上函数工具
用 @tool 把普通 Python 函数变成工具;SDK 负责 schema 与校验。把工具放进 Agent 的 tools 列表,并在 instructions 里说明何时使用。
官方 Quickstart:history_fun_fact 工具
import asyncio
from agents import Agent, Runner
from agents.decorators import tool
@tool
def history_fun_fact() -> str:
"""Return a short history fact."""
return "Sharks are older than trees."
agent = Agent(
name="History Tutor",
instructions="Answer history questions clearly. Use history_fun_fact when it helps.",
tools=[history_fun_fact],
)
async def main():
result = await Runner.run(
agent,
"Tell me something surprising about ancient life on Earth.",
)
print(result.final_output)
if __name__ == "__main__":
asyncio.run(main())和手写 Chat Completions 工具循环不同,这里由 Runner 在 Agent 循环里执行工具。你主要写函数与指令,而不是手拼 tool 消息。
下一步:handoff 分流
Quickstart 后半展示 triage + handoff:先定义 History Tutor / Math Tutor,再让 Triage Agent 的 handoffs 指向它们。Runner 会处理 agent 切换与工具调用。
官方 handoff 最小结构
from agents import Agent, Runner
import asyncio
history_tutor_agent = Agent(
name="History Tutor",
handoff_description="Specialist agent for historical questions",
instructions="You answer history questions clearly and concisely.",
)
math_tutor_agent = Agent(
name="Math Tutor",
handoff_description="Specialist agent for math questions",
instructions="You explain math step by step and include worked examples.",
)
triage_agent = Agent(
name="Triage Agent",
instructions="Route each homework question to the right specialist.",
handoffs=[history_tutor_agent, math_tutor_agent],
)
async def main():
result = await Runner.run(
triage_agent,
"Who was the first president of the United States?",
)
print(result.final_output)
print(f"Answered by: {result.last_agent.name}")
if __name__ == "__main__":
asyncio.run(main())多轮状态可以手动传 result.to_input_list(),也可以用 session,或使用 previous_response_id / conversation_id。细节见官方 Running agents。
跑完后去哪里看轨迹
SDK 内置 tracing。到 OpenAI Dashboard 的 Trace viewer 查看一次 run 里 agent、工具与 handoff 的路径,比只盯 final_output 更容易定位问题。
- pip install openai-agents 成功
- 无工具 Agent 能打印 final_output
- 带 @tool 的 Agent 能在回答中用到工具返回内容
- 需要时在 Dashboard Trace viewer 能看到对应 run
最容易踩的坑
Authentication / missing API key
确认当前 shell 已 export OPENAI_API_KEY(Windows 用对应语法),且激活的是安装了 openai-agents 的同一虚拟环境。
asyncio 报错或脚本无输出
按官方示例用 async def main + asyncio.run(main());或改用 Runner.run_sync 做同步试验。
工具从未被调用
检查 @tool 是否加入 tools=[...];instructions 是否明确何时使用;换一个更依赖该工具的问题。
不确定该用 SDK 还是直接打 Responses
只要短问答、自己管循环,就用 Responses;要运行时管多轮工具与编排,再用 Agents SDK。
官方资料
OpenAI Agents SDK
Quickstart ↗