agents-cli 状态管理state / session / artifact 三层持久化机制对比【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cliagents-cli是 Google 推出的开源命令行工具与技能套件能把 Claude Code、Codex 等编码助手变成构建 AI Agent 的专家。它的底层依赖 Google ADKAgent Development Kit而 ADK 的状态管理体系正是新手最容易困惑的部分state状态键值、session会话、artifact文件工件三层各司其职持久化程度和生命周期完全不同。本文用一张对比表 源码路径带你看懂这三层机制分别在什么时候记住数据、数据存在哪里、重启后会不会丢并给出生产环境的选型建议。 先搞清全局状态管理在 agents-cli 中的位置agents-cli 本身不直接存数据而是把「创建 → 开发 → 评估 → 部署 → 发布」全流程托管给编码助手执行。状态持久化能力来自它脚手架里内置的 ADK 服务层并通过 Terraform 模板一键生成对应的云资源Cloud SQL、GCS 存储桶等。上图是 agents-cli 构建所依赖的 Google Cloud Agent 技术栈全景会话与工件服务就运行在这条链路之上。 一图看懂state / session / artifact 三层持久化对比维度state状态session会话artifact工件存什么键值对任务步骤、用户偏好、中间结果一次完整对话的上下文与事件流二进制文件PDF、图片、音频生命周期随作用域前缀而定一次对话跨调用按命名空间可跨会话默认开发随 session 服务InMemorySessionService内存InMemoryArtifactService内存生产选项Cloud SQL / Vertex AICloud SQL、Agent Platform Sessions、Agent Engine 托管GCS 存储桶GcsArtifactService重启后取决于所选 session 服务内存实现会丢持久化后端不丢内存实现会丢GCS 不丢版本管理覆盖写支持回滚到指定调用前支持多版本可回读历史版本一句话记忆state 是便签纸session 是便签纸的笔记本artifact 是装文件的保险箱。三者绑定关系是state 挂在 session 上artifact 可按 session 或 user 命名空间归属。️ 第一层state —— 用前缀决定数据活多久ADK 中最常用的状态操作就是读写session.state工具里是tool_context.state。它支持四种作用域前缀决定了键值的持久化范围详见 adk-python.md 的 State Prefixes 章节写法示例作用域通俗解释booking_step当前会话订票流程进行到第 2 步会话结束即失效user:preferred_language用户级跨会话这个用户偏好中文下次再来还认识app:total_queries应用级所有用户全应用累计查询次数这类全局计数temp:intermediate_result仅当前调用函数之间的临时变量用完即弃 新手常见误区以为state里的数据永远都在。实际上默认作用域只有会话级想让数据跨会话存活必须显式加user:或app:前缀。另外 ADK 还支持 Session Rewind——把会话回滚到某次调用之前的状态adk-python.md适合调试或实现撤销功能但它只影响会话级状态不动 app/user 作用域的数据。 第二层session —— 三种后端决定重启后还在吗会话是状态和事件流的容器。agents-cli 在脚手架阶段就帮你把 session 服务的选择做成了显式选项定义在 template.py 中类型说明适用场景in_memory数据在内存无状态、零配置本地开发、原型验证默认值cloud_sqlPostgreSQL 持久化走 Cloud SQL 连接器Cloud Run / GKE 上的生产会话agent_platform_sessions托管会话服务不想自己运维数据库的生产环境选择逻辑在 create.py 中部署目标是Agent Runtime时session 管理由平台自动接管ADK 自动接线VertexAiSessionService无需也无法手动指定类型部署到Cloud Run / GKE时交互式创建会提示你选择上面三种后端非 Python 语言Go / Java / TS目前仅支持内存会话。一个容易忽略的细节脚手架生成的 services.py 把会话服务注册为进程级共享的shared://session意味着 Web 路由、A2A 接口等多入口访问时看到的是同一份会话不会出现从 A 入口建会话、B 入口查不到的灵异问题。 第三层artifact —— 文件工件的版本化保险箱当 Agent 要保存 PDF、生成图片、缓存音频这类二进制内容时就交给 artifact 服务adk-python.md开发环境InMemoryArtifactService()重启即丢仅供联调生产环境GcsArtifactService(bucket_name...)落到 GCS 存储桶命名空间直接命名为report.pdf表示会话级加user:前缀则跨会话持久版本化每次保存生成新版本号可按版本号回读历史版本——这是 state 不具备的能力。在 agents-cli 的部署模板里工件服务由环境变量自动升级设置了LOGS_BUCKET_NAME就走 GCS否则退回内存实现见 agent-runtime.md 的说明无需手写任何胶水代码。 部署选型指南什么时候该上持久化agents-cli 的设计哲学是原型阶段零配置生产阶段一键升级本地原型agents-cli create my-agent默认内存会话跑通逻辑即可别过早引入数据库部署上云agents-cli scaffold enhance . --deployment-target cloud_run或gke按需追加--session-type cloud_sql追求托管部署到 Agent Runtime会话、扩缩容全部交给平台这是官方推荐的最低运维成本路径对比矩阵见 SKILL.md 的 Deployment Target Decision Matrix。 补充如果需求超出三层之外——比如跨所有会话记住用户画像并持续学习——ADK 还提供了Memory Bank记忆库这一长期记忆机制agents-cli 的编码技能里也内置了相应写法参考。❓ 新手常见疑问Q1三层数据会互相覆盖吗不会。state 是 JSON 键值、artifact 是带版本的文件对象两者独立存储只是都挂接在同一 session 之下。Q2内存会话丢数据严重吗开发阶段无所谓上生产后同一用户多实例并发时实例 A 记下了、实例 B 查不到是真实风险这正是cloud_sql或托管会话存在的意义。Q3为什么我的 Go/Java 项目选不了 Cloud SQL当前仅 Python 版 ADK 脚手架支持会话类型选择其他语言会收到黄色警告并自动回退到内存实现create.py。✅ 总结你的场景推荐配置本地原型、快速验证全默认内存 state session artifactCloud Run / GKE 生产--session-type cloud_sql GCS 工件桶托管、少运维部署到 Agent Runtime平台自动接管会话跨会话记忆用户加user:前缀 考虑 Memory Bank掌握「state 管数据、session 管对话、artifact 管文件」这个心智模型你就理解了 agents-cli 状态管理的全部核心。配合官方技能文档 google-agents-cli-adk-code可以让你的编码助手在写 Agent 代码时自动做对持久化选型。【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考