Agent Runtime 为 Agent 集群开启 Agent

员工助手在多轮任务中会持续生成文档、下载资料、修改代码。如果这些文件只保存在容器临时目录中，运行环境重建后就需要重新准备，用户也难以继续之前的工作。
AgentWorkspaces 为 Agent 提供可持久保存、重复挂载的工作区。通过独立的存储声明（PVC），将工作文件的生命周期与运行实例分开：实例可以停止和重建，后续实例继续挂载原工作区、读取已有文件并接着写入。具备相应节点与存储条件时，也可以在不同节点上恢复工作区，减少对原计算节点的依赖。
创建 Agent 集群时会默认安装 AgentWorkspaces，无需单独安装或开启。集群和节点就绪后，即可创建工作区并挂载到 Agent。本文介绍工作区的创建、使用，以及重建后的文件保留验证。
适用场景
场景
使用方式
员工办公助手
为每位用户的助手保留独立工作区，保存资料、报告和任务文件；重建实例后继续处理。
Coding Agent
保存代码、修改结果和构建产物，避免每次启动都重新准备全部工作文件。
多阶段任务
代码生成、检查和后续处理按顺序挂载同一工作区，读取上一阶段的输出。
节点维护与重新调度
在数据完成远端持久化、旧实例释放工作区后，由其他符合条件的节点接续运行。
建议以用户、项目或任务为单位分配工作区。需要相互隔离的 Agent 使用不同 PVC；多阶段任务采用顺序交接，避免多个实例同时修改同一份文件。
功能说明
文件持久化：将需要保留的文件写入挂载目录，运行实例重建后继续使用原 PVC。
工作区复用：实例重新启动时复用已有工作文件，减少重复下载和初始化；实际收益取决于文件规模、缓存和业务初始化过程。
跨节点恢复：工作区可从已安全持久化的远端数据恢复到其他支持该组件的节点。
Kubernetes 接入：通过 StorageClass、PVC 和容器挂载路径使用工作区，业务程序仍通过文件系统读写。
工作区保存的是文件。进程内存、未写入文件的会话状态和正在执行的程序，不会因重新挂载工作区自动恢复。应用需要自行保存任务进度，并在启动时读取。
开始前准备
1. 已按 创建集群和节点池 准备 Agent 集群，集群和目标节点已就绪，并拥有相应的存储和工作负载管理权限。
2. 确定 Agent 所在命名空间，以及需要持久保存的应用目录。
3. 规划每个工作区的容量、挂载路径和数据保留方式。
AgentWorkspaces 已随集群创建默认安装，后续从创建工作区开始操作。
步骤一：创建工作区
以下以员工助手为例：工作区命名为 assistant-workspace，容器内挂载到 /workspace。名称和挂载路径均可根据业务调整。
1. 在关联 TKE 集群的存储管理中创建 PVC，选择助手所在命名空间。
2. 填写 PVC 名称 assistant-workspace，选择集群提供的工作区 StorageClass（默认名称为 awv-btrfs），并设置满足任务需要的容量。
3. 选择组件支持的访问模式。常用的 ReadWriteOnce 表示卷可由单个节点读写，不等于只允许一个 Pod 写入；业务编排仍应确保同一工作区只有一个写入方。
4. 提交创建，记录 PVC 名称、命名空间和回收策略。
组件默认采用延迟绑定（WaitForFirstConsumer）。尚未创建使用该 PVC 的工作负载时，PVC 处于 Pending 可以是正常现象；创建消费者后再检查绑定结果。
步骤二：为 Agent 挂载工作区
在工作负载创建或编辑页面配置存储卷。
配置项
示例与说明
命名空间
与 PVC 相同。
存储卷来源
选择已有 PVC assistant-workspace。
容器挂载路径
/workspace；需要保留的文件必须写入此目录。
读写方式
需要生成和修改文件时选择可写挂载。
实例数量
示例使用一个实例，防止多个写入方竞争同一工作区。
启动与更新方式
更新时先停止旧写入方、释放挂载，再启动新实例；检查滚动更新策略是否会同时运行新旧实例。
应用的数据目录应与挂载路径一致。例如，将报告输出到 /workspace/reports、代码保存到 /workspace/project。仅挂载工作区不会自动迁移容器其他目录的数据，也不会自动导入原有 CBS、CFS 或临时目录中的文件。
启动后检查 Pod 和 PVC 状态，并在容器终端确认挂载目录可读写。使用非 root 用户运行时，还需确认目录属主、用户组和权限满足应用要求。
步骤三：验证重建后继续使用文件
首次接入时，先用独立测试实例完成以下验证。示例要求容器提供 /bin/sh、cat 和 sync，且 /workspace 可写。
1. 在控制台打开测试容器终端，执行：
printf '%s\\n' 'assistant-round-1' > /workspace/agc-workspace-check.txt
sync
cat /workspace/agc-workspace-check.txt
2. 确认输出为 assistant-round-1，记录当前 Pod、节点和 PVC。
3. 在控制台停止或重建测试实例，保留原 PVC。确认旧实例退出、挂载释放；新实例继续选择同一命名空间中的 assistant-workspace。
4. 新实例就绪后，在容器终端读取旧文件并追加内容：
cat /workspace/agc-workspace-check.txt
printf '%s\\n' 'assistant-round-2' >> /workspace/agc-workspace-check.txt
sync
cat /workspace/agc-workspace-check.txt
预期先看到第一轮内容，追加后看到两行记录。不要在容器启动命令中重新创建该文件，否则无法判断是否保留了原文件。需要更完整的验证步骤，可参考 实践：重建环境后继续使用工作文件。
本次验证若仍在同一节点运行，只能证明同节点重建后的文件复用。验证跨节点接续时，应先停止写入并确认数据完成远端持久化、旧节点释放工作区，再将测试实例调度到另一个具备工作区组件的节点，核对文件内容和新写入结果。
工作区数据会从节点提交到远端存储。容器内执行 sync 不等于所有数据已完成远端持久化；原节点突然不可恢复时，不能把尚未安全提交的本地写入视为已可跨节点恢复。不要通过强制删除挂载记录或修改存储状态来跳过交接。
如何评估使用效果
分别记录工作区挂载完成、Agent 可接收任务和首次任务完成的时间，同时检查文件是否完整、是否可以继续写入。比较首次创建、同节点重建和跨节点恢复时，保持文件规模、实例规格、运行时和业务命令一致，并记录缓存状态。
工作区准备时间只占 Agent 启动的一部分。镜像拉取、语言环境初始化、模型连接等阶段需分别观察；可结合 为 Agent 集群开启镜像加速 减少镜像准备等待。
常见问题
现象
检查与处理
找不到工作区 StorageClass
确认集群已完成创建，检查实际 StorageClass 名称；集群就绪后仍缺失时，联系技术支持排查默认组件状态，无需自行重复安装。
PVC 一直 Pending
先检查是否等待消费者；已有消费者时检查事件、组件状态、授权和存储资源。
Pod 无法挂载工作区
检查实际调度节点、节点组件、PVC 引用和旧实例是否仍占用工作区。
挂载成功但写入被拒绝
检查只读设置、容器 UID/GID 和目录权限。
重建后文件不见了
检查是否复用了原 PVC，以及文件是否写入实际挂载目录；停止继续写入，避免覆盖排查线索。
跨节点恢复等待较久
检查旧节点的数据提交、挂载释放、COS 网络与授权，以及目标节点状态。
存量数据没有出现在工作区
新建 PVC 不会自动迁移旧数据；需要单独安排复制、停写切换及内容校验。

为 Agent 集群开启 AgentWorkspaces

本页目录：

适用场景

功能说明

开始前准备

步骤一：创建工作区

步骤二：为 Agent 挂载工作区

步骤三：验证重建后继续使用文件

如何评估使用效果

常见问题

场景	使用方式
员工办公助手	为每位用户的助手保留独立工作区，保存资料、报告和任务文件；重建实例后继续处理。
Coding Agent	保存代码、修改结果和构建产物，避免每次启动都重新准备全部工作文件。
多阶段任务	代码生成、检查和后续处理按顺序挂载同一工作区，读取上一阶段的输出。
节点维护与重新调度	在数据完成远端持久化、旧实例释放工作区后，由其他符合条件的节点接续运行。

配置项	示例与说明
命名空间	与 PVC 相同。
存储卷来源	选择已有 PVC `assistant-workspace`。
容器挂载路径	`/workspace`；需要保留的文件必须写入此目录。
读写方式	需要生成和修改文件时选择可写挂载。
实例数量	示例使用一个实例，防止多个写入方竞争同一工作区。
启动与更新方式	更新时先停止旧写入方、释放挂载，再启动新实例；检查滚动更新策略是否会同时运行新旧实例。

现象	检查与处理
找不到工作区 StorageClass	确认集群已完成创建，检查实际 StorageClass 名称；集群就绪后仍缺失时，联系技术支持排查默认组件状态，无需自行重复安装。
PVC 一直 Pending	先检查是否等待消费者；已有消费者时检查事件、组件状态、授权和存储资源。
Pod 无法挂载工作区	检查实际调度节点、节点组件、PVC 引用和旧实例是否仍占用工作区。
挂载成功但写入被拒绝	检查只读设置、容器 UID/GID 和目录权限。
重建后文件不见了	检查是否复用了原 PVC，以及文件是否写入实际挂载目录；停止继续写入，避免覆盖排查线索。
跨节点恢复等待较久	检查旧节点的数据提交、挂载释放、COS 网络与授权，以及目标节点状态。
存量数据没有出现在工作区	新建 PVC 不会自动迁移旧数据；需要单独安排复制、停写切换及内容校验。