让 AI Agent 过目不忘：无影 AgentBay 跨会话数据持久化实战-阿里云开发者社区

本文作者：阿里云无影技术专家李岳冰

无影 AgentBay 是什么

做 AI Agent 开发绕不开一个问题：Agent 光会"想"不够，还得能"动手"——打开浏览器查资料、在终端里跑代码、甚至操作手机 App。但让 Agent 直接操作你的电脑，风险太大。

AgentBay 解决的就是这个问题。它给每个 Agent 分配一个独立的云端沙箱，可以理解为一台"云上临时电脑"。Agent 在里面随便折腾，不会影响你的本地环境。

通过无影 AgentBay 的 SDK 创建一个云端环境只需要几行代码：

from agentbay import AgentBay, CreateSessionParams
agent_bay = AgentBay()
session = agent_bay.create(CreateSessionParams()).session
session.command.execute_command("echo 'Hello from cloud!'")
agent_bay.delete(session)

这里的 Session 就是一个云端沙箱实例。创建、使用、销毁，整个过程很直观。更多关于 Session 的说明可以参考 Session 管理文档。

问题：Session 是一次性的

Session 的设计初衷就是"用完即弃"——创建后在里面做各种操作，任务结束就销毁。所有文件、配置、运行状态，随着 Session 一起消失。

对于一次性任务（跑个脚本、测个接口）这完全没问题。但很多场景下，这种"阅后即焚"的行为反而是个麻烦：

编程助手帮你写了一下午代码，第二天你想接着写，发现项目没了
数据分析跑了两小时的计算，结果没保存，得重跑
好不容易在手机 App 里完成了登录，下次又得重新登录

说白了，Agent 需要"记忆"。上次做到哪了、产出了什么、有哪些状态要保留——这些信息不能随着 Session 一起丢掉。

AgentBay 的持久化方案

AgentBay 提供了多种持久化机制来应对不同场景：

图中展示了四种方案，各有侧重：

Context：通用的文件级持久化，适合保存项目文件、配置、数据等。
Browser Context：专门持久化浏览器状态（Cookie、缓存等）。
Pause/Resume（Beta）：暂停和恢复 Session，保留完整的运行时状态（进程、内存等），适合需要中断再继续的长时间任务。
Volume（规划中）：大容量数据磁盘，适合 TB 级别的数据存储场景。

下面会介绍最常用的 Context 和 Browser Context。

Context 是什么

简单说，Context 就是一个挂在云端的存储空间。它不属于任何一个 Session，而是独立存在的。你可以把它想成一个"云端 U 盘"：

Session 启动时，自动把 Context 里的文件下载到指定目录
Session 运行期间，Agent 在这个目录里正常读写
Session 结束时，把修改过的文件上传回 Context

下次再创建 Session 时，只要挂载同一个 Context，数据就自动恢复了。完整的 API 说明见数据持久化文档。

准备工作

开始之前需要两步准备：

# 1. 安装 SDK
pip install wuying-agentbay-sdk
# 2. 设置 API Key（在阿里云 AgentBay 控制台获取）
export AGENTBAY_API_KEY=your_key_here

上手实操

下面通过一个例子演示 Context 的完整用法。

如果你想先跑起来看效果，直接复制下面这段脚本运行（需要提前设置 AGENTBAY_API_KEY 环境变量）：

"""
AgentBay Context 数据持久化演示
运行前设置环境变量: export AGENTBAY_API_KEY=your_key
安装依赖: pip install wuying-agentbay-sdk
"""
from agentbay import AgentBay, ContextSync, CreateSessionParams, SyncPolicy
agent_bay = AgentBay()
# 1. 创建 Context
context = agent_bay.context.get("persistence-demo", create=True).context
print(f"[1] Context 就绪: {context.name} ({context.id})")
# 2. 配置挂载
context_sync = ContextSync.new(
    context_id=context.id,
    path="/tmp/workspace",
    policy=SyncPolicy.default()
)
params = CreateSessionParams(context_syncs=[context_sync])
# 3. 第一个 Session：写入数据
session1 = agent_bay.create(params).session
print(f"[2] Session 1 已创建: {session1.session_id}")
session1.file_system.write_file("/tmp/workspace/notes.txt", "第一次会话写入的内容")
session1.file_system.write_file("/tmp/workspace/config.json", '{"version": "1.0"}')
print("[3] 已写入 2 个文件")
agent_bay.delete(session1, sync_context=True)
print("[4] Session 1 已销毁，数据已同步到 Context")
# 4. 第二个 Session：验证数据恢复
session2 = agent_bay.create(params).session
print(f"[5] Session 2 已创建: {session2.session_id}")
content = session2.file_system.read_file("/tmp/workspace/notes.txt").content
config = session2.file_system.read_file("/tmp/workspace/config.json").content
print(f"[6] 读取到 notes.txt: {content}")
print(f"[7] 读取到 config.json: {config}")
agent_bay.delete(session2)
print("[8] Session 2 已销毁，演示完成")
# 5. 清理 Context（可选）
# agent_bay.context.delete(context)

跑完之后回来看分步讲解，会更容易理解每一步在做什么。

第一步：准备 Context

from agentbay import AgentBay
agent_bay = AgentBay()
# 按名称获取 Context，不存在就创建一个
result = agent_bay.context.get("my-project", create=True)
context = result.context
print(f"Context: {context.name} (ID: {context.id})")

Context 的名字是唯一标识，同一个 API Key 下不会重复。第一次调用时会创建，之后再调用就直接返回已有的。

第二步：创建 Session 并关联 Context

from agentbay import ContextSync, CreateSessionParams, SyncPolicy
# 配置：把 Context 挂载到 Session 的 /tmp/workspace 目录
context_sync = ContextSync.new(
    context_id=context.id,
    path="/tmp/workspace",
    policy=SyncPolicy.default()
)
# 创建 Session
session = agent_bay.create(
    CreateSessionParams(context_syncs=[context_sync])
).session

ContextSync 描述了"把哪个 Context 挂到哪个目录"。SyncPolicy.default() 使用默认的同步策略，大多数情况下够用了。

第三步：在 Session 里干活

# 写文件
session.file_system.write_file(
    "/tmp/workspace/notes.txt",
    "第一次会话：项目初始化完成"
)
session.file_system.write_file(
    "/tmp/workspace/config.json",
    '{"version": "1.0", "status": "in-progress"}'
)
# 跑命令也行
session.command.execute_command("ls -la /tmp/workspace/")

这些文件写在 /tmp/workspace/ 下，也就是 Context 挂载的目录。

第四步：销毁 Session，保留数据

# sync_context=True 表示销毁前把数据同步回 Context
agent_bay.delete(session, sync_context=True)

Session 没了，但 /tmp/workspace/ 里的文件已经上传到 Context 的云端存储中。

第五步：新 Session 中验证

# 创建全新的 Session，挂载同一个 Context
new_session = agent_bay.create(
    CreateSessionParams(context_syncs=[context_sync])
).session
# 读取上次写入的文件
content = new_session.file_system.read_file("/tmp/workspace/notes.txt").content
print(content)  # => 第一次会话：项目初始化完成
config = new_session.file_system.read_file("/tmp/workspace/config.json").content
print(config)   # => {"version": "1.0", "status": "in-progress"}
agent_bay.delete(new_session)

数据完好无损地从上个 Session 延续到了新 Session。

两个实际场景

编程助手：项目跨会话延续

# 第一次对话：初始化项目
context = agent_bay.context.get("user-123-web-app", create=True).context
sync = ContextSync.new(context.id, "/home/wuying/project", SyncPolicy.default())
params = CreateSessionParams(context_syncs=[sync])
session = agent_bay.create(params).session
session.command.execute_command(
    "cd /home/wuying/project && npm init -y && npm install express"
)
session.file_system.write_file(
    "/home/wuying/project/index.js",
    "const express = require('express');\n// ..."
)
agent_bay.delete(session, sync_context=True)
# ---------- 几天后的对话 ----------
session = agent_bay.create(params).session
# node_modules、package.json、index.js 都在，直接继续开发
session.command.execute_command("cd /home/wuying/project && npm start")

手机 App：登录态复用

每次新 Session 都要让 Agent 重新登录 App 很浪费时间。把 App 的登录数据目录持久化，后续 Session 直接恢复已登录状态。

context = agent_bay.context.get("xhs-login", create=True).context
sync = ContextSync.new(
    context.id,
    "/data/data/com.xingin.xhs/files/mmkv",
    SyncPolicy.default()
)
# 首次：完成登录后保存
session = agent_bay.create(CreateSessionParams(context_syncs=[sync])).session
# ... Agent 执行登录流程 ...
agent_bay.delete(session, sync_context=True)
# 以后：Session 一启动就是已登录状态
session = agent_bay.create(CreateSessionParams(context_syncs=[sync])).session

同步策略调优

SyncPolicy.default() 能覆盖绝大多数场景。如果有特殊需求，可以调整细节。更多策略选项参考同步策略最佳实践。

大文件/大量文件场景：默认逐文件上传，文件多了效率不高。切换为打包模式：

from agentbay import UploadPolicy
policy = SyncPolicy.default()
policy.upload_policy = UploadPolicy(auto_upload=True, upload_mode="ARCHIVE")
sync = ContextSync.new(context.id, "/tmp/workspace", policy)

关键数据的手动同步：不想依赖 Session 结束时的自动同步，可以主动触发：

session.file_system.write_file("/tmp/workspace/model.bin", model_data)
# 主动同步，等待完成后再继续
result = session.context_manager.sync()
if result.success:
    print("同步完成")

数据自动过期：临时数据不需要永久保存，设一个过期时间：

from agentbay import RecyclePolicy
policy = SyncPolicy.default()
policy.recycle_policy = RecyclePolicy(lifecycle="7d")

大 Context 加速 Session 启动：如果 Context 数据很大，Session 创建时会等待下载完成才返回。设置 beta_wait_for_completion=False 可以跳过等待，让 Session 先创建起来，Context 在后台继续下载：

context_sync = ContextSync.new(
    context_id=context.id,
    path="/tmp/workspace",
    policy=SyncPolicy.default(),
    beta_wait_for_completion=False
)

需要注意：使用这个选项时，Session 刚创建时挂载路径下的文件可能还没准备好，代码需要容忍短暂的文件缺失。

手动同步支持指定方向：sync() 默认是上传，也可以指定为下载（从 Context 刷新本地数据）：

# 上传本地修改到 Context
session.context_manager.sync(mode="upload")
# 从 Context 下载最新数据到本地
session.context_manager.sync(mode="download")

Browser Context：浏览器状态的专属持久化

前面介绍的 Context 是通用的文件级持久化，什么文件都能存。但浏览器场景有些特殊——Cookie、Local Storage、缓存这些东西散落在浏览器的各种内部目录里，用通用 Context 去挂载这些路径不太方便。

所以 AgentBay 单独提供了 Browser Context，专门用来持久化浏览器状态。它和通用 Context 共用同一套存储后端，但接口更简洁，不需要你关心挂载路径和同步策略的细节。

基本用法

from agentbay import AgentBay, CreateSessionParams, BrowserContext
agent_bay = AgentBay()
# 创建一个 Context 用于存储浏览器数据
context = agent_bay.context.get("my-browser-data", create=True).context
# 用 BrowserContext 包装，关联到 Session
browser_context = BrowserContext(context.id, auto_upload=True)
params = CreateSessionParams(
    image_id="browser_latest",
    browser_context=browser_context
)
session = agent_bay.create(params).session

auto_upload=True 表示 Session 结束时自动把浏览器数据上传回 Context。下次用同一个 Context 创建 Session，Cookie、登录态、浏览器配置都会恢复。

什么时候用 Browser Context，什么时候用通用 Context？

Browser Context：持久化的是浏览器自身的状态（Cookie、Cache、Local Storage、扩展配置等）。适合 Web 自动化、爬虫场景下保持登录态。
通用 Context：持久化的是文件系统中的任意文件。适合保存代码项目、数据文件、配置等。
两者可以同时使用：一个 Session 可以同时挂载通用 Context（存项目文件）和 Browser Context（存浏览器状态）。

典型场景：网站登录态复用

第一次 Session 中通过浏览器完成网站登录，Cookie 被保存到 Browser Context。后续 Session 创建时浏览器直接恢复已登录状态，不需要重新登录。

from agentbay import BrowserOption
# 第一次：登录并保存状态
context = agent_bay.context.get("site-login", create=True).context
browser_ctx = BrowserContext(context.id, auto_upload=True)
session = agent_bay.create(
    CreateSessionParams(image_id="browser_latest", browser_context=browser_ctx)
).session
# 初始化浏览器，通过 Playwright 操作登录
session.browser.initialize(BrowserOption())
endpoint_url = session.browser.get_endpoint_url()
# ... 使用 Playwright 连接 endpoint_url，完成登录操作 ...
# 销毁 Session，浏览器数据自动上传
agent_bay.delete(session, sync_context=True)
# 以后：浏览器直接恢复到已登录状态
session2 = agent_bay.create(
    CreateSessionParams(image_id="browser_latest", browser_context=browser_ctx)
).session
# 浏览器打开目标网站时已经是登录状态

和通用 Context 的用法很像，区别就是创建参数里用 browser_context 而不是 context_syncs，不需要手动指定挂载路径。更详细的用法（包括 Cookie 持久化验证的完整示例）见 Browser Context 文档。

Context 的直接管理

不启动 Session 也能管理 Context 里的文件：

# 列出所有 Context
result = agent_bay.context.list()
for ctx in result.contexts:
    print(f"{ctx.name} ({ctx.id})")
# 列出某个 Context 里的文件
files = agent_bay.context.list_files(context.id, "/")
# 获取文件下载链接（返回预签名 URL）
url_result = agent_bay.context.get_file_download_url(context.id, "notes.txt")
print(url_result.url)
# 获取文件上传链接
upload_result = agent_bay.context.get_file_upload_url(context.id, "input.csv")
print(upload_result.url)
# 清空数据
agent_bay.context.clear(context.id)
# 删除整个 Context
agent_bay.context.delete(context)

需要注意的几件事

sync_context=True 很重要：如果下次 Session 需要最新数据，删除时一定要加这个参数，否则上传可能还没完成 Session 就被销毁了。
Context 按 API Key 和 Region 隔离：同一个名字在不同 API Key 或不同 Region 下是完全独立的 Context，数据不互通。
挂载路径要有写权限：推荐 /home/wuying、/tmp 等目录，某些系统目录可能写入失败。
大数据量用 ARCHIVE 模式：文件数量多或者单文件很大时，打包上传比逐文件上传快很多。

总结

Context 的核心思路很简单：给 Agent 一个跨 Session 的存储空间。创建 Context、挂载到 Session、销毁时同步回去——三步搞定数据持久化。不需要额外搭建存储服务，不需要自己处理文件上传下载，SDK 把脏活都干了。

操作	代码
创建/获取 Context	`agent_bay.context.get("名字", create=True)`
文件持久化（通用 Context）	`ContextSync.new(context_id, 路径, SyncPolicy.default())`
浏览器持久化（Browser Context）	`BrowserContext(context_id, auto_upload=True)`
销毁时保存数据	`agent_bay.delete(session, sync_context=True)`
手动同步	`session.context_manager.sync()`
管理 Context 文件	`agent_bay.context.list_files()` / `get_file_download_url()`

让 AI Agent 过目不忘：无影 AgentBay 跨会话数据持久化实战