6.6 KiB
| search | ||
|---|---|---|
|
快速入门
项目和虚拟环境的创建
此操作只需执行一次。
mkdir my_project
cd my_project
python -m venv .venv
虚拟环境的激活
每次启动新的终端会话时都需要执行此操作。
在 macOS 或 Linux 上:
source .venv/bin/activate
在 Windows 上:
.venv\Scripts\activate
Agents SDK 的安装
pip install openai-agents # or `uv add openai-agents`, etc
OpenAI API 密钥的设置
如果您还没有密钥,请按照这些说明创建 OpenAI API 密钥。
以下命令会为当前终端会话设置密钥。
在 macOS 或 Linux 上:
export OPENAI_API_KEY=sk-...
在 Windows PowerShell 上:
$env:OPENAI_API_KEY = "sk-..."
在 Windows 命令提示符中:
set "OPENAI_API_KEY=sk-..."
第一个智能体的创建
智能体通过 instructions、名称以及特定模型等可选配置来定义。
from agents import Agent
agent = Agent(
name="History Tutor",
instructions="You answer history questions clearly and concisely.",
)
第一个智能体的运行
使用 [Runner][agents.run.Runner] 执行智能体,并获取返回的 [RunResult][agents.result.RunResult]。
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())
对于第二轮交互,您可以将 result.to_input_list() 传回 Runner.run(...)、附加一个会话,或者使用 conversation_id / previous_response_id 复用由OpenAI服务器管理的状态。智能体运行指南对这些方法进行了比较。
可以采用以下经验法则:
| 如果您希望…… | 可以从……开始 |
|---|---|
| 完全手动控制,并使用与提供商无关的历史记录 | result.to_input_list() |
| 让 SDK 为您加载和保存历史记录 | session=... |
| 使用由OpenAI管理的服务器端续接 | previous_response_id 或 conversation_id |
有关权衡因素和确切行为,请参阅智能体运行。
当任务主要依赖提示词、工具和对话状态时,请使用普通的 Agent 搭配 Runner。如果智能体需要在隔离的工作区中检查或修改真实文件,请直接参阅沙盒智能体快速入门。
智能体工具的添加
您可以为智能体提供工具,以查询信息或执行操作。
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())
更多智能体的添加
在选择多智能体模式之前,请先确定由谁负责最终答案:
- 任务转移:由专家接管该轮交互中相应部分的对话。
- Agents as tools:编排器保持控制权,并将专家作为工具调用。
本快速入门将继续介绍任务转移,因为这是最简短的入门示例。有关管理器风格的模式,请参阅智能体编排和工具:agents as tools。
其他智能体可以用相同方式定义。handoff_description 会为路由智能体提供额外上下文,帮助其判断何时进行委派。
from agents import Agent
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],
)
智能体编排的运行
运行器负责执行各个智能体、处理所有任务转移以及所有工具调用。
import asyncio
from agents import Runner
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())
参考代码示例
代码仓库中包含实现相同核心模式的完整脚本:
examples/basic/hello_world.py,用于首次运行。examples/basic/tools.py,用于函数工具。examples/agent_patterns/routing.py,用于多智能体路由。
追踪记录的查看
如需回顾智能体运行期间发生的情况,请前往 OpenAI 控制面板中的追踪查看器,查看智能体运行的追踪记录。
后续步骤
了解如何构建更复杂的智能体工作流: