Agents

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

基础配置

Agent 最常见的配置属性包括：

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

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 类型是通用的。上下文是一个依赖注入工具：它是你创建并传递给 Runner.run() 的对象，会被传递给每个 Agent、工具、交接等环节，作为 Agent 运行的依赖项和状态的容器。你可以提供任何 Python 对象作为上下文。

@dataclass
class UserContext:
    uid: str
    is_pro_user: bool

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

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

输出类型

默认情况下，agents 生成纯文本（即 str）输出。如果你希望 agent 生成特定类型的输出，可以使用 output_type 参数。常见的选择是使用 Pydantic 对象，但我们支持任何可以被 Pydantic TypeAdapter 包装的类型——数据类、列表、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,
)

Note

当你传递 output_type 时，这会指示模型使用 structured outputs 而非常规的纯文本响应。

交接/切换

Handoffs 是 agent 可以委派给子 agent 的机制。你提供一个 handoffs 列表，agent 可以在相关时选择委派给它们。这是一种强大的模式，可以编排模块化、专业化的 agent，每个 agent 专注于单一任务。更多内容请参阅 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 时提供指令。但你也可以通过函数提供动态指令。该函数将接收 agent 和上下文，并必须返回提示文本。支持常规函数和 async 异步函数。

def dynamic_instructions(
    context: RunContextWrapper[UserContext], agent: Agent[UserContext]
) -> str:
    return f"用户姓名是 {context.context.name}。请协助解答他们的问题。"


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

生命周期事件（钩子）

有时你需要观察 agent 的生命周期。例如，你可能希望记录事件或在特定事件发生时预取数据。通过 hooks 属性可以挂载到 agent 生命周期。继承 AgentHooks 类并重写你关注的方法即可。

安全护栏

安全护栏允许你在 agent 运行的同时对用户输入进行检查/验证。例如，可以筛查用户输入的相关性。详见安全护栏文档。

克隆/复制 agents

通过 agent 的 clone() 方法，你可以复制一个 Agent，并可选择修改任意属性。

pirate_agent = Agent(
    name="海盗",
    instructions="用海盗口吻写作",
    model="o3-mini",
)

robot_agent = pirate_agent.clone(
    name="机器人",
    instructions="用机器人语气写作",
)

强制使用工具

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

auto：允许 LLM 自行决定是否使用工具
required：要求 LLM 必须使用工具（但可以智能选择具体工具）
none：要求 LLM 禁止使用工具
设置特定字符串（如 my_tool）：要求 LLM 必须使用该指定工具

注意

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

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