1. 引言

在构建 AI Agent 应用时，上下文管理是决定智能体行为质量和一致性的关键环节。agent-context 是一个轻量级 Python 包，专门为 AI Agent 提供结构化的上下文管理能力，帮助开发者高效维护对话历史、工具调用记录和状态信息。本文将详细介绍该包的核心功能、安装方法、API 语法，并通过 8 个实际案例展示其应用场景，最后总结常见错误与使用注意事项。

2. agent-context 包概述

agent-context 是一个面向 AI Agent 开发者的 Python 库，旨在解决以下核心问题：

• 上下文持久化：将 Agent 的对话历史、工具调用结果、中间状态等结构化数据持久化存储。
• 上下文检索：支持按时间、类型、关键词等维度快速检索历史上下文。
• 上下文压缩：自动对长上下文进行摘要或裁剪，避免超出 LLM 的上下文窗口限制。
• 多会话管理：支持同时管理多个 Agent 会话的上下文，互不干扰。

3. 安装

agent-context 可通过 pip 直接安装：

pip install agent-context

如需安装包含所有可选依赖的完整版本：

pip install agent-context[all]

可选依赖包括：

• redis：支持 Redis 作为上下文存储后端
• sqlite：支持 SQLite 本地存储
• compression：启用上下文压缩功能

4. 核心 API 与参数

4.1 ContextManager 类

核心入口类，负责上下文的创建、读写和管理。

from agent_context import ContextManager
初始化
cm = ContextManager(
backend="memory",       # 存储后端：memory | sqlite | redis
max_tokens=4096,        # 上下文最大 token 数
compression=True,       # 是否启用自动压缩
session_id=None         # 会话 ID，None 则自动生成
)

参数说明：

• backend：存储后端类型，默认为 memory（内存存储，进程结束后丢失）。
• max_tokens：上下文窗口的最大 token 数，超过时触发压缩或裁剪策略。
• compression：布尔值，是否启用自动压缩（需安装 compression 可选依赖）。
• session_id：字符串，用于标识会话。相同 session_id 可恢复历史上下文。

4.2 核心方法

# 添加消息到上下文
cm.add_message(role="user", content="你好，请帮我查询天气")
cm.add_message(role="assistant", content="好的，正在查询...")
添加工具调用记录
cm.add_tool_call(
tool_name="get_weather",
arguments={"city": "北京"},
result="晴天，25°C"
)
获取当前上下文（用于 LLM 调用）
context = cm.get_context()
返回格式：[{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}, ...]
搜索历史上下文
results = cm.search(query="天气", limit=5)
重置上下文
cm.reset()
保存上下文到持久化存储
cm.save()
从持久化存储加载上下文
cm.load(session_id="my_session_001")

4.3 上下文压缩策略

# 自定义压缩策略
cm.set_compression_strategy(
    strategy="summary",     # summary | truncate | sliding_window
    max_messages=50,        # 保留的最大消息数
    summary_prompt="请用一句话总结以上对话的核心内容"
)

5. 8 个实际应用案例

案例 1：基础对话上下文管理

构建一个简单的客服对话 Agent，维护多轮对话上下文。

from agent_context import ContextManager
cm = ContextManager(backend="memory", max_tokens=2048)
模拟多轮对话
cm.add_message("user", "我的订单还没到，能帮我查一下吗？")
cm.add_message("assistant", "好的，请提供您的订单号。")
cm.add_message("user", "订单号是 ORD-2024-001")
cm.add_message("assistant", "正在查询，请稍候...")
获取完整上下文用于 LLM 调用
context = cm.get_context()
print(f"当前上下文包含 {len(context)} 条消息")
输出：当前上下文包含 4 条消息

案例 2：工具调用记录追踪

Agent 调用外部工具时，记录每次调用的输入输出。

cm = ContextManager(backend="memory")
模拟 Agent 调用多个工具
cm.add_tool_call("search_database", {"query": "SELECT * FROM users"}, "返回 3 条记录")
cm.add_tool_call("call_api", {"url": "https://api.example.com/data"}, '{"status": "ok"}')
获取所有工具调用记录
tool_history = cm.get_tool_history()
for call in tool_history:
print(f"工具: {call['tool_name']}, 参数: {call['arguments']}")

案例 3：多会话隔离管理

同时管理多个用户会话，上下文互不干扰。

# 用户 A 的会话
cm_a = ContextManager(backend="memory", session_id="user_a")
cm_a.add_message("user", "帮我写一首诗")
用户 B 的会话
cm_b = ContextManager(backend="memory", session_id="user_b")
cm_b.add_message("user", "帮我算一道数学题")
两个会话完全隔离
print(f"用户 A 上下文: {len(cm_a.get_context())} 条")  # 1 条
print(f"用户 B 上下文: {len(cm_b.get_context())} 条")  # 1 条

案例 4：持久化存储与恢复

使用 SQLite 后端，在程序重启后恢复上下文。

# 第一次运行：创建并保存上下文
cm = ContextManager(backend="sqlite", session_id="chat_001")
cm.add_message("user", "今天天气怎么样？")
cm.add_message("assistant", "今天晴天，气温 25°C")
cm.save()  # 持久化到 SQLite
第二次运行：恢复上下文
cm2 = ContextManager(backend="sqlite", session_id="chat_001")
cm2.load()  # 从 SQLite 加载
context = cm2.get_context()
print(f"恢复后的上下文: {context}")

案例 5：上下文压缩与裁剪

当上下文超过 max_tokens 时自动压缩。

cm = ContextManager(
    backend="memory",
    max_tokens=100,  # 设置较小的窗口
    compression=True
)
添加大量消息触发压缩
for i in range(20):
cm.add_message("user", f"这是第 {i+1} 条长消息" * 10)
context = cm.get_context()
print(f"压缩后上下文 token 数: {cm.get_token_count()}")
输出：压缩后上下文 token 数: 98（不超过 100）

案例 6：上下文搜索与检索

在大量历史上下文中搜索特定内容。

cm = ContextManager(backend="memory")
cm.add_message("user", "我的邮箱是 test@example.com")
cm.add_message("user", "我的手机号是 13800138000")
cm.add_message("user", "请帮我重置密码")
搜索包含邮箱的上下文
results = cm.search(query="邮箱", limit=5)
for r in results:
print(f"找到: {r['content']}")

案例 7：与 LangChain 集成

将 agent-context 作为 LangChain Agent 的记忆组件。

from agent_context import ContextManager
from langchain.agents import AgentExecutor, create_react_agent
from langchain_openai import ChatOpenAI
使用 agent-context 管理记忆
memory = ContextManager(backend="memory", max_tokens=4096)
自定义 LangChain 回调，自动记录对话
def record_interaction(user_input, agent_response):
memory.add_message("user", user_input)
memory.add_message("assistant", agent_response)
创建 Agent 时传入记忆
llm = ChatOpenAI(model="gpt-4")
实际使用时将 memory 集成到 Agent 的 memory 参数中

案例 8：自定义存储后端

实现自定义存储后端，适配企业级数据库。

from agent_context import BaseBackend
class MyCustomBackend(BaseBackend):
def save(self, session_id, data):
# 将数据保存到自定义数据库
pass
def load(self, session_id):
    # 从自定义数据库加载数据
    pass
使用自定义后端
cm = ContextManager(backend=MyCustomBackend(), session_id="custom_session")

6. 常见错误与使用注意事项

6.1 常见错误

错误类型	错误信息	解决方法
后端未安装	ImportError: redis backend requires 'redis' extra	安装对应依赖：pip install agent-context[redis]
会话 ID 冲突	多个进程使用相同 session_id 导致数据覆盖	使用唯一 session_id，如 f"session_{uuid.uuid4()}"
上下文溢出	LLM 返回 token 超限错误	调小 max_tokens 或启用 compression=True
内存泄漏	长时间运行后内存持续增长	定期调用 cm.reset() 或使用持久化后端

6.2 使用注意事项

• 选择合适的后端：开发测试用 memory，生产环境建议用 sqlite 或 redis 保证数据持久化。
• 合理设置 max_tokens：根据 LLM 模型的上下文窗口设置，建议保留 20%-30% 的余量给模型输出。
• 定期清理历史：对于长期运行的 Agent，建议设置定时任务清理过期上下文，避免存储膨胀。
• 敏感信息处理：上下文中可能包含用户隐私数据，使用持久化后端时注意加密存储。
• 并发安全：memory 后端非线程安全，多线程场景建议使用 sqlite 或 redis 后端。
• 版本兼容性：升级 agent-context 前检查 changelog，避免存储格式不兼容导致数据丢失。

7. 总结

agent-context 为 Python AI Agent 开发提供了简洁而强大的上下文管理方案。通过灵活的存储后端、自动压缩机制和丰富的 API，开发者可以快速构建具备持久化记忆能力的智能体应用。本文介绍的 8 个案例覆盖了从基础对话到企业级集成的常见场景，掌握这些用法后，你可以根据实际需求进一步扩展和定制。

 

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。