跳转至

快速入门

创建项目和虚拟环境

你只需要做一次。

mkdir my_project
cd my_project
python -m venv .venv

激活虚拟环境

每次开启新的终端会话时都要执行此操作。

source .venv/bin/activate

安装 Agents SDK

pip install openai-agents # or `uv add openai-agents`, etc

设置 OpenAI API 密钥

如果你还没有，请按照这些说明创建 OpenAI API 密钥。

export OPENAI_API_KEY=sk-...

创建你的第一个智能体

智能体由 instructions、名称以及可选配置（如特定模型）定义。

from agents import Agent

agent = Agent(
    name="History Tutor",
    instructions="You answer history questions clearly and concisely.",
)

运行你的第一个智能体

使用 Runner 执行智能体，并获取返回的 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

关于权衡和精确行为，请参阅运行智能体。

当任务主要依赖提示词、tools 和对话状态时，使用普通 Agent 加 Runner。如果智能体需要在隔离工作空间中检查或修改真实文件，请跳转到Sandbox 智能体快速入门。

为智能体提供工具

你可以为智能体提供工具来查询信息或执行操作。

import asyncio
from agents import Agent, Runner, function_tool


@function_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],
)

运行智能体编排

Runner 会处理执行各个智能体、任何任务转移以及任何工具调用。

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())

参考示例

仓库包含了相同核心模式的完整脚本：

查看追踪

要查看智能体运行期间发生了什么，请前往 OpenAI Dashboard 中的 Trace viewer 查看智能体运行的追踪。

后续步骤

了解如何构建更复杂的智能体流程：