教程 5：上下文管理

掌握使用 OpenAI Agents SDK 开发上下文感知智能体！本教程将教你如何利用 RunContextWrapper 传递自定义上下文对象，使智能体在整个执行过程中能够访问用户数据、会话信息和状态。

你将学到的内容

• RunContextWrapper：向智能体传递自定义上下文对象
• 上下文感知工具：构建可访问用户状态和偏好设置的工具
• 类型安全上下文：使用泛型类型实现编译时安全性
• 上下文操作：在智能体执行过程中更新和修改上下文
• 生产模式：真实场景中的上下文管理策略

核心概念：什么是上下文管理？

上下文管理让你能够向智能体传递自定义数据结构，这些数据结构会在整个智能体执行过程中持续存在。可以把上下文想象成一个共享状态容器，它：

• 存储用户信息、偏好设置和会话数据
• 提供对外部系统和数据库的访问权限
• 在多次工具调用之间保持状态
• 实现个性化的智能体行为
• 支持类型安全的数据访问

┌─────────────────────────────────────────────────────────────┐
│                    CONTEXT WORKFLOW                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  USER CONTEXT                                               │
│  ┌─────────────┐                                            │
│  │  UserInfo   │    1. PASS TO RUNNER                       │
│  │  - name     │ ────────────────────────────────────────┐  │
│  │  - uid      │                                         │  │
│  │  - prefs    │                                         ▼  │
│  └─────────────┘                                            │
│                   ┌─────────────┐                           │
│                   │   AGENT     │    2. CONTEXT AVAILABLE   │
│                   │   RUNNER    │       TO ALL TOOLS        │
│                   └─────────────┘                           │
│                         │                                   │
│                         ▼                                   │
│                   ┌─────────────┐    3. TOOLS ACCESS        │
│                   │ TOOL CALLS  │       CONTEXT VIA         │
│                   │ WITH        │       RunContextWrapper   │
│                   │ CONTEXT     │                           │
│                   └─────────────┘                           │
│                         │                                   │
│                         ▼                                   │
│                   ┌─────────────┐    4. CONTEXT CAN BE      │
│                   │  CONTEXT    │       MODIFIED AND        │
│                   │ UPDATED     │       PERSISTS            │
│                   └─────────────┘                           │
└─────────────────────────────────────────────────────────────┘
​

上下文管理的关键概念

上下文对象

用于存储状态和用户信息的自定义数据类：

@dataclass
class UserInfo:
    name: str
    uid: int
    preferences: dict = None
​

RunContextWrapper

提供对工具中上下文访问的类型安全包装器：

@function_tool
async def my_tool(wrapper: RunContextWrapper[UserInfo]) -> str:
    user = wrapper.context  # Access the UserInfo object
    return f"Hello {user.name}"
​

上下文感知智能体

使用泛型类型实现上下文安全性的智能体：

agent = Agent[UserInfo](
    name="Context Agent",
    tools=[context_aware_tool]
)
​

本演示展示了什么

1. 用户信息上下文

• 存储用户个人资料数据（姓名、ID、偏好）
• 根据用户上下文个性化智能体回复
• 在对话过程中更新用户偏好

2. 上下文感知工具

• fetch_user_profile(): Retrieve user information from context
• update_user_preference(): Modify user settings in context
• get_personalized_greeting(): Generate custom greetings

3. Type Safety

• Generic typing with Agent[UserInfo] for compile-time checks
• Typed context access with RunContextWrapper[UserInfo]
• IDE 对上下文对象的支持与自动补全功能

4. 上下文持久化

• 上下文修改在工具调用之间持续生效
• 状态变化在整个智能体执行过程中得以保留
• 更新后的上下文可供后续操作使用

学习目标

完成本教程后，你将掌握：

• ✅ 如何使用 dataclass 创建自定义上下文对象
• ✅ 使用 RunContextWrapper 实现类型安全的上下文访问
• ✅ 构建可读写状态的上下文感知工具
• ✅ 利用上下文实现个性化的智能体行为
• ✅ 大规模上下文管理的生产模式

开始使用

1. 安装 OpenAI Agents SDK：

   pip install openai-agents
   ​

2. 设置环境：

   cp env.example .env
   # Edit .env and add your OpenAI API key
   ​

3. 运行上下文示例：

   import asyncio
   from agent import context_example
   
   # Test context management
   asyncio.run(context_example())
   ​

示例应用场景

基本上下文使用

• “你好！我想了解我的个人资料，希望收到轻松的问候。”
• “把我的问候风格改为友好”
• “我当前的偏好是什么？”

个性化示例

• 根据用户偏好定制问候语
• 利用用户个人资料信息生成量身定制的回复
• 通过上下文更新动态调整智能体行为

生产级应用

• Web 应用中的用户会话管理
• 带有账户上下文的客户支持
• 电商应用中的购物偏好与历史记录

上下文管理的关键模式

1. 基本上下文创建

from dataclasses import dataclass

@dataclass
class UserInfo:
    name: str
    uid: int
    preferences: dict = None
​

2. 上下文感知工具

@function_tool
async def my_tool(wrapper: RunContextWrapper[UserInfo]) -> str:
    user = wrapper.context
    return f"Processing for {user.name}"
​

3. 带上下文运行

user_context = UserInfo(name="Alice", uid=123)
result = await Runner.run(agent, "message", context=user_context)
​

4. 上下文更新

@function_tool
async def update_preference(wrapper: RunContextWrapper[UserInfo], key: str, value: str) -> str:
    wrapper.context.preferences[key] = value
    return f"Updated {key} to {value}"
​

上下文管理最佳实践

1. 使用 Dataclass：利用 Python 的 dataclass 实现整洁的上下文对象
2. 类型安全：始终使用泛型类型进行编译时校验
3. 尽可能不可变：考虑使用 frozen dataclass 实现只读上下文
4. 验证：为上下文对象初始化添加校验逻辑
5. 文档化：清晰地记录上下文字段及其用途

相关概念

• 会话：上下文与会话记忆协同工作，实现全面的状态管理
• 防护措施：上下文可用于防护逻辑的校验
• 工具调用：上下文支持复杂的工具行为

常见误区

• 缺少泛型类型：始终在 Agent[YourContextType] 中指定上下文类型
• 上下文变异：注意避免意外修改上下文
• 内存泄漏：不再需要时清理大型上下文对象
• 线程安全：多线程应用中需考虑并发访问问题

高级技巧

• 从简单开始：先从基础用户信息入手，逐步扩展到复杂状态对象
• 尽早校验：为上下文对象构造函数添加校验逻辑
• 使用类型提示：利用 Python 类型提示提升 IDE 支持
• 考虑不可变性：适当使用 frozen dataclass 实现只读上下文
• 文档化上下文：清晰的文档有助于团队成员理解上下文结构

下一步

掌握上下文管理后，你将准备好：

• 教程 6：防护措施与校验 - 利用上下文实现输入输出的安全性
• 教程 7：会话 - 将上下文与对话记忆结合
• 教程 8：生产模式 - 在实际应用中规模化管理上下文

免责声明：
本文档采用基于机器的 AI 翻译服务进行翻译。尽管我们力求准确，但请注意，自动翻译可能存在错误或不准确之处。应以原文语言版本的文档作为权威依据。如需获取关键信息，建议使用专业的人工翻译。对于因使用本翻译而产生的任何误解或误读，我们概不负责。