1.3 环境搭建与快速入门
1.3 环境搭建与快速入门
本节摘要：最快的学习方式是"跑起来"。本节带你完成安装、API 密钥配置、第一个智能体，再逐步加工具、加多智能体——用三个递进示例，让你在 10 分钟内感受 SDK 的核心能力。
你能学到什么
阅读完本节，你应当能够：
- 完成 SDK 安装
- 配置 API 密钥
- 跑通第一个智能体
- 给智能体加工具
- 跑通多智能体协作
一、问题与直觉
"安装、配密钥、跑起来"三步走——这是所有 SDK 的入场券。openai-agents-python 的安装极简（一个 pip 命令），第一个智能体只要几行代码。先跑通最小示例，再逐步加能力，是学习 SDK 的最快路径。
很多初学者卡在第一步就放弃了，原因往往不是代码难，而是环境细节：Python 版本不对、密钥没配、依赖冲突。所以本节把环境要求讲细一点：Python 建议 3.10 及以上（SDK 官方支持 3.9 及以上），用一个干净的虚拟环境安装依赖，密钥通过环境变量注入而不是写死在代码里。环境干净，后面所有示例都能顺畅跑起来。
二、核心原理
2.1 环境要求
三条缺一不可：没有 Python，代码跑不起来；没有安装包，import 报错；没有密钥，调用模型被拒绝。下面逐个解决。
三、工程实践要点
3.1 安装与配置
# 建议先建虚拟环境，避免污染全局 Python python -m venv .venv # Windows 激活 .venv\Scripts\activate # 安装 SDK pip install openai-agents # 配置密钥（环境变量，不要写进代码） export OPENAI_API_KEY="sk-你的密钥"
⚠️ 常见坑：密钥硬编码在代码里。密钥走环境变量，不进代码、不进版本库——泄露密钥等于把模型钱包交给别人。团队协作时用密钥管理服务，本地开发用环境变量或 dotenv 文件（且该文件必须进忽略清单）。
3.2 第一个智能体
from agents import Agent, Runner # 定义智能体 agent = Agent( name="greeter", instructions="你是一位友好的助手，用中文回答。", ) # 运行 result = Runner.run_sync(agent, "你好，介绍一下你自己") print(result.final_output)
三步：定义 Agent → Runner 运行 → 拿结果。第一个智能体跑通！注意 run_sync 是同步版本，适合脚本与演示；Web 服务里请用异步版本 await Runner.run(...)，避免阻塞事件循环（第 2 章会展开）。
3.3 加工具：让智能体"会干活"
from agents import Agent, Runner, function_tool @function_tool def get_weather(city: str) -> str: """查询城市天气。""" return f"{city} 今天晴，25 度" agent = Agent( name="weather_bot", instructions="用户问天气时，调用天气工具。", tools=[get_weather], ) result = Runner.run_sync(agent, "北京天气怎么样？") print(result.final_output)
加一个函数装饰器，智能体就会"自动调用工具"——这就是 SDK 的核心魔法。工具函数的签名和 docstring 会被转换成模型可见的工具说明书：参数名 city、类型 str、说明"查询城市天气"，模型据此决定何时调用、传什么参数。
💡 关键直觉：function_tool 装饰器把普通函数变成"智能体可调用的工具"——不用写任何循环逻辑，Runner 会自动决定"该调工具时调工具"。
3.4 多智能体：分工协作
from agents import Agent, Runner researcher = Agent( name="研究员", instructions="搜索并汇总资料，输出要点列表。", ) writer = Agent( name="写手", instructions="根据资料写一段 200 字左右的短文。", handoffs=[researcher], # 写手可以把任务交接给研究员 ) result = Runner.run_sync(writer, "写一篇关于智能体的短文") print(result.final_output)
（概念示意，具体 API 以官方文档为准）——多智能体让"一个不够"的任务有了分工方案。handoffs 参数声明"这个 Agent 可以交接给谁"，模型会根据对话内容自动决定是否交接。细节在第 3 章，这里先建立体感。
3.5 快速验证清单
第一个智能体能回复 → 环境与密钥 OK 带工具智能体能调工具 → function_tool 挂载 OK 多智能体能协作 → handoffs 机制 OK
三关都过，说明 SDK 的核心链路你已经亲手摸通了。遇到环境问题先自查这三步：Python 版本、包版本、密钥是否注入。
3.6 常见安装问题排查
问题一 import agents 报 ModuleNotFoundError 原因：包没装进当前环境 处理：确认虚拟环境已激活，重跑 pip install openai-agents 问题二 运行时提示 API key 未配置 原因：环境变量没设置或没生效 处理：检查 export 命令，重启终端让环境变量生效 问题三 pip 安装慢或超时 处理：配置国内镜像源加速，例如 pip install -i 镜像地址 openai-agents 问题四 首次调用报模型不存在 原因：模型名写错或账号无权限 处理：核对模型名拼写，检查账号的模型访问权限
环境问题九成出在这四类，逐项排查比反复重装快得多。把报错信息完整贴到搜索框，通常能找到现成答案。
核心回顾
- 要点一：三步——安装、配密钥、跑起来
- 要点二：第一个智能体只要几行代码
- 要点三：function_tool 把函数变工具
- 要点四：Runner 自动处理工具调用循环
- 要点五：多智能体解决"一个不够"的任务
- 要点六：密钥走环境变量，不进代码
入门跑通了，第 2 章深入内部——核心架构与组件。