智能代理

代理(Agents)是应用程序中的核心构建模块。一个代理就是一个大型语言模型(LLM)，通过指令和工具进行配置。

基础配置

您将配置的代理最常见属性包括：

instructions: 也称为开发者消息或系统提示。
model: 使用哪个LLM模型，以及可选的model_settings用于配置模型调优参数，如temperature、top_p等。
tools: 代理可以用于完成任务的各种工具。

from agents import Agent, ModelSettings, function_tool

@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=[get_weather],
)

上下文

代理(Agents)对其context类型是通用的。上下文(Context)是一个依赖注入工具：它是您创建并传递给Runner.run()的对象，会被传递给每个代理、工具、交接等，它作为代理运行的依赖项和状态的集合袋。您可以提供任何Python对象作为上下文。

@dataclass
class UserContext:
  uid: str
  is_pro_user: bool

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

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

输出类型

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

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时，这会告诉模型使用结构化输出而不是常规的纯文本响应。

任务交接

交接（Handoffs）是指主代理可以委派给子代理的机制。您提供一个交接列表，代理在相关情况下可以选择委派给它们。这是一种强大的模式，能够协调模块化、专业化的代理，每个代理都专注于单一任务。更多信息请参阅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],
)

动态指令

在大多数情况下，您可以在创建代理时提供指令。不过，您也可以通过函数动态提供指令。该函数将接收代理和上下文，并且必须返回提示。系统同时接受常规函数和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,
)

生命周期事件（钩子）

有时，您可能希望观察代理的生命周期。例如，您可能想要记录事件，或在某些事件发生时预取数据。您可以通过hooks属性来挂钩到代理生命周期中。继承AgentHooks类，并重写您感兴趣的方法。

防护栏

防护栏(Guardrails)允许您在代理运行的同时对用户输入进行检查/验证。例如，您可以筛选用户输入的相关性。更多详情请参阅guardrails文档。

克隆/复制代理

通过在代理上使用clone()方法，您可以复制一个Agent，并可选地更改您想要的任何属性。

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",
)

强制使用工具

提供工具列表并不总是意味着LLM会使用工具。您可以通过设置ModelSettings.tool_choice来强制使用工具。有效值为：

auto，允许LLM自行决定是否使用工具。
required，要求LLM必须使用工具（但可以智能决定使用哪个工具）。
none，表示要求LLM不要使用工具。
设置特定的字符串，例如my_tool，这要求LLM使用该特定工具。

注意

为了防止无限循环，该框架在工具调用后会自动将tool_choice重置为"auto"。此行为可通过agent.reset_tool_choice进行配置。之所以会出现无限循环，是因为工具结果会被发送给LLM，而LLM又会由于tool_choice的设置不断生成新的工具调用，如此循环往复。

如果您希望代理在调用工具后完全停止（而不是继续自动模式），可以设置[Agent.tool_use_behavior="stop_on_first_tool"]，这将直接使用工具输出作为最终响应，而无需进一步的LLM处理。