Skip to content

快速入门

创建项目和虚拟环境

你只需要做一次这个步骤。

mkdir my_project
cd my_project
python -m venv .venv

激活虚拟环境

每次启动新的终端会话时都需要执行这个操作。

source .venv/bin/activate

安装 Agents SDK

pip install openai-agents # 或者使用 `uv add openai-agents` 等

设置 OpenAI API 密钥

如果你还没有密钥，可以按照这些指引创建一个 OpenAI API 密钥。

export OPENAI_API_KEY=sk-...

创建你的第一个 agent

Agent 的定义包括指令、名称和可选配置（比如 model_config）

from agents import Agent

agent = Agent(
    name="数学辅导员",
    instructions="你提供数学问题的帮助。每一步都要解释你的推理过程并包含例子",
)

添加更多 agent

可以用同样的方式定义更多 agent。handoff_description 提供额外的上下文，用于确定转交路由

from agents import Agent

history_tutor_agent = Agent(
    name="历史辅导员",
    handoff_description="专门处理历史问题的 agent",
    instructions="你提供历史查询的帮助。清晰地解释重要事件和背景。",
)

math_tutor_agent = Agent(
    name="数学辅导员",
    handoff_description="专门处理数学问题的 agent",
    instructions="你提供数学问题的帮助。每一步都要解释你的推理过程并包含例子",
)

定义你的转交选项

在每个 agent 上，你可以定义一系列可用的转交选项，agent 可以从中选择以决定如何推进任务。

triage_agent = Agent(
    name="分类 Agent",
    instructions="你根据用户的作业问题决定使用哪个 agent",
    handoffs=[history_tutor_agent, math_tutor_agent]
)

运行 agent 编排

让我们检查一下工作流是否正常运行，以及分类 agent 是否正确地在两个专家 agent 之间进行路由。

from agents import Runner

async def main():
    result = await Runner.run(triage_agent, "法国的首都是什么？")
    print(result.final_output)

添加一个防护栏

你可以定义自定义防护栏来处理输入或输出。

from agents import GuardrailFunctionOutput, Agent, Runner
from pydantic import BaseModel

class HomeworkOutput(BaseModel):
    is_homework: bool
    reasoning: str

guardrail_agent = Agent(
    name="防护栏检查",
    instructions="检查用户是否在询问作业相关问题。",
    output_type=HomeworkOutput,
)

async def homework_guardrail(ctx, agent, input_data):
    result = await Runner.run(guardrail_agent, input_data, context=ctx.context)
    final_output = result.final_output_as(HomeworkOutput)
    return GuardrailFunctionOutput(
        output_info=final_output,
        tripwire_triggered=not final_output.is_homework,
    )

把所有内容组合起来

让我们把所有内容组合起来，运行整个工作流，使用转交和输入防护栏。

from agents import Agent, InputGuardrail,GuardrailFunctionOutput, Runner
from pydantic import BaseModel
import asyncio

class HomeworkOutput(BaseModel):
    is_homework: bool
    reasoning: str

guardrail_agent = Agent(
    name="防护栏检查",
    instructions="检查用户是否在询问作业相关问题。",
    output_type=HomeworkOutput,
)

math_tutor_agent = Agent(
    name="数学辅导员",
    handoff_description="专门处理数学问题的 agent",
    instructions="你提供数学问题的帮助。每一步都要解释你的推理过程并包含例子",
)

history_tutor_agent = Agent(
    name="历史辅导员",
    handoff_description="专门处理历史问题的 agent",
    instructions="你提供历史查询的帮助。清晰地解释重要事件和背景。",
)


async def homework_guardrail(ctx, agent, input_data):
    result = await Runner.run(guardrail_agent, input_data, context=ctx.context)
    final_output = result.final_output_as(HomeworkOutput)
    return GuardrailFunctionOutput(
        output_info=final_output,
        tripwire_triggered=not final_output.is_homework,
    )

triage_agent = Agent(
    name="分类 Agent",
    instructions="你根据用户的作业问题决定使用哪个 agent",
    handoffs=[history_tutor_agent, math_tutor_agent],
    input_guardrails=[
        InputGuardrail(guardrail_function=homework_guardrail),
    ],
)

async def main():
    result = await Runner.run(triage_agent, "美国第一任总统是谁？")
    print(result.final_output)

    result = await Runner.run(triage_agent, "生命是什么")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

查看你的追踪记录

要查看 agent 运行期间发生的情况，请导航到 OpenAI Dashboard 中的 Trace 查看器，查看你的 agent 运行的追踪记录。

下一步

学习如何构建更复杂的 agent 流程：