Context 管理

Context 是一个多义词。你可能关心的 context 主要有两类：

本地代码可用的 context：这是工具函数运行时、在 on_handoff 等回调中、在生命周期钩子等场景下可能需要的数据和依赖项。
LLM 可用的 context：这是 LLM 在生成响应时能看到的数据。

本地 context

这通过 RunContextWrapper 类和其中的 context 属性来表示。它的工作方式是：

你可以创建任何想要的 Python 对象。常见模式是使用 dataclass 或 Pydantic 对象。
你将该对象传递给各种运行方法（例如 Runner.run(..., **context=whatever**)）。
所有工具调用、生命周期钩子等都会收到一个包装对象 RunContextWrapper[T]，其中 T 代表你的 context 对象类型，你可以通过 wrapper.context 访问它。

最重要的注意事项：对于给定的 agent 运行，每个 agent、工具函数、生命周期等必须使用相同_类型_的 context。

你可以将 context 用于以下场景：

运行的上下文数据（例如用户名/用户ID或有关用户的其他信息）
依赖项（例如日志记录器对象、数据获取器等）
辅助函数

注意

context 对象不会发送给 LLM。它纯粹是一个本地对象，你可以从中读取、写入和调用其方法。

import asyncio
from dataclasses import dataclass

from agents import Agent, RunContextWrapper, Runner, function_tool

@dataclass
class UserInfo:  # (1)!
    name: str
    uid: int

async def fetch_user_age(wrapper: RunContextWrapper[UserInfo]) -> str:  # (2)!
    return f"用户 {wrapper.context.name} 今年47岁"

async def main():
    user_info = UserInfo(name="John", uid=123)  # (3)!

    agent = Agent[UserInfo](  # (4)!
        name="Assistant",
        tools=[function_tool(fetch_user_age)],
    )

    result = await Runner.run(
        starting_agent=agent,
        input="用户多大年龄？",
        context=user_info,
    )

    print(result.final_output)  # (5)!
    # 用户 John 今年47岁。

if __name__ == "__main__":
    asyncio.run(main())

这是 context 对象。我们在这里使用了 dataclass，但你可以使用任何类型。
这是一个工具。你可以看到它接收一个 RunContextWrapper[UserInfo]。工具实现从 context 中读取数据。
我们用 UserInfo 泛型标记 agent，这样类型检查器可以捕获错误（例如，如果我们尝试传递一个使用不同 context 类型的工具）。
context 被传递给 run 函数。
agent 正确调用工具并获取年龄。

Agent/LLM context

当调用 LLM 时，它只能看到来自对话历史的数据。这意味着如果你想让 LLM 访问新数据，必须以某种方式将其添加到历史记录中。有几种方法可以做到这一点：

你可以将其添加到 Agent 的 instructions 中。这也被称为"系统提示"或"开发者消息"。系统提示可以是静态字符串，也可以是接收 context 并输出字符串的动态函数。这对于始终有用的信息（例如用户名或当前日期）是常见策略。
在调用 Runner.run 函数时将其添加到 input 中。这类似于 instructions 策略，但允许你在命令链中拥有较低位置的消息。
通过函数工具公开它。这对于_按需_context 很有用 - LLM 决定何时需要某些数据，并可以调用工具来获取该数据。
使用检索或网络搜索。这些是特殊工具，能够从文件或数据库（检索）或从网络（网络搜索）获取相关数据。这对于在相关上下文数据中"扎根"响应很有用。