智能体

智能体是应用中的核心构建块。智能体是配置了指令、工具以及可选运行时行为（例如任务转移、安全防护措施和 structured outputs）的大语言模型（LLM）。

当你希望定义或自定义单个普通Agent时，请使用本页面。如果你正在决定多个智能体应如何协作，请阅读智能体编排。如果智能体应在具有清单定义文件和沙箱原生能力的隔离工作区中运行，请阅读沙箱智能体概念。

对于OpenAI模型，SDK默认使用 Responses API，但这里的区别在于编排方式：Agent加Runner可让 SDK 代你管理轮次、工具、安全防护措施、任务转移和会话。如果你希望自行管理该循环，请直接使用 Responses API。

后续指南选择

请将本页面作为定义智能体的中心入口。根据下一步需要做出的决策，前往相应的相邻指南。

如果你希望……	接下来阅读
选择模型或提供商配置	模型
为智能体添加能力	工具
让智能体针对真实代码仓库、文档包或隔离工作区运行	沙箱智能体快速入门
在管理器式编排和任务转移之间做出选择	智能体编排
配置任务转移行为	任务转移
运行轮次、流式传输事件或管理对话状态	运行智能体
检查最终输出、运行项或可恢复状态	结果
共享本地依赖项和运行时状态	上下文管理

基本配置

智能体最常见的属性包括：

属性	必需	说明
name	是	易于理解的智能体名称。
instructions	否	系统提示词或动态指令回调。强烈建议设置。请参阅动态指令。
prompt	否	OpenAI Responses API 提示词配置。接受静态提示词对象或函数。请参阅提示词模板。
handoff_description	否	当此智能体作为任务转移目标提供时展示的简短说明。
handoffs	否	将对话委派给专业智能体。请参阅任务转移。
model	否	要使用的LLM。请参阅模型。
model_settings	否	模型调优参数，例如temperature、top_p和tool_choice。
tools	否	智能体可以调用的工具。请参阅工具。
mcp_servers	否	智能体使用的 MCP 支持工具。请参阅MCP 指南。
mcp_config	否	微调 MCP 工具的准备方式，例如严格模式的 schema 转换和 MCP 失败信息格式。请参阅MCP 指南。
input_guardrails	否	针对此智能体链首次用户输入运行的安全防护措施。请参阅安全防护措施。
output_guardrails	否	针对此智能体最终输出运行的安全防护措施。请参阅安全防护措施。
output_type	否	使用结构化输出类型，而非纯文本。请参阅输出类型。
hooks	否	作用于智能体范围的生命周期回调。请参阅生命周期事件（钩子）。
tool_use_behavior	否	控制工具结果是返回模型继续处理，还是结束本次运行。请参阅工具使用行为。
reset_tool_choice	否	在工具调用后重置tool_choice（默认值：True），以避免工具使用循环。请参阅工具的强制使用。

from agents import Agent
from agents.decorators import tool

@tool
def get_weather(city: str) -> str:
    """returns weather info for the specified city."""
    return f"The weather in {city} is sunny"

agent = Agent(
    name="Haiku agent",
    instructions="Always respond in haiku form",
    model="gpt-5-nano",
    tools=[get_weather],
)

本节中的所有内容都适用于Agent。SandboxAgent基于相同理念构建，并额外添加了default_manifest、base_instructions、capabilities和run_as，用于工作区范围的运行。请参阅沙箱智能体概念。

提示词模板

你可以通过设置prompt来引用在OpenAI平台中创建的提示词模板。此功能适用于使用 Responses API 的OpenAI模型。

使用步骤如下：

1. 前往 https://platform.openai.com/playground/prompts
2. 创建一个新的提示词变量poem_style。

3. 创建包含以下内容的系统提示词：

   Write a poem in {{poem_style}}
   

4. 使用--prompt-id标志运行代码示例。

from agents import Agent

agent = Agent(
    name="Prompted assistant",
    prompt={
        "id": "pmpt_123",
        "version": "1",
        "variables": {"poem_style": "haiku"},
    },
)

你也可以在运行时动态生成提示词：

from dataclasses import dataclass

from agents import Agent, GenerateDynamicPromptData, Runner

@dataclass
class PromptContext:
    prompt_id: str
    poem_style: str


async def build_prompt(data: GenerateDynamicPromptData):
    ctx: PromptContext = data.context.context
    return {
        "id": ctx.prompt_id,
        "version": "1",
        "variables": {"poem_style": ctx.poem_style},
    }


agent = Agent(name="Prompted assistant", prompt=build_prompt)
result = await Runner.run(
    agent,
    "Say hello",
    context=PromptContext(prompt_id="pmpt_123", poem_style="limerick"),
)

上下文

智能体的context类型是泛型。上下文是一种依赖注入工具：它是由你创建并传递给Runner.run()的对象，随后会被传递给每个智能体、工具和任务转移等，并作为智能体运行所需依赖项和状态的集合。你可以将任意 Python 对象作为上下文提供。

有关完整的RunContextWrapper功能、共享使用量追踪、嵌套tool_input以及序列化注意事项，请阅读上下文指南。

from dataclasses import dataclass

@dataclass
class Purchase:
    id: str

@dataclass
class UserContext:
    name: str
    uid: str
    is_pro_user: bool

    async def fetch_purchases(self) -> list[Purchase]:
        # implement your logic here
        return []

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

输出类型

默认情况下，智能体生成纯文本（即str）输出。如果你希望智能体生成特定类型的输出，可以使用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，而不是常规的纯文本响应。

多智能体系统设计模式

多智能体系统有许多设计方式，但我们通常会看到两种具有广泛适用性的模式：

1. 管理器（agents as tools）：由中央管理器/编排器将专业子智能体作为工具调用，并保留对话控制权。
2. 任务转移：对等智能体将控制权转移给接管对话的专业智能体。这是一种去中心化模式。

有关更多详细信息，请参阅构建智能体的实用指南。

管理器（agents as tools）

customer_facing_agent负责处理所有用户交互，并调用以工具形式公开的专业子智能体。请在工具文档中了解更多信息。

from agents import Agent

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

customer_facing_agent = Agent(
    name="Customer-facing agent",
    instructions=(
        "Handle all direct user communication. "
        "Call the relevant tools when specialized expertise is needed."
    ),
    tools=[
        booking_agent.as_tool(
            tool_name="booking_expert",
            tool_description="Handles booking questions and requests.",
        ),
        refund_agent.as_tool(
            tool_name="refund_expert",
            tool_description="Handles refund questions and requests.",
        )
    ],
)

任务转移

任务转移是智能体可以委派任务的子智能体。发生任务转移时，被委派的智能体会接收对话历史记录并接管对话。此模式支持模块化的专业智能体，使其能够出色完成单一任务。请在任务转移文档中了解更多信息。

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, hand off to the booking agent. "
        "If they ask about refunds, hand off 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,
)

生命周期事件（钩子）

有时，你可能希望观察智能体的生命周期。例如，你可能希望在特定事件发生时记录事件日志、预取数据或记录使用量。

钩子有两种作用域：

• RunHooks观察整个Runner.run(...)调用，包括向其他智能体的任务转移。
• AgentHooks通过agent.hooks附加到特定的智能体实例。

回调上下文也会因事件而异：

• 智能体开始/结束钩子接收AgentHookContext，它会封装你的原始上下文，并携带共享的运行使用量状态。
• LLM、工具和任务转移钩子接收RunContextWrapper。

典型的钩子触发时机：

• on_agent_start / on_agent_end：特定智能体开始或完成最终输出生成时。
• on_llm_start / on_llm_end：每次模型调用前后立即触发。
• on_tool_start / on_tool_end：每次本地工具调用前后触发。对于工具调用，钩子的context通常是ToolContext，因此你可以检查tool_call_id等工具调用元数据。
• on_handoff：控制权从一个智能体转移到另一个智能体时。

如果你希望使用单个观察器监控整个工作流，请使用RunHooks；如果某个智能体需要自定义副作用，请使用AgentHooks。

from agents import Agent, RunHooks, Runner


class LoggingHooks(RunHooks):
    async def on_agent_start(self, context, agent):
        print(f"Starting {agent.name}")

    async def on_llm_end(self, context, agent, response):
        print(f"{agent.name} produced {len(response.output)} output items")

    async def on_agent_end(self, context, agent, output):
        print(f"{agent.name} finished with usage: {context.usage}")


agent = Agent(name="Assistant", instructions="Be concise.")
result = await Runner.run(agent, "Explain quines", hooks=LoggingHooks())
print(result.final_output)

有关完整的回调功能，请参阅生命周期 API 参考。

安全防护措施

安全防护措施允许你在智能体运行的同时并行检查/验证用户输入，并在智能体生成输出后检查其输出。例如，你可以筛查用户输入和智能体输出的相关性。请在安全防护措施文档中了解更多信息。

智能体的克隆/复制

通过对智能体使用clone()方法，你可以复制一个智能体，并可选择更改任意属性。

pirate_agent = Agent(
    name="Pirate",
    instructions="Write like a pirate",
    model="gpt-5.6-sol",
)

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

工具的强制使用

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

1. auto，允许LLM自行决定是否使用工具。
2. required，要求LLM使用工具（但可以智能地决定使用哪个工具）。
3. none，要求LLM_不_使用工具。
4. 设置特定字符串，例如my_tool，要求LLM使用该特定工具。

使用 OpenAI Responses 工具搜索时，按名称指定工具的选择方式受到更多限制：你不能通过tool_choice指定裸命名空间名称或仅延迟加载的工具，而且tool_choice="tool_search"不会指定ToolSearchTool。在这些情况下，建议使用auto或required。有关 Responses 特有的限制，请参阅托管工具搜索。

from agents import Agent, ModelSettings
from agents.decorators import tool

@tool
def get_weather(city: str) -> str:
    """Returns weather info for the specified city."""
    return f"The weather in {city} is sunny"

agent = Agent(
    name="Weather Agent",
    instructions="Retrieve weather details.",
    tools=[get_weather],
    model_settings=ModelSettings(tool_choice="get_weather")
)

工具使用行为

Agent配置中的tool_use_behavior参数控制工具输出的处理方式：

• "run_llm_again"：默认行为。运行工具后，由LLM处理结果并生成最终响应。
• "stop_on_first_tool"：将第一个工具调用的输出用作最终响应，不再由LLM进一步处理。

from agents import Agent
from agents.decorators import tool

@tool
def get_weather(city: str) -> str:
    """Returns weather info for the specified city."""
    return f"The weather in {city} is sunny"

agent = Agent(
    name="Weather Agent",
    instructions="Retrieve weather details.",
    tools=[get_weather],
    tool_use_behavior="stop_on_first_tool"
)

• StopAtTools(stop_at_tool_names=[...])：如果调用了任何指定工具，则停止运行，并将其输出用作最终响应。

from agents import Agent
from agents.decorators import tool
from agents.agent import StopAtTools

@tool
def get_weather(city: str) -> str:
    """Returns weather info for the specified city."""
    return f"The weather in {city} is sunny"

@tool
def sum_numbers(a: int, b: int) -> int:
    """Adds two numbers."""
    return a + b

agent = Agent(
    name="Stop At Stock Agent",
    instructions="Get weather or sum numbers.",
    tools=[get_weather, sum_numbers],
    tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"])
)

• ToolsToFinalOutputFunction：用于处理工具结果，并决定是停止还是交由LLM继续处理的自定义函数。

from agents import Agent, FunctionToolResult, RunContextWrapper
from agents.decorators import tool
from agents.agent import ToolsToFinalOutputResult
from typing import List, Any

@tool
def get_weather(city: str) -> str:
    """Returns weather info for the specified city."""
    return f"The weather in {city} is sunny"

def custom_tool_handler(
    context: RunContextWrapper[Any],
    tool_results: List[FunctionToolResult]
) -> ToolsToFinalOutputResult:
    """Processes tool results to decide final output."""
    for result in tool_results:
        if result.output and "sunny" in result.output:
            return ToolsToFinalOutputResult(
                is_final_output=True,
                final_output=f"Final weather: {result.output}"
            )
    return ToolsToFinalOutputResult(
        is_final_output=False,
        final_output=None
    )

agent = Agent(
    name="Weather Agent",
    instructions="Retrieve weather details.",
    tools=[get_weather],
    tool_use_behavior=custom_tool_handler
)

Note

为防止无限循环，框架会在工具调用后自动将tool_choice重置为“auto”。此行为可通过agent.reset_tool_choice配置。之所以会发生无限循环，是因为工具结果会发送给LLM，随后LLM由于tool_choice而再次生成工具调用，如此无限重复。