上下文管理
“上下文”一词含义广泛。通常你会关心两大类上下文：
- 代码本地可用的上下文：这是工具函数运行、
on_handoff等回调、生命周期钩子等场景下可能需要的数据和依赖。 - LLM 可用的上下文：这是 LLM 在生成响应时能够看到的数据。
本地上下文
这通过RunContextWrapper 类以及其内部的context 属性来表示。其工作方式是：
- 你创建任意 Python 对象。常见做法是使用 dataclass 或 Pydantic 对象。
- 将该对象传给各种运行方法（例如
Runner.run(..., **context=whatever**)）。 - 你的所有工具调用、生命周期钩子等都会接收一个包装对象
RunContextWrapper[T]，其中T表示你的上下文对象类型，你可以通过wrapper.context访问它。
最重要的一点：对于一次给定的智能体运行，该运行中的每个智能体、工具函数、生命周期等都必须使用相同“类型”的上下文。
你可以将上下文用于以下场景：
- 运行的情境化数据（例如用户名/uid 或有关用户的其他信息）
- 依赖（例如 logger 对象、数据提取器等）
- 帮助函数
注意
上下文对象不会发送给 LLM。它是一个纯本地对象，你可以读取、写入并在其上调用方法。
importasynciofromdataclassesimportdataclassfromagentsimportAgent,RunContextWrapper,Runner,function_tool@dataclassclassUserInfo:# (1)!name:struid:int@function_toolasyncdeffetch_user_age(wrapper:RunContextWrapper[UserInfo])->str:# (2)!"""Fetch the age of the user. Call this function to get user's age information."""returnf"The user{wrapper.context.name} is 47 years old"asyncdefmain():user_info=UserInfo(name="John",uid=123)agent=Agent[UserInfo](# (3)!name="Assistant",tools=[fetch_user_age],)result=awaitRunner.run(# (4)!starting_agent=agent,input="What is the age of the user?",context=user_info,)print(result.final_output)# (5)!# The user John is 47 years old.if__name__=="__main__":asyncio.run(main())- 这是上下文对象。这里我们使用了 dataclass，但你可以使用任何类型。
- 这是一个工具。你可以看到它接收
RunContextWrapper[UserInfo]。该工具实现会从上下文中读取数据。 - 我们用泛型
UserInfo标注智能体，以便类型检查器能够捕获错误（例如，如果我们尝试传入一个接收不同上下文类型的工具）。 - 上下文被传递给
run函数。 - 智能体正确调用工具并获取年龄。
进阶：ToolContext
在某些情况下，你可能希望访问正在执行的工具的额外元数据——例如其名称、调用 ID 或原始参数字符串。
为此，你可以使用扩展自RunContextWrapper 的ToolContext 类。
fromtypingimportAnnotatedfrompydanticimportBaseModel,FieldfromagentsimportAgent,Runner,function_toolfromagents.tool_contextimportToolContextclassWeatherContext(BaseModel):user_id:strclassWeather(BaseModel):city:str=Field(description="The city name")temperature_range:str=Field(description="The temperature range in Celsius")conditions:str=Field(description="The weather conditions")@function_tooldefget_weather(ctx:ToolContext[WeatherContext],city:Annotated[str,"The city to get the weather for"])->Weather:print(f"[debug] Tool context: (name:{ctx.tool_name}, call_id:{ctx.tool_call_id}, args:{ctx.tool_arguments})")returnWeather(city=city,temperature_range="14-20C",conditions="Sunny with wind.")agent=Agent(name="Weather Agent",instructions="You are a helpful agent that can tell the weather of a given city.",tools=[get_weather],)ToolContext 提供与RunContextWrapper 相同的.context 属性，
并额外包含当前工具调用特有的字段：
tool_name– 正在调用的工具名称tool_call_id– 此次工具调用的唯一标识符tool_arguments– 传递给工具的原始参数字符串
当你在执行期间需要工具级元数据时，使用ToolContext。
对于智能体与工具之间的一般上下文共享，RunContextWrapper 已足够。
智能体/LLM 上下文
当调用 LLM 时，它能够看到的唯一数据来自对话历史。这意味着，如果你想让某些新数据对 LLM 可见，必须以能将其纳入历史的方式提供。常见方法有：
- 将其添加到智能体的
instructions中。这也被称为“系统提示词（system prompt）”或“开发者消息”。系统提示词可以是静态字符串，或是接收上下文并输出字符串的动态函数。对于始终有用的信息（例如用户名或当前日期），这是一种常见策略。 - 在调用
Runner.run函数时，将其添加到input中。这与instructions的策略类似，但允许你添加在指挥链中位置更低的消息。 - 通过 工具调用（function tools） 暴露。这对于_按需_上下文很有用——LLM 会在需要某些数据时自行决定，并调用工具以获取该数据。
- 使用检索或 网络检索。这些是能够从文件或数据库（检索）或从网络（网络检索）获取相关数据的特殊工具。这有助于将响应“落地”到相关的情境数据上。