Agents介绍
Agents 是你应用程序中的核心构建模块。简单来说，一个 agent 就是一个配置了特定指令和工具的大语言模型(LLM)。
基础配置
配置 agent 时，你最常用到的属性有：
instructions：也就是开发者消息或系统提示词model：选择使用哪个 LLM，以及可选的model_settings来调整模型参数，比如 temperature、top_p 等tools：赋予 agent 完成任务所需的工具
from agents import Agent, ModelSettings, function_tool
def get_weather(city: str) -> str:
return f"{city}的天气是晴朗的"
agent = Agent(
name="俳句助手",
instructions="请用俳句形式回答",
model="o3-mini",
tools=[function_tool(get_weather)],
)
Context（上下文）
Agents 的 context 类型是通用的。Context 其实是一个依赖注入工具：你创建一个对象并传递给 Runner.run()，这个对象会被传递给每个 agent、tool 和 handoff 等。它就像一个百宝袋，存放着 agent 运行时需要的依赖和状态。你可以使用任何 Python 对象作为 context。
@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 包装的类型 - 比如 dataclasses、lists、TypedDict 等。
from pydantic import BaseModel
from agents import Agent
class CalendarEvent(BaseModel):
name: str
date: str
participants: list[str]
agent = Agent(
name="日历提取器",
instructions="从文本中提取日历事件",
output_type=CalendarEvent,
)
Note
当你设置 output_type 时，模型就会使用 structured outputs 而不是普通的文本响应。
Handoffs（任务转交）
Handoffs 是 agent 可以委派任务给的子 agent。你可以提供一个 handoffs 列表，agent 可以根据需要选择将任务委派给合适的子 agent。这是一个强大的模式，让你可以编排模块化的、专门的 agents，每个 agent 都专注于擅长的单一任务。想了解更多，可以查看 handoffs 文档。
from agents import Agent
booking_agent = Agent(...)
refund_agent = Agent(...)
triage_agent = Agent(
name="分诊助手",
instructions=(
"帮助用户解答问题。"
"如果他们询问预订相关问题，转交给预订助手。"
"如果他们询问退款相关问题，转交给退款助手。"
),
handoffs=[booking_agent, refund_agent],
)
动态指令
大多数情况下，你可以在创建 agent 时提供固定的指令。不过，你也可以通过函数提供动态指令。这个函数会接收 agent 和 context 作为参数，并返回提示词。普通函数和 async 函数都可以使用。
def dynamic_instructions(
context: RunContextWrapper[UserContext], agent: Agent[UserContext]
) -> str:
return f"用户名是 {context.context.name}。请帮助解答他们的问题。"
agent = Agent[UserContext](
name="分诊助手",
instructions=dynamic_instructions,
)
生命周期事件（Hooks）
有时候，你可能想要观察 agent 的生命周期。比如，你可能想要记录事件，或在某些事件发生时预先获取数据。你可以通过 hooks 属性来监听 agent 的生命周期。只需继承 AgentHooks 类，然后重写你感兴趣的方法即可。
Guardrails（防护栏）
Guardrails 允许你在 agent 运行的同时，对用户输入进行检查和验证。比如，你可以筛查用户输入是否相关。更多详情请查看 guardrails 文档。
克隆/复制 Agents
通过使用 agent 的 clone() 方法，你可以复制一个 Agent，还可以选择性地修改任何属性。