OpenAI Agents SDK 中文文档中文教程（2）

from agents import Agent, ModelSettings, function_tool

def get_weather(city: str) -> str:
    return f"The weather in {
       
       city} is sunny"

agent = Agent(
    name="Haiku agent",
    instructions="Always respond in haiku form",
    model="o3-mini",
    tools=[function_tool(get_weather)],
)

上下文

代理在其类型上是通用的。Context 是一个依赖关系注入工具：它是您创建并传递给的对象，该对象被传递给每个代理、工具、切换等，它充当代理运行的依赖项和状态的抓取袋。您可以提供任何 Python 对象作为上下文。contextRunner.run()

@dataclass
class UserContext:
  uid: str
  is_pro_user: bool

  async def fetch_purchases() -> list[Purchase]:
     return ...

agent = Agent[UserContext](
    ...,
)

输出类型

默认情况下，代理生成纯文本（即）输出。如果您希望代理生成特定类型的输出，则可以使用 parameter 。一个常见的选择是使用 Pydantic 对象，但我们支持任何可以包装在 Pydantic TypeAdapter 中的类型 - 数据类、列表、TypedDict 等。stroutput_type

from pydantic import BaseModel
from agents import Agent


class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

agent = Agent(
    name="Calendar extractor",
    instructions="Extract calendar events from text",
    output_type=CalendarEvent,
)

注意

当您传递，时，它会告诉模型使用结构化输出而不是常规的纯文本响应。output_type

交接

Handoff 是代理可以委派给的子代理。您提供交接列表，代理可以选择委派给它们（如果相关）。这是一个强大的模式，允许编排在单一任务中表现出色的模块化、专用代理。在 handoffs 文档中阅读更多内容。

from agents import Agent

booking_agent = Agent(...)
refund_agent = Agent(...)

triage_agent = Agent(
    name="Triage agent",
    instructions=(
        "Help the user with their questions."
        "If they ask about booking, handoff to the booking agent."
        "If they ask about refunds, handoff to the refund agent."
    ),
    handoffs=[booking_agent, refund_agent],
)

动态指令

在大多数情况下，您可以在创建代理时提供说明。但是，您也可以通过函数提供动态指令。该函数将接收 agent 和 context，并且必须返回 prompt。regular 和 functions 都被接受。async

def dynamic_instructions(
    context: RunContextWrapper[UserContext], agent: Agent[UserContext]
) -> str:
    return f"The user's name is {
       
       context.context.name}. Help them with their questions."


agent = Agent[UserContext](
    name="Triage agent",
    instructions=dynamic_instructions,
)

生命周期事件（钩子）

有时，您希望观察代理的生命周期。例如，您可能希望记录事件，或在某些事件发生时预取数据。您可以使用该属性挂接到代理生命周期。将 AgentHooks 类子类化，并覆盖您感兴趣的方法。hooks

护栏

防护机制允许您对用户输入运行检查/验证，与正在运行的代理并行。例如，您可以筛选用户输入的相关性。在护栏文档中阅读更多内容。

克隆/复制代理

通过在代理上使用该方法，您可以复制代理，并选择性地更改所需的任何属性。clone()

pirate_agent = Agent(
    name="Pirate",
    instructions="Write like a pirate",
    model="o3-mini",
)

robot_agent = pirate_agent.clone(
    name="Robot",
    instructions="Write like a robot",
)

运行代理

您可以通过 Runner 类运行代理。您有 3 个选项：

Runner.run（），它异步运行并返回 RunResult。
Runner.run_sync（）的 API 中，这是一种同步方法，仅在后台运行。.run()
Runner.run_streamed（）运行异步并返回 RunResultStreaming。它在流式处理模式下调用 LLM，并在收到这些事件时将这些事件流式传输给您。

from agents import Agent, Runner

async def main():
    agent = Agent(name="Assistant", instructions="You are a helpful assistant")

    result = await Runner.run(