LlamaIndex 智能体状态维护实战：从对话记忆到长期存储的全解析

在开发智能体应用时，我们常常遇到这样的困境：多轮对话中智能体无法记住用户历史信息，复杂任务流程难以保留中间结果。LlamaIndex 通过Context 上下文机制为智能体赋予了「记忆能力」，让状态维护变得简单高效。今天我们就结合实战代码，聊聊如何让智能体实现「对话有记忆、状态可持久」。

一、无状态困境：为什么需要维护智能体状态？

场景痛点：

• 用户第一次提问：「我叫 Laurie，帮我查股价」
• 智能体回复后，用户追问：「我刚才说的名字是什么？」
• 无状态情况下：智能体无法记住用户姓名，需重新询问，导致体验割裂。

LlamaIndex 解决方案：
通过Context类在智能体运行间维护状态，记录对话历史、用户信息等关键数据。
核心概念：

• 状态（State）：智能体需要记住的信息（如用户名、计算结果、API 令牌）。
• 上下文（Context）：状态的载体，支持跨运行周期存储和传递。

二、基础状态维护：实现对话记忆

1. 创建上下文并绑定智能体

python

运行

from llama_index.core.workflow import Context  

# 初始化上下文，关联智能体workflow  
ctx = Context(workflow)  

2. 在多轮对话中传递上下文

python

运行

async def main():  
    # 第一轮：用户告知姓名  
    response1 = await workflow.run(user_msg="Hi, my name is Laurie!", ctx=ctx)  
    print(response1)  # 输出：Hello Laurie! How can I assist you?  

    # 第二轮：智能体调用上下文记忆  
    response2 = await workflow.run(user_msg="What's my name?", ctx=ctx)  
    print(response2)  # 输出：Your name is Laurie!  

关键逻辑：

• 首次运行时，用户姓名被隐式存储在上下文的state变量中。
• 后续运行通过ctx自动获取历史状态，无需手动传递参数。

三、长期状态存储：从内存到磁盘的持久化

场景需求：
智能体需跨会话保留状态（如电商场景的购物车信息、医疗场景的患者记录）。

1. 序列化上下文到 JSON

python

运行

from llama_index.core.workflow import JsonSerializer  
import json  

# 将上下文转为字典（JSON可序列化格式）  
ctx_dict = ctx.to_dict(serializer=JsonSerializer())  

# 保存到文件  
with open("context.json", "w") as f:  
    json.dump(ctx_dict, f)  

2. 从磁盘恢复上下文

python

运行

# 读取文件  
with open("context.json", "r") as f:  
    ctx_dict = json.load(f)  

# 反序列化为上下文对象  
restored_ctx = Context.from_dict(workflow, ctx_dict, serializer=JsonSerializer())  

# 验证状态恢复  
response3 = await workflow.run(user_msg="What's my name?", ctx=restored_ctx)  
print(response3)  # 输出：Your name is Laurie!（即使重启程序也能正确回复）  

序列化器选择：

序列化器	适用场景	特点
JsonSerializer	纯文本状态（推荐）	轻量、跨语言兼容
JsonPickleSerializer	包含复杂对象的状态	基于 pickle，支持任意 Python 对象

四、工具与状态交互：打造有记忆的功能模块

场景需求：
智能体工具需主动修改状态（如用户注册流程中设置用户名、多步计算中保存中间结果）。
核心机制：
工具通过Context对象访问和修改状态，实现「数据读写 - 逻辑处理 - 状态更新」闭环。

1. 工具函数的标准结构

python

运行

async def tool_function(ctx: Context, *args, **kwargs) -> str:  
    """  
    工具函数必须以Context为第一个参数，用于访问状态  
    :param ctx: 上下文对象，包含当前状态  
    :param args/kwargs: 工具所需的业务参数  
    :return: 工具执行结果  
    """  
    # 1. 从上下文中获取状态  
    current_state = await ctx.get("state")  # AgentWorkflow默认状态变量为"state"  

    # 2. 处理业务逻辑（示例：更新用户名）  
    current_state["user_name"] = kwargs.get("name", "unset")  

    # 3. 将更新后的状态保存回上下文  
    await ctx.set("state", current_state)  

    # 4. 返回结果（可包含状态信息）  
    return f"State updated: user_name={current_state['user_name']}"  

2. 实战示例：自定义状态管理工具

需求：创建一个set_user_info工具，支持设置用户姓名和年龄，并在状态中存储。

python

运行

from llama_index.core.tools import FunctionTool  
from llama_index.llms.openai import OpenAI  
from llama_index.core.agent.workflow import AgentWorkflow  

# 1. 定义工具函数（含状态读写）  
async def set_user_info(ctx: Context, name: str, age: int) -> str:  
    """设置用户姓名和年龄到状态中"""  
    state = await ctx.get("state") or {}  # 初始化状态（避免空值）  
    state.update({  
        "user": {  
            "name": name,  
            "age": age,  
            "last_updated": datetime.now().isoformat()  
        }  
    })  
    await ctx.set("state", state)  
    return f"User info set: {state['user']}"  

# 2. 创建工具对象  
set_user_info_tool = FunctionTool.from_defaults(  
    fn=set_user_info,  
    name="SetUserInfo",  
    description="用于设置用户姓名和年龄到状态中"  
)  

# 3. 初始化智能体，配置初始状态  
workflow = AgentWorkflow.from_tools_or_functions(  
    [set_user_info_tool],  
    llm=OpenAI(model="gpt-4o-mini"),  
    system_prompt="你可以管理用户信息",  
    initial_state={}  # 初始状态为空，等待工具填充  
)  

# 4. 调用工具并验证状态  
async def main():  
    ctx = Context(workflow)  
    # 第一次调用：设置用户信息  
    response1 = await workflow.run(  
        user_msg="Set my info: name=Laurie, age=30",  
        ctx=ctx,  
        tool_args={"name": "Laurie", "age": 30}  # 传递工具参数  
    )  
    print(response1)  # 输出：User info set: {'name': 'Laurie', 'age': 30, ...}  

    # 第二次调用：读取状态（通过LLM提问）  
    response2 = await workflow.run(  
        user_msg="What's my name and age?",  
        ctx=ctx  
    )  
    print(response2)  # 输出：Your name is Laurie and you are 30 years old.  

关键细节解析：

• 状态结构：状态支持嵌套对象（如state["user"]），方便管理复杂信息。
• 参数传递：工具参数通过tool_args传递，避免与上下文参数混淆。
• LLM 联动：智能体可通过 LLM 自动解析用户输入（如从 "Set my info: name=Laurie, age=30" 提取参数），无需手动处理。

3. 多工具协同场景：状态作为信息桥梁

需求：先通过set_user_info设置用户信息，再通过get_user_age工具计算年龄对应的人生阶段。

python

运行

# 定义第二个工具：根据年龄计算人生阶段  
async def get_user_age_stage(ctx: Context) -> str:  
    state = await ctx.get("state")  
    age = state["user"].get("age")  
    if age < 18:  
        return "Teenager"  
    elif 18 <= age < 30:  
        return "Young Adult"  
    else:  
        return "Adult"  

# 合并工具到智能体  
workflow = AgentWorkflow.from_tools_or_functions(  
    [set_user_info_tool, get_user_age_stage],  
    llm=OpenAI(model="gpt-4o-mini"),  
    system_prompt="你可以管理用户信息并分析年龄阶段"  
)  

async def main():  
    ctx = Context(workflow)  
    # 第一步：设置用户信息  
    await workflow.run("Set my info: name=Laurie, age=30", ctx=ctx)  
    # 第二步：调用第二个工具，自动使用前一步状态  
    response = await workflow.run("What's my age stage?", ctx=ctx)  
    print(response)  # 输出：Your age stage is Adult.  

核心价值：

• 状态成为工具间的「共享内存」，避免重复传递参数。
• 复杂流程可拆分为多个工具，每个工具专注单一职责，提升代码可维护性。

五、生产级实践建议

1. 状态隔离：
   不同用户的状态需独立存储（如用用户 ID 作为上下文标识），避免数据混淆：

   python

   运行

   ctx = Context(workflow, context_id="user_123")  # 为用户分配唯一ID  
   

2. 敏感数据处理：
   对令牌、密码等敏感信息，建议在存储前加密：

   python

   运行

   from cryptography.fernet import Fernet  
   cipher = Fernet(encryption_key)  
   encrypted_state = cipher.encrypt(json.dumps(state).encode())  
   

3. 状态清理：
   定期删除过期状态（如会话超时后自动清除上下文），降低存储成本：

   python

   运行

   # 设置状态有效期（示例：30分钟）  
   await ctx.set("state", state, ttl=1800)  
   

结尾：让智能体真正「记住」用户需求

通过上下文机制，LlamaIndex 让智能体从「无记忆的问答机器人」升级为「有持续交互能力的智能助手」。无论是多轮对话中的信息留存，还是复杂流程中的状态传递，状态维护都是提升用户体验的关键。

如果本文对你有帮助，别忘了点赞收藏，关注我，一起探索更高效的开发方式～