> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Studio 智能体工作台

AgentKit Studio 使用与 VeADK Frontend 相同的服务和完整界面，提供对话、搜索、历史会话、资源库、视频创作、自动化集成，以及智能体创建、测试、部署和管理功能，启动后默认进入对话页面。智能体工作台以画布形式呈现多智能体拓扑，并集中展示已部署 Runtime 的版本与部署状态，支持在同一 Runtime 上迭代更新。

当前可通过自定义配置、智能模式、代码包部署或从存量项目迁移创建项目。你可以预览和编辑生成的文件，启动临时测试进程，将项目下载为 ZIP，或者部署到 AgentKit。Studio 还支持选择云端 Runtime、多来源技能、多模态会话、自动化集成，以及集中查看和重试部署任务。

<Note>
  在工作台中选择智能体时，Studio 会先完成会话列表、智能体信息、能力和自动评测状态的加载，再切换可见选中项，避免切换过程中出现中间加载状态。
</Note>

<Note>
  发送消息或调试运行智能体时，Studio 通过流式接口接收回复。若 30 秒内未收到首个流式事件，Studio 会中止该流并提示检查共享公网出口等网络配置后重试，避免请求长时间无响应地挂起。
</Note>

## 在本地启动

从智能体目录的上一级目录运行：

```bash lines theme={null}
export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

veadk studio --agents-dir ./agents --open
```

`--open` 会在服务就绪后打开 `http://127.0.0.1:8000`。未传入该选项时，Studio 只启动服务，不自动打开浏览器。

火山引擎凭证用于工作台中的模型、云资源查询和 AgentKit 部署。生产环境应通过环境变量或密钥管理服务提供凭证，不要把凭证写入项目文件。

使用 BytePlus 作为云服务商时，传入 `--provider byteplus`，并通过 `BYTEPLUS_ACCESS_KEY`、`BYTEPLUS_SECRET_KEY` 和可选的 `BYTEPLUS_SESSION_TOKEN` 环境变量提供凭证；Runtime 列表默认查询的地域为 `BYTEPLUS_REGION` 或 `ap-southeast-1`。未显式指定 `--provider` 时，依次读取 `AGENTKIT_CLOUD_PROVIDER` 与 `CLOUD_PROVIDER` 环境变量确定云服务商，均未设置时使用火山引擎。

## Studio 持久化存储

视频创作、自动评测优化、智能开发项目版本和产物持久化等 Studio 能力需要持久化对象存储来保存参考素材、生成结果、优化项快照和对话产物。Studio 使用 TOS 作为持久化存储后端。未单独配置发布存储时，技能发布也会复用持久化存储桶，详见[技能发布存储](#技能发布存储)。

### 云端部署

`veadk studio deploy` 部署时会自动创建或复用名为 `veadk-studio-<账号 ID>` 的私有 TOS 存储桶，存储地域与部署地域一致。该桶名由云账号 ID 确定，使重复部署幂等。管理员也可以通过 `VEADK_STUDIO_TOS_BUCKET` 环境变量显式指定已有存储桶名称；指定时该存储桶必须已存在于部署地域，否则部署会报错。

一个存储桶创建在某个地域后，不能以同名在其他地域重复创建。切换部署地域时，如果目标地域已存在同名存储桶则复用，否则需要显式指定该地域可用的存储桶。

<Warning>
  部署过程中创建 TOS 存储桶使用部署者的火山引擎凭证。已部署的 Studio 使用绑定 IAM Role 的临时凭证访问存储桶，不会向浏览器下发 TOS 凭证。
</Warning>

### 本地启动

本地启动时，通过以下环境变量配置持久化存储：

| 环境变量 | 默认值 | 说明 |
| :- | :- | :- |
| `VEADK_STUDIO_TOS_BUCKET` | — | Studio 使用的 TOS 存储桶名称。 |
| `VEADK_STUDIO_TOS_REGION` | — | 存储桶所在地域。 |

两个变量均需设置，Studio 才会启用持久化存储。未配置时，依赖持久化存储的功能（如视频参考素材上传）会被禁用，并在对应位置显示「管理员未配置持久化存储」；纯文本功能不受影响。本地 Studio 使用已配置的火山引擎或 BytePlus AK/SK 访问存储桶。

<Note>
  旧的 `VEADK_VIDEO_TOS_*` 和 `DATABASE_TOS_*` 环境变量仍作为临时兼容回退：当 `VEADK_STUDIO_TOS_BUCKET` 和 `VEADK_STUDIO_TOS_REGION` 均未设置时，Studio 会尝试从旧变量读取存储桶、地域和端点。新部署只需配置 `VEADK_STUDIO_TOS_*` 两个变量。
</Note>

<Note>
  使用火山引擎作为云服务商且未自定义 TOS 端点时，Studio 会在首次访问 TOS 时探测默认的公网端点（`tos-<地域>.volces.com`）。若探测遇到传输层网络错误，Studio 自动切换到对应的内网端点（`tos-<地域>.ivolces.com`），后续访问继续使用所选端点。鉴权失败、权限不足等非网络类 TOS 服务错误不会触发回退。浏览器端获取的签名 URL 始终使用公网端点，确保外部可访问。BytePlus 和自定义端点不受此机制影响。
</Note>

Studio 对象使用用户优先的版本化布局，路径格式为 `veadk-studio/v1/users/<编码用户 ID>/<命名空间>/<范围>/<资源 ID>/`。视频参考素材使用 `video/<素材角色>/<素材 ID>/` 命名空间，存储在该路径下的文件内容及 `metadata.json`。

自动评测生成的优化项快照存储在 `veadk-studio/v1/evaluation-optimizations/<Runtime ID>/<应用名>.json` 路径下，每个 Runtime 应用保留最新一份快照。

智能开发项目版本存储在 `veadk-studio/v1/users/<编码用户 ID>/intelligent-development/projects/<项目 ID>/versions/<版本 ID>/` 路径下，每个版本包含不可变的源码压缩包、验证报告和提交标记。查看、下载和部署已保存的版本不依赖原始 Sandbox；项目摘要仅作为索引。

## 自定义品牌

使用 `--site-title` 设置最多 16 个字符的系统名称，使用 `--site-logo` 指定本地图片或 HTTP(S) 图片 URL。Logo 会用于侧边栏、登录页和浏览器 favicon。浏览器页面标题会随当前界面动态变化：新会话首页只显示系统名称；进入对话后显示会话名称；进入自动化、系统信息、创建智能体、资源库、搜索等功能页时，标题为「系统名称 - 页面名称」。省略 `--site-title` 时使用默认名称 `AgentKit Studio`。

```bash lines theme={null}
veadk studio \
  --site-title "火山助手" \
  --site-logo "./logo.png"
```

Logo 最大 5 MB，支持 PNG、JPEG、GIF、WebP、AVIF 和 ICO。也可以通过 `VEADK_SITE_TITLE` 与 `VEADK_SITE_LOGO` 环境变量配置。部署到 VeFaaS 时可使用相同参数；网络图片会在部署时下载并打包，部署后的站点不依赖原图片 URL。

## 创建智能体

1. 在「智能体」页面中点击「创建智能体」，在创建菜单中选择「从 0 快速创建」进入自定义配置，选择「智能模式」用自然语言描述目标由 Codex 构建，选择「从代码包添加和部署」上传已有项目，或选择「从存量项目迁移」将 LangChain、Dify 等框架的项目迁移至 VeADK。
2. 配置模型、系统提示词、工具、记忆和知识库，并从 Skill Hub、本地上传或 AgentKit SkillSpace 添加技能。多智能体项目还可以配置顺序、并行、循环或 A2A 节点，并在画布中查看和编排智能体拓扑。
3. 检查生成的项目文件，并在受限的临时进程中测试运行；需要离线使用时下载 ZIP。
4. 在「优化」步骤中按需为智能体启用 Harness Sidecar 优化项；该步骤为可选，不勾选时不启动优化。
5. 在「环境」步骤中选择预构建的运行环境镜像，或使用 AgentKit 默认运行环境；该步骤为可选。
6. 选择部署到 AgentKit，在工作台中观察构建镜像、部署和发布进度。部署完成后，智能体以已发布状态出现在工作台，后续可在同一 Runtime 上更新。

<Note>
  自定义创建中的资源选择器（如智能体中心、知识库集合）支持按关键词本地筛选：在下拉框中输入文字即可过滤当前已加载的选项。筛选只作用于已经加载的列表，不会改变地域、项目范围或刷新逻辑。
</Note>

<Note>
  部署进入构建镜像阶段时，Studio 会在部署进度卡片中实时展示构建日志。日志在服务端完成凭据脱敏与篇幅截断后下发到浏览器，面板显示同步状态（同步中、已同步或读取失败）与行数，可展开、收起并复制内容；日志支持语法高亮，并默认自动滚动到末尾，手动向上滚动后暂停跟随，回到底部时恢复跟随；构建失败时，Studio 会重试同步最终构建日志并标记为失败状态，便于在日志末尾定位真实失败原因。日志同步依赖部署所用的火山引擎凭证，无法读取时面板显示失败状态，不影响部署继续进行。自定义创建和代码包部署均支持该能力。
</Note>

<Note>
  构建镜像已提交但暂时无法确认最终状态时，Studio 将该阶段标记为「构建状态待确认」，提示稍后在 Code Pipeline 查看构建结果，并禁用重试按钮以避免重复部署。此前这种情况会显示为「部署失败」。
</Note>

<Note>
  部署进行期间，工作台详情页聚焦于部署进度：保留智能体标题并展示可滚动的部署进度面板，同时隐藏其余详情标签与内容；部署结束后恢复显示常规详情标签。自定义创建、代码包部署与更新已部署智能体均遵循该行为。
</Note>

<Note>
  部署到 AgentKit 时，根智能体的描述会自动整理为符合 Runtime 规范的单行描述（至多 255 字节，去除换行、控制字符与不安全符号）；完整描述保留在项目中，仅用于生成 Runtime 描述。若整理后的描述被 Runtime 拒绝，Studio 会去掉描述后重试创建，不影响其他配置。
</Note>

<Note>
  智能体的系统提示词（`instruction`）至多 40,000 个字符，超出时生成或测试项目会报错。
</Note>

<Note>
  系统提示词编辑器提供所见即所得的 Markdown 编辑能力。当内容包含编辑器无法解析的 Markdown 语法时，编辑器自动切换为纯文本模式，仍可正常编辑与保存。
</Note>

### 模型选择

配置 LLM 智能体时，可在模型选择器中浏览当前账号在火山方舟已开通的模型，并选择目标模型。模型列表由 Studio 服务端从火山方舟获取，仅展示支持智能体调用的 LLM 和 VLM 模型，包含模型名称、展示名称、厂商和开通状态；已停用的模型不会出现在列表中。模型列表有缓存，需要获取最新状态时使用刷新按钮。

模型来源分为以下两类，Studio 根据模型 API 地址是否为当前云服务商的官方 Ark 端点自动判断：

| 模型来源 | Studio 提供的凭据 | 调试运行 | 部署 |
| :- | :- | :- | :- |
| Ark（留空或使用当前云的官方 Ark 地址） | 使用官方 Ark 地址与 Studio 管理的 Ark API Key | 支持 | 无需额外填写 |
| 自定义（非官方 Ark 端点） | 不提供凭据 | 不支持 | 需在发布页填写该智能体的 API Key |

<Warning>
  调试运行不支持自定义模型地址。使用非官方 Ark 端点的智能体在调试时会报错，需改用当前云的官方 Ark 地址，或先部署再通过 Runtime 测试。
</Warning>

使用 Ark 模型时，Studio 服务端会从当前账号的火山方舟 API Key 列表中选择一个用于调试运行和部署。默认选择与 `MODEL_AGENT_API_KEY_NAME` 匹配的 API Key，未匹配时使用列表中的第一个 Key。也可以在部署配置区手动选择指定的 Ark API Key：所选 Key 的明文由 Studio 服务端解析并注入运行环境，不会下发到浏览器。列表为空时需先在火山方舟控制台创建 API Key。

使用自定义模型地址时，发布页会在环境变量区域显示「自定义模型凭据」分组，为每个使用自定义地址的智能体提供必填的 API Key 输入框，可选项还包括模型提供方和模型 API 地址。输入的凭据仅用于本次发布，不保存在草稿中。生成的项目代码通过以下环境变量读取对应配置，并在 `.env.example` 中以占位符形式列出：

| 环境变量 | 说明 |
| :- | :- |
| `CUSTOM_MODEL_<智能体名称>_PROVIDER` | 模型提供方（如 `openai`），仅在填写时生成。 |
| `CUSTOM_MODEL_<智能体名称>_API_BASE` | 模型 API 地址，仅在填写时生成。 |
| `CUSTOM_MODEL_<智能体名称>_API_KEY` | 模型 API Key，必填。 |

### 配置部署参数

在部署配置区选择发布区域和网络模式，并按需设置 Runtime 实例数。实例设置仅在创建新 Runtime 时出现，更新已有 Runtime 时不显示。更新已有 Runtime 时，发布区域和网络模式从现有 Runtime 读取并保持不变。

| 配置项 | 默认值 | 说明 |
| :- | :- | :- |
| 发布区域 | `cn-beijing` | Runtime 部署地域。 |
| 网络模式 | 公网 | 可选公网、VPC 或公网 + VPC；使用 VPC 时需填写 VPC ID。 |
| 最小实例数 | `1` | Runtime 的最小实例数。 |
| 最大实例数 | `5` | Runtime 的最大实例数；使用 in-memory 短期记忆时默认为 `1`。 |
| 访问鉴权 | API Key | 创建新 Runtime 时的访问鉴权方式。可选 API Key 或 VeIdentity 用户池；更新已有 Runtime 时保留其当前鉴权方式。 |
| 自动创建评测集 | 开启 | 部署成功后自动为该智能体创建 Good Case 和 Bad Case 评测集；关闭则跳过此步骤。创建失败时在部署结果中显示警告，不影响已部署的 Runtime。 |

实例数必须为大于 0 的整数，且最小实例数不能大于最大实例数。当智能体的短期记忆后端为 `local`（in-memory）或未配置时，Studio 会将最大实例数默认设为 1，并提示多实例、进程重启或滚动发布可能导致会话丢失，建议改用基于数据库的持久化短期记忆存储。部署进度会根据实例范围显示相应阶段：当实例范围不是默认的 1～5 时，在创建 Runtime 后增加「更新实例配置」阶段。

创建新 Runtime 时，Studio 会根据根智能体名称自动生成 Runtime 名称（由英文字母、数字、下划线和连字符组成，长度 4–64 个字符），确保智能体与 Runtime 的命名一致且可预测。Runtime 名称可手动修改，Studio 会在部署前校验名称格式并检查是否与当前地域已有的 Runtime 重名；名称重复时部署会报错并提示修改。部署结果中会同时返回智能体名称和 Runtime 名称。

创建新 Runtime 时，访问鉴权默认为 API Key；如需改用用户身份验证，可在部署配置区选择 VeIdentity 用户池。Studio 服务端使用自身配置的火山引擎凭证加载当前账号可见的用户池列表，浏览器不接触凭证。列表中会标记当前 Studio 登录所用的用户池：选择该用户池时，Studio 会把登录后验证的 JWT 转发给 Runtime，调用方无需另行获取令牌；选择其他用户池时，调用方需使用该用户池签发的 JWT 访问 Runtime。用户池所在地域通过 `VEIDENTITY_REGION` 环境变量确定。火山引擎模式下未设置 `VEIDENTITY_REGION` 时，依次回退到 `REGION` 环境变量与默认地域 `cn-beijing`；BytePlus 模式固定为 `ap-southeast-1`。

### 配置构建资源

部署到 AgentKit 时，Studio 使用以下云资源完成镜像构建与发布：

* **TOS 存储桶**：存放源代码包，供云端构建服务拉取。
* **容器镜像仓库（CR）**：存储构建产物镜像，包含实例、命名空间和镜像仓库。
* **CodePipeline**：管理云端构建流水线，包含 Workspace 和 Pipeline。

每类资源支持三种配置方式：

| 配置方式 | 说明 |
| :- | :- |
| 自动创建 | 部署时自动创建所需资源。资源名称由 Studio 按账号 ID 和部署地域自动生成，部署完成后所选资源记录在 Runtime 标签中。 |
| 指定名称 | 输入资源名称，部署时按该名称创建或复用资源。 |
| 选择已有 | 从当前账号的已有资源中选择，Studio 服务端使用自身配置的火山引擎凭证加载资源列表。 |

默认全部使用「自动创建」。选择「指定名称」或「选择已有」时，需填写或选择完整的资源信息；TOS 需指定存储桶，CR 需同时指定实例、命名空间和镜像仓库，CodePipeline 需指定 Workspace 和 Pipeline，缺项会在部署前校验失败并提示。

<Note>
  构建资源配置仅在创建新 Runtime 时出现。更新已有 Runtime 时，Studio 从 Runtime 标签读取上次部署所选资源并保持不变，不显示资源配置区。
</Note>

自动创建模式下各资源的名称规则如下：

| 资源 | 自动创建名称 |
| :- | :- |
| TOS 存储桶 | `agentkit-platform-{账号 ID}`；非北京地域附加地域后缀 |
| CR 实例 | `agentkit-platform-{账号 ID}` |
| CR 命名空间 | `agentkit` |
| CR 镜像仓库 | `{智能体名称}-{随机字符}` |
| CodePipeline Workspace | `agentkit-cli-workspace` |
| CodePipeline Pipeline | `{智能体名称}-{随机字符}`（与 Runtime 同名） |

账号 ID 和随机字符在部署时按当前云账号生成，页面仅展示名称模板。

选择「选择已有」时，Studio 服务端使用自身配置的火山引擎凭证加载当前账号在所选地域下的已有资源列表。TOS 存储桶和 CR 资源按名称展示并选择；CodePipeline Workspace 按 ID 选择，选中 Workspace 后加载其中的 Pipeline，仅展示与 AgentKit 构建流水线兼容的条目。列表支持按名称搜索和分页加载，加载失败时可重试。

<Warning>
  选择已有资源前，确认所选 TOS 存储桶、CR 仓库和 CodePipeline 处于可用状态且当前凭证有权访问。使用不兼容的 CodePipeline 会导致构建失败。
</Warning>

| 现象 | 检查方法 |
| :- | :- |
| 资源列表为空 | 确认当前账号在所选地域已创建对应资源，且凭证有查看权限。 |
| 资源列表加载失败 | 检查 Studio 登录状态、网络连通性和凭证权限，然后重试。 |
| 部署时提示资源校验失败 | 检查所选或所填资源是否完整，例如 CR 需同时指定实例、命名空间和镜像仓库。 |

### 配置智能体优化

自定义创建在「调试」与「环境」之间增加了「优化」步骤，用于为智能体启用 Harness Sidecar 优化。Harness Sidecar 在独立的受控运行时中执行智能体增强行为，应用进程本身不加载相关插件实现。

<Note>
  Harness Sidecar 优化仅支持火山引擎账号。BytePlus 账号暂不支持优化项，保持优化项为空即可继续部署，普通 BytePlus 智能体不受影响。
</Note>

在「优化」步骤中先选择优化场景，再按需勾选优化组件：

| 优化场景 | 适用情况 | 默认勾选的组件 |
| :- | :- | :- |
| 自定义 | 按需选择组件，不勾选时不启动 Sidecar | — |
| 运维场景 | 运维诊断、数据库、日志与监控 MCP | 上下文治理、回答校验与修复、Goal 任务控制、MCP 稳定性治理 |

选择「运维场景」时会自动加载 SQL 只读保护。优化组件按用途分为三组：

| 分组 | 组件 | 作用 |
| :- | :- | :- |
| 提升回答质量 | 上下文治理 | 治理上下文组装、任务锚定与上下文预算。 |
| 提升回答质量 | 回答校验与修复 | 校验证据与回答，失败时执行修复或告警。 |
| 降低运行成本 | 上下文与结果压缩 | 压缩长上下文与大型工具结果，降低 Token 成本。 |
| 增强运行稳定性 | Goal 任务控制 | 管理 Goal 任务的进度、续跑与结束条件。 |
| 增强运行稳定性 | MCP 稳定性治理 | 治理连接、超时、空结果、大返回与调用预算，默认包含 SQL 只读保护。 |

启用优化项后，发布步骤会要求补充所依赖的运行时配置：

* 勾选「上下文治理」「上下文与结果压缩」「回答校验与修复」或「Goal 任务控制」且使用火山方舟模型时，需要补充模型网关配置。Studio 自动填充模型提供方、模型 API 地址与模型名称，Ark API Key 由所选 API Key 注入，无需手动填写。
* 勾选「MCP 稳定性治理」时，Studio 从先前在「添加 MCP 工具」中配置的 HTTP MCP 工具自动注入 `MCP_URLS` 与 `MCP_API_KEY`，无需手动填写。至少需要配置一个使用 HTTP 传输的 MCP 工具，并提供有效的服务地址与 Bearer Token；多个 HTTP MCP 工具须使用同一共享凭证。不满足上述条件时，发布步骤会提示返回「添加 MCP 工具」补充配置后再重新发布。stdio 传输的 MCP 工具不支持 MCP 稳定性治理。

<Warning>
  启用 Harness Sidecar 优化后，相关增强行为在受控运行时中执行，会访问模型与 MCP 网关。请确认所配置的模型凭据、MCP 网关地址与访问范围符合业务的数据处理与安全要求。
</Warning>

### 配置云上环境

自定义创建的生命周期依次为「架构」「调试」「优化」「环境」「发布」五个步骤。「环境」步骤位于优化与发布之间，用于选择预构建的运行环境镜像。该步骤为可选：选择「默认环境」时，部署使用 AgentKit 默认镜像构建，生成的项目中不包含 `Dockerfile`。

在「环境」步骤的下拉列表中选择已构建成功的运行环境。列表展示环境名称、操作系统、Python 版本和构建状态（准备中、排队中、构建中、扫描中、可用或构建失败）；仅构建状态为「可用」的环境可选。选中后，部署时以该环境镜像作为基础镜像构建智能体镜像，所选环境版本固定到此次部署。未选择环境时使用 AgentKit 默认运行环境。

<Note>
  运行环境需要在[工作区](#工作区)页面的「环境」标签中预先创建并完成镜像构建。构建状态为「可用」后，该环境会出现在「环境」步骤的下拉列表中。详见[管理运行环境](#管理运行环境)。
</Note>

## 工作区

Studio 侧边栏提供「工作区」入口，用于将可复用的运行环境按用途组织为工作区。一个工作区可以包含多个环境，同一个环境也可以加入多个工作区；删除工作区只会删除组合关系，不会删除环境本身。智能体的创建与部署仍直接选择具体环境及其构建版本，工作区仅用于组织和管理环境。

工作区页面提供「工作区」和「环境」两个标签页，可在两者之间切换。工作区列表展示每个工作区的名称、描述、包含的环境数量和可用环境数量；点击「管理」进入工作区详情，可在其中添加或移除环境。每个环境卡片同时展示引用该环境的工作区数量。

<Note>
  工作区元数据保存在与环境相同的 Studio 私有 TOS 存储桶中。工作区需要管理员配置持久化存储后才能使用。未配置持久化存储时，工作区相关功能不可用。
</Note>

<Note>
  被工作区引用的环境不能直接删除。删除环境前需要先从引用该环境的所有工作区中移除该环境。
</Note>

## 管理运行环境

在「工作区」页面的「环境」标签中创建、管理和构建可复用的运行环境。运行环境是一份包含操作系统、Python 版本、命令行工具、技能和 Dockerfile 的配置定义，构建后生成容器镜像，可在部署智能体时作为基础镜像选择。环境定义、生成的 Dockerfile、构建版本、日志元数据和镜像地址保存在 Studio 私有 TOS 存储桶中。

<Note>
  环境管理需要管理员配置持久化存储后才能使用。未配置持久化存储时，环境相关功能不可用。
</Note>

### 创建运行环境

在「环境」标签中点击「创建环境」后，选择创建方式：

| 创建方式 | 说明 |
| :- | :- |
| 自定义配置 | 选择操作系统、Python 版本、命令行工具和技能，由 Studio 自动生成 Dockerfile；可在「描述文件」标签中查看和编辑生成内容。 |
| 上传 Dockerfile | 直接上传已有的 Dockerfile 文件，跳过工具和技能选择；上传后可继续编辑文件内容。 |

两种方式均需填写环境名称和描述。

#### 自定义配置

选择「自定义配置」后，填写以下配置项：

| 配置项 | 可选值 | 说明 |
| :- | :- | :- |
| 环境名称 | 自由文本，至多 128 个字符 | 环境的唯一标识名称。 |
| 描述 | 自由文本，至多 2000 个字符 | 环境用途说明。 |
| 操作系统 | Ubuntu 22.04、Ubuntu 24.04 | 基础镜像的操作系统版本。 |
| Python 版本 | Python 3.10、Python 3.12 | 镜像中的 Python 版本。 |
| 命令行工具 | 见下表 | 预装到镜像中的官方工具，按需勾选。 |
| 技能 | Skill Hub、本地上传、AgentKit SkillSpace | 预装到镜像中的技能，至多 20 个。 |
| Dockerfile | 自动生成或自定义 | 构建镜像使用的 Dockerfile 内容。 |

选择命令行工具时，可从以下官方工具中按需勾选，所选工具会被预装到环境镜像中：

| 工具 | 分类 | 说明 |
| :- | :- | :- |
| lark-cli | 工具 | 飞书开放平台命令行工具。 |
| pandoc | 工具 | 文档格式转换工具。 |
| opencli | 工具 | 将网站与桌面应用转换为命令行工具。 |
| uv | 效率 | 快速 Python 包与项目管理器。 |
| ripgrep | 效率 | 高性能文本检索工具。 |
| jq | 效率 | JSON 查询与转换工具。 |
| GitHub CLI | 效率 | 在终端中管理 GitHub 工作流。 |
| Playwright | 浏览器自动化 | 浏览器自动化与端到端测试。 |
| Chromium | 浏览器自动化 | 无头浏览器运行时。 |
| Git | 系统与媒体 | 代码版本管理。 |
| curl | 系统与媒体 | 网络请求与文件下载。 |
| FFmpeg | 系统与媒体 | 音视频转码与处理。 |
| ImageMagick | 系统与媒体 | 图片转换与批处理。 |

创建或保存环境时，Studio 根据操作系统、Python 版本和所选工具自动生成 Dockerfile。未提供自定义 Dockerfile 时，使用自动生成的版本。镜像基于所选操作系统的官方 Ubuntu 镜像，安装 Python 运行时、所选工具的系统依赖，并预装 VeADK 运行时依赖。火山引擎构建使用火山引擎 APT 镜像、阿里云 PyPI 镜像、华为云 Python 源码镜像和 npmmirror 的 Playwright 浏览器镜像；BytePlus 构建使用对应的官方源。跨版本 Python 组合（如 Ubuntu 22.04 + Python 3.12）使用固定补丁版本的源码编译，不依赖 GitHub 托管的二进制文件。

<Note>
  生成的 Dockerfile 不包含任何访问密钥或凭据。工具所需的令牌等凭据应在部署后通过运行时环境变量提供，不要写入 Dockerfile。
</Note>

<Warning>
  请勿在 Dockerfile 中写入访问密钥、令牌或其他凭据。Dockerfile 会随项目一起提交到云端构建服务，任何能访问构建产物的人都可能读取其中的内容。
</Warning>

#### 上传 Dockerfile

选择「上传 Dockerfile」后，通过拖拽或点击上传区域选择本地 Dockerfile 文件。上传后可在内容预览区域继续编辑文件内容。

上传的 Dockerfile 须满足以下条件：

| 校验项 | 要求 |
| :- | :- |
| 文件大小 | 至多 128 KiB |
| 内容 | 不能为空 |
| 指令 | 必须包含 `FROM` 指令 |

<Note>
  上传 Dockerfile 时不再选择操作系统、Python 版本、命令行工具和技能；这些配置由上传的文件内容决定。环境名称和描述仍需填写。
</Note>

### 构建环境镜像

创建或保存环境后，点击「构建」启动异步镜像构建。Studio 将构建上下文上传到 TOS 存储桶，通过 CodePipeline 执行构建流水线，并将结果镜像推送到 Container Registry。构建过程分为准备、排队、构建、扫描等阶段，最终状态为「可用」或「构建失败」。

构建完成后，环境列表中展示最新版本的构建状态和镜像地址。可在环境详情页查看构建步骤、进度和日志。日志支持语法高亮，并默认自动滚动到末尾，手动向上滚动后暂停跟随，回到底部时恢复跟随。构建失败时，日志末尾展示错误信息，便于定位失败原因。

<Note>
  首次构建环境镜像时，Studio 自动创建或复用托管的 CodePipeline Workspace、Pipeline 和 Container Registry 资源。使用账号级默认 TOS 存储桶时，Container Registry 复用账号的 `agentkit-cli-<账号 ID>` 实例，并在其中创建 `runtime-environments/base-images` 仓库。
</Note>

### 环境构建资源

部署 Studio 时，可通过以下标志指定已有的环境构建资源：

```bash lines theme={null}
veadk studio deploy \
  --vefaas-app-name <app-name> \
  --environment-cp-workspace <workspace-id-or-name> \
  --environment-cr-repository <registry/namespace/repository>
```

两项可独立使用。`--environment-cr-repository` 须使用 `registry/namespace/repository` 格式，各段不能包含空格或 `.`、`..`。未指定时，Studio 创建或复用托管资源。这些配置不从环境变量读取，仅在部署命令中生效。部署后的「系统信息」页面展示最终使用的 CodePipeline 和 Container Registry 名称、来源及控制台链接，这些值为资源标识，不包含凭证。

<Note>
  环境构建资源与智能体部署构建资源独立管理。环境镜像构建使用上述 CodePipeline 和 Container Registry；智能体部署使用「配置构建资源」中管理的资源。当智能体选择了预构建环境时，部署会将智能体镜像构建到环境镜像所在的 Container Registry 命名空间下，确保构建凭证可同时拉取基础镜像和推送智能体镜像。
</Note>

### 智能模式

智能模式是一种基于自然语言目标的创建方式：在「添加智能体」中选择「智能模式」，用一段话描述智能体要解决的问题，沙箱中的 Codex 会自动判断意图，完成项目构建、调试和临时云端验证，生成可部署的源码产物。

<Note>
  智能模式需要已配置开发沙箱 Tool（`SANDBOX_DEV` 或 `--sandbox-dev-tool-id`），且该 Tool 已配置模型凭据（模型 ID、API Key 与指向当前云官方 Ark 端点的模型 API 地址）。未配置 Tool 时该入口显示为「暂不可用」；Tool 已配置但模型凭据缺失或不匹配时，入口同样不可用并提示重新部署 Studio。`veadk studio deploy` 部署时默认自动创建该 Tool 并完成模型配置；本地启动时可手动指定已有 Tool ID。
</Note>

<Note>
  「智能模式」页面在目标输入区下方提供模型选择器，用于指定本次智能开发会话中 Codex 使用的模型。模型列表由 Studio 服务端从当前账号已开通的火山方舟模型中获取，仅展示可用或即将下线的模型，每项显示模型名称、ID、厂商和生命周期状态，支持搜索筛选。默认使用开发沙箱 Tool 已配置的模型；选择其他模型后，所选模型的名称、提供方和 API 地址由 Studio 服务端注入会话环境，不向浏览器下发模型凭据。模型列表加载失败时可重试。
</Note>

#### 使用流程

<Steps>
  <Step title="描述目标">
    在「智能模式」页面输入目标描述，例如「创建一个能读取销售数据、生成周报并校验输出格式的 Agent」。如有影响结果的关键信息，Codex 会在开始前向你确认。
  </Step>

  <Step title="构建与验证">
    Studio 创建一个智能开发沙箱会话，Codex 在其中梳理目标与实现方式，编写、运行和验证智能体代码。构建过程中，进度消息以独立的进度指示器形式显示在对话中，与助手回复文本区分开；进度指示器在当前轮次结束后自动消失。交付物说明采用统一的结构化格式：先给出一句话结果摘要，随后按「已完成」「验证」「遗留问题」分节列出具体内容。开发环境最多保留 8 小时，可在同一会话中持续优化。
  </Step>

  <Step title="查看与部署产物">
    构建完成后，对话中出现交付物卡片，展示智能体名称、入口文件、文件数量、产物大小和验证状态。已通过云端验证的产物标记为「已验证交付物」并展示通过的检查项数量；未经验证的产物标记为「生成的 Agent 源码」。在卡片中可查看源码文件、下载 ZIP 或直接部署到 AgentKit Runtime。
  </Step>
</Steps>

#### 部署已验证源码

从智能模式部署时，源码由服务端从已验证的交付物或已保存的项目版本中物化，浏览器无法替换文件，仅支持创建新 Runtime。部署页面展示 Runtime 名称（可修改，需符合 4–64 个字符、仅含英文字母、数字、下划线和连字符的格式）、入口文件、产物校验值等信息，并支持选择发布区域和网络模式。部署时 Runtime 名称取自交付物中的智能体名称，资源标签会记录来源为智能开发。

<Warning>
  未通过云端验证的源码仍可部署，但部署前请确认 Runtime 配置无误。
</Warning>

#### 会话管理

智能开发会话在当前浏览器会话中运行，不显示在侧边栏的历史会话列表中。会话进行中显示「正在构建」状态；切换到其他页面后再返回可恢复当前会话。在构建进行中尝试切换页面时，Studio 提示离开将停止本轮构建，但会话仍会保留。恢复会话时，对话历史仅展示用户消息和助手回复，内部的意图判断与任务调度过程不会显示。

<Note>
  智能开发过程中的工具调用、思考内容和进度消息在发送到浏览器前会经过服务端脱敏：任务凭据和私有路径会被移除，不会出现在浏览器中。
</Note>

#### 项目版本库

每次构建或优化完成后，交付物会作为不可变的项目版本保存在 Studio 私有 TOS 存储桶中。已保存的版本不依赖原始 Sandbox 环境，即使 Sandbox 会话过期后仍可查看、下载和部署。版本按项目归组，同一项目的多个版本按创建时间排列。

<Note>
  项目版本持久化需要管理员配置 Studio 持久化存储（`VEADK_STUDIO_TOS_BUCKET` 与 `VEADK_STUDIO_TOS_REGION`）。未配置持久化存储时，构建产物仅在当前 Sandbox 会话有效期内可用，不会保存为项目版本。配置方式见 [Studio 持久化存储](#studio-持久化存储)。
</Note>

在智能模式创建页面中可打开项目版本库，浏览已保存的项目及其版本。每个版本展示创建时间、意图摘要、验证状态、智能体名称、入口文件、文件数量和产物大小。支持以下操作：

| 操作 | 说明 |
| :- | :- |
| 查看源码 | 在代码浏览器中以 IDE 风格的文件树浏览版本中的文件，支持浅色和深色主题切换。 |
| 下载 ZIP | 下载该版本的完整源码压缩包。 |
| 部署到 AgentKit | 从已保存版本中物化源码并部署到新的 Runtime，不依赖原始 Sandbox。 |
| 恢复到新会话 | 将已保存版本恢复到一个新的智能开发会话，作为后续迭代的基线。 |
| 删除版本 | 删除该版本及其源码产物；删除后不可恢复。 |

<Note>
  优化类构建会在交付物中标注优化前后变更，可在源码浏览器中直接查看变更对比。
</Note>

##### 版本比较

在项目版本库中选择同一项目的任意两个版本，可以比较它们之间的文件差异。比较结果以并排差异视图呈现，逐文件展示新增、删除和修改的内容。版本比较不产生额外存储对象。

### 从代码包添加和部署

代码包部署是一种独立的创建方式：在「添加智能体」中选择「从代码包添加和部署」，上传一个已有的智能体项目压缩包，即可在 Studio 中查看或编辑其文件并直接部署到 AgentKit，无需逐项配置模型、工具和技能。适合把在外部编写好的 VeADK 项目快速上线，或对已有项目做少量调整后重新部署。

<Steps>
  <Step title="上传代码包">
    在「添加智能体」菜单中选择「从代码包添加和部署」，点击上传区域或拖拽文件即可选择 `.zip` 压缩包。压缩包最大 50 MB，解压后文件数不能超过 800 个。启动入口默认为根目录的 `app.py`；如果压缩包根目录包含 `agentkit.yaml` 且其中声明了 `common.entry_point`，则以该配置指定的文件作为启动入口。
  </Step>

  <Step title="查看或编辑文件">
    上传成功后，Studio 会列出已识别的文件数量，并按压缩包文件名生成项目名称（符合 Google ADK 命名规则：以英文字母或下划线开头，仅含英文字母、数字和下划线，不使用保留名 `user`，长度不超过 64 个字符）。点击「查看文件」可在代码浏览器中预览或编辑文件内容；需要替换内容时重新上传压缩包即可。
  </Step>

  <Step title="配置部署参数">
    在部署配置区选择发布区域和网络模式，与自定义创建的部署页一致。代码包部署不显示智能体拓扑和飞书渠道开关。
  </Step>

  <Step title="部署到 AgentKit">
    选择「部署」后，Studio 按四个阶段展示进度：上传代码包、镜像打包、创建 Runtime 和发布服务。每个阶段完成或失败时会在部署进度区显示对应状态。
  </Step>
</Steps>

<Note>
  Studio 会对压缩包做安全处理：自动忽略 `__MACOSX` 目录与 `.DS_Store` 文件；当全部文件位于同一个顶层目录时，会去掉这层包裹目录后再校验入口。包含绝对路径、空段、`.`、`..` 段或空字节的条目会被拒绝；重复文件路径也会报错。启动入口文件必须位于去除包裹目录后的根目录。
</Note>

<Warning>
  代码包中的 `app.py` 会在部署后的 AgentKit Runtime 中执行，可能访问外部服务或运行环境中的数据。只部署可信来源的项目，并为 Studio 使用权限受限的凭证。
</Warning>

| 校验项 | 限制 | 说明 |
| :- | :- | :- |
| 压缩包大小 | 50 MB | 单个上传压缩包的最大体积。 |
| 文件数量 | 800 个 | 解压后保留文件数的上限。 |
| 解压后总大小 | 50 MB | 解压后内容总大小上限。 |
| 启动入口 | `app.py` | 默认入口文件。如果根目录存在 `agentkit.yaml` 且声明了 `common.entry_point`，则以该配置值为准；否则使用根目录的 `app.py`。 |
| 路径安全 | — | 拒绝绝对路径、`.` / `..` 段、空字节；忽略 `__MACOSX` 与 `.DS_Store`。 |
| 包裹目录 | 单层 | 全部文件同属一个顶层目录时自动去除该层。 |
| 项目名称 | 64 个字符 | 由压缩包文件名生成，符合 ADK 命名规则。 |

### 从存量项目迁移

存量项目迁移是一种独立的创建方式：在「添加智能体」中选择「从存量项目迁移」，上传一个已有的智能体项目压缩包，Studio 会在 Dev Sandbox 中自动分析项目框架和入口，生成可部署的 VeADK 项目。

迁移支持以下框架：

| 框架 | 迁移方式 |
| :- | :- |
| LangChain | Structured 迁移，运行 `ak migrate` 转换为 VeADK 项目 |
| LangGraph | Structured 迁移，运行 `ak migrate` 转换为 VeADK 项目 |
| Google ADK | Structured 迁移，运行 `ak migrate` 转换为 VeADK 项目 |
| Strands | Structured 迁移，运行 `ak migrate` 转换为 VeADK 项目 |
| AgentCore | Structured 迁移，运行 `ak migrate` 转换为 VeADK 项目 |
| Dify | Agentic 迁移，在 Dev Sandbox 中以 `ak migrate --execution in-place` 方式转换 |
| Any（通用迁移） | Agentic 迁移，适用于无法归入上述框架的项目，在 Dev Sandbox 中以 `ak migrate --execution in-place` 方式转换 |

<Steps>
  <Step title="上传项目压缩包">
    在「添加智能体」菜单中选择「从存量项目迁移」，上传一个 `.zip` 压缩包。压缩包最大 50 MB。
  </Step>

  <Step title="自动分析">
    Studio 创建一个用户独占的 Dev Sandbox Session（有效期 1 小时），调用预装的 Codex 对上传项目进行只读分析，识别框架、入口文件和迁移边界。分析结果包含每个框架的置信度和证据（文件路径与行号）、推荐框架与入口、需要用户确认的问题，以及迁移边界（包含和排除的文件）。
  </Step>

  <Step title="确认迁移参数">
    分析完成后，用户需确认框架、入口文件（Structured 框架必填）和应用名称，回答分析中提出的开放问题，并确认迁移边界后开始迁移。
  </Step>

  <Step title="执行迁移">
    Structured 框架运行 `ak migrate` 直接转换；Dify 和 Any 框架在同一个 Dev Sandbox Session 中由 Codex 辅助执行 `ak migrate --execution in-place`。迁移过程中的状态、日志和产物均保存在 Session 内。
  </Step>

  <Step title="预览、下载或部署">
    迁移完成后，可在 Studio 中预览迁移产物文件、下载 ZIP，或直接部署到 AgentKit。部署时 Studio 服务端从当前用户的 Session 中解析并校验迁移产物，不依赖浏览器提交的文件。
  </Step>
</Steps>

<Warning>
  迁移在 Dev Sandbox Session 中执行，Session 有效期为 1 小时。Session 过期后，预览、下载和部署均不可用，需重新上传并迁移。迁移产物中的 `app.py` 会在部署后的 AgentKit Runtime 中执行，只部署可信来源的项目。
</Warning>

<Note>
  从迁移产物部署到 AgentKit 时，Studio 会根据当前云服务商自动适配模型环境变量（`MODEL_AGENT_API_BASE`、`MODEL_AGENT_NAME` 和 `MODEL_NAME`），确保迁移产物在目标云环境下使用正确的模型端点和模型名称。
</Note>

<Note>
  分析与迁移过程中，Studio 在「Codex 执行动态」面板中以结构化形式展示 Codex 的执行进展：分析计划与迁移计划按条目显示完成状态与进度，首个未完成的计划步骤自动标记为进行中；命令执行、文件更新、外部工具调用、网络搜索和子任务协作分别显示输入、输出与退出码或错误信息，执行异常的活动条目自动展开以展示错误详情。所有动态内容在发送到浏览器前均经过服务端脱敏，密钥、令牌等敏感字段会被移除。
</Note>

<Note>
  迁移输入区在压缩包上传按钮旁提供模型选择器，用于指定 Dev Sandbox 中 Codex 执行迁移分析与转换时使用的模型。模型列表由 Studio 服务端从当前账号已开通的火山方舟模型中获取，仅展示可用或即将下线的模型，不兼容项目迁移的模型会被排除，每项显示模型名称、ID、厂商和生命周期状态，支持搜索筛选。默认使用迁移能力返回的默认模型，未配置时选择列表中的首个可用模型。模型列表加载失败时可重试。任务创建后模型不可更改；所选模型的名称、提供方和 API 地址由 Studio 服务端注入迁移会话环境，不向浏览器下发模型凭据。
</Note>

| 校验项 | 限制 | 说明 |
| :- | :- | :- |
| 压缩包大小 | 50 MB | 单个上传压缩包的最大体积。 |
| Session 有效期 | 1 小时 | Dev Sandbox Session 的存活时间，过期后迁移产物不可用。 |
| 框架选择 | — | Structured 框架（LangChain、LangGraph、Google ADK、Strands、AgentCore）必填入口文件；Dify 和 Any 不接受 Structured 入口。 |
| 应用名称 | 63 个字符 | 只能包含小写字母、数字和连字符，以字母或数字开头和结尾。 |
| 产物安全校验 | — | 迁移产物 ZIP 按文件清单逐条校验大小和 SHA256，拒绝路径越界、符号链接和修改 Agent 运行方法的文件。 |

### 添加技能

创建智能体时可从以下来源添加技能，添加后技能文件写入生成项目的 `skills/` 目录：

* **Skill Hub**：在火山引擎公开技能仓库中按关键词检索技能并添加。
* **本地上传**：拖入文件夹或选择 ZIP 包。每个技能目录需包含 `SKILL.md`；Studio 检查文件是否存在、文件数量、大小和路径安全，并自动忽略 `__MACOSX` 目录中的 macOS 元数据文件，完整的 frontmatter 与技能格式由 ADK 在加载时校验。生成项目中的技能目录名取自 `SKILL.md` 的 `name` 字段或上传目录名。
* **AgentKit SkillSpace**：浏览当前账号可见的技能空间，选择技能及其版本。

浏览 AgentKit SkillSpace 及其中技能由 Studio 服务端使用自身配置的火山引擎凭证完成，浏览器不会接触凭证。本地启动时通过 `VOLCENGINE_ACCESS_KEY` 与 `VOLCENGINE_SECRET_KEY` 提供访问权限；部署到 VeFaaS 时使用绑定 IAM Role 的临时凭证。启用 SSO 登录后，浏览技能空间需要先完成 Studio 登录。

技能空间列表默认跨地域返回当前账号可见的全部空间；选择某个空间后，按该空间所在地域加载其中的技能列表。需要重新获取列表时使用刷新按钮。

| 现象 | 检查方法 |
| :- | :- |
| 提示未配置火山引擎凭证 | 本地启动时检查 `VOLCENGINE_ACCESS_KEY` 与 `VOLCENGINE_SECRET_KEY`；VeFaaS 部署检查绑定的 IAM Role。凭证只在服务端使用，不会下发到浏览器。 |
| 提示需先登录 | 启用 SSO 时，先完成 Studio 登录后再浏览技能空间。 |
| 技能空间或技能列表为空 | 确认当前凭证有权查看对应地域的技能空间，且所选空间内已有技能；必要时使用刷新按钮重试。 |
| 列表加载失败 | 检查 Studio 登录状态、网络连通性和凭证权限，然后使用刷新按钮重试。 |

<Note>
  本地上传不再在导入阶段强制校验 `SKILL.md` 的 `name` 与 `description` 格式，也不要求目录名与 `name` 一致。如果技能在运行时报错，检查 `SKILL.md` frontmatter 是否符合 ADK 技能要求。
</Note>

<Note>
  从 AgentKit SkillSpace 添加技能时，若云端版本提供完整文件包，Studio 会下载其中的 `SKILL.md`、脚本、参考文档和资源；未提供完整包时仅使用 `SKILL.md`。单个智能体可添加的技能数量没有固定上限。
</Note>

### 智能生成智能体配置

自定义创建的构建画布上方提供「智能生成」入口。在输入框中用一句自然语言描述目标，例如「创建一个短视频生产智能体，依次完成趋势调研、脚本编写、素材生产、视频生成和质量复核」，点击「智能生成」即可。

Studio 调用 `doubao-seed-2-0-lite-260428` 模型，根据需求生成一份经过校验的完整智能体配置草稿并填入画布，生成过程会消耗 Token。

<Note>
  生成结果会替换当前画布与属性配置。如果画布存在未保存的修改，Studio 会先要求确认是否继续。
</Note>

#### 生成结果的结构

生成的配置遵循以下规则：

* 优先使用 LLM 智能体作为根智能体，使其能够直接推理并灵活响应用户需求；不会仅因需求涉及多个任务或步骤就选择编排型根智能体，仅在需要严格控制执行流程时才使用编排型智能体作为根。
* 编排型智能体（顺序、并行、循环）只负责调度子智能体，不包含模型、提示词、工具、记忆、知识库或链路观测配置。
* LLM 智能体始终为叶子节点，自动填充名称、描述、系统提示词、模型和工具，且不能再嵌套子智能体。
* 生成的 LLM 智能体统一使用 `doubao-seed-2-1-pro-260628` 模型。
* 编排型智能体的迭代上限默认为 `3`；循环型智能体按需求中指定的循环上限设置。
* 所有智能体与自定义工具名称为全局唯一的 snake\_case Python 标识符。
* 仅在需求需要时启用工具，不会为只做审查的智能体分配媒体生成工具。
* 智能生成不配置记忆、知识库与链路观测。生成的草稿中这些能力始终处于关闭状态，对应后端使用默认值（记忆使用 `local`，知识库使用 `viking`）；如需启用，请在生成后于画布中手动配置。

生成的智能体可以选择以下内置工具：

| 工具标识 | 说明 |
| :- | :- |
| `web_search` | 调用融合信息搜索，检索公开网络结果。 |
| `parallel_web_search` | 并行执行多次网络搜索。 |
| `link_reader` | 读取并解析指定 URL 的网页内容。 |
| `image_generate` | 根据文本提示生成图片。 |
| `image_edit` | 编辑已有图片。 |
| `video_generate` | 根据文本或图片输入生成视频。 |
| `run_code` | 在代码沙箱中执行代码。 |

<Note>
  生成配置不会为 LLM 智能体分配企业知识库搜索工具。记忆、知识库与链路观测需在生成后于画布中按需启用，各后端的完整参数见对应组件页面。
</Note>

<Note>
  使用 BytePlus 作为云服务商时，`web_search` 和 `parallel_web_search` 不出现在自定义创建和智能生成的内置工具列表中；火山引擎模式下不受影响。
</Note>

#### 未决项

生成结果会列出尚未确定的资源或标识（如实例 ID、URL、凭证、MCP 服务或技能 ID），Studio 不会虚构这些信息。生成后需在画布中按需补充实际资源。

#### 使用步骤

<Steps>
  <Step title="输入需求">
    在构建画布上方的输入框中用自然语言描述目标，输入长度上限为 8000 字符。
  </Step>

  <Step title="生成配置">
    点击「智能生成」。生成期间输入框置灰，完成后画布填入新的配置草稿，并显示一条摘要说明。
  </Step>

  <Step title="检查未决项">
    查看生成结果中的未决项提示，按需在画布中补充实际资源或标识。
  </Step>

  <Step title="调整与测试">
    像自定义创建一样检查、编辑配置，然后生成项目并启动临时测试，或下载 ZIP、部署到 AgentKit。
  </Step>
</Steps>

生成完成后可点击「重新生成」再次基于同一需求生成新配置。

#### 权限与失败处理

启用角色访问控制时，智能生成仅对 `developer` 和 `admin` 开放。

生成失败时 Studio 会弹窗提示。常见情况包括：

| 现象 | 检查方法 |
| :- | :- |
| 生成超时 | 服务端生成限时 180 秒，超时后返回超时提示，可缩短需求后重试。 |
| 模型调用失败 | 检查火山引擎凭证与模型访问权限；错误信息已做凭据脱敏处理。 |
| 提示无权限 | 确认当前账号具有 `developer` 或 `admin` 角色。 |

### 添加远程智能体

远程智能体通过 AgentKit 智能体中心发现并调用，适合把已经发布到中心的专业能力接入多智能体项目。远程智能体只能作为子智能体，不能作为根智能体；根智能体需要使用 LLM、顺序、并行或循环类型。

使用该能力前，应满足以下条件：

* Studio 已配置可访问 AgentKit 的云服务商凭证（火山引擎或 BytePlus）；部署到 VeFaaS 时，所绑定的 IAM Role 需要具备相应权限。
* 目标地域的 `default` 项目中至少存在一个当前账号可见的 AgentKit 智能体中心，且中心内已有可调用的远程智能体。
* 启用 Studio 角色权限时，当前用户具有 `developer` 或 `admin` 角色。

<Steps>
  <Step title="配置根智能体">
    创建 LLM 或编排型根智能体，并完成模型、描述和系统提示词等必要配置。
  </Step>

  <Step title="添加远程智能体节点">
    在左侧智能体结构中为根智能体或其他本地智能体添加子智能体，然后将类型设为「远程智能体」。根节点上的远程智能体类型不可选择。
  </Step>

  <Step title="选择智能体中心">
    默认加载火山引擎北京地域（BytePlus 为 `ap-southeast-1`）`default` 项目下当前账号可见的智能体中心。使用其他地域时，先在「更多选项」中修改地域，再从下拉框选择中心；需要重新获取列表时使用刷新按钮。
  </Step>

  <Step title="配置发现范围">
    按需设置召回数量和 OpenAPI 地址。远程智能体的名称、描述和能力来自中心返回的 Agent Card，无需单独填写名称或 A2A 地址。
  </Step>

  <Step title="测试调用">
    生成项目并启动临时测试，输入一个需要目标中心专业能力的问题。响应能够使用中心内匹配智能体返回的信息，即表示发现和调用链路可用。
  </Step>
</Steps>

每轮任务中，父智能体会根据用户请求从所选中心发现匹配的远程智能体，并将其作为可调用能力使用。

| Studio 配置 | 生成项目配置 | 类型 | 是否必填 | 默认值 | 说明 |
| :- | :- | :- | :- | :- | :- |
| AgentKit 智能体中心 | `REGISTRY_SPACE_ID` | `str` | 是 | — | 用于发现远程智能体的中心；在 Studio 中通过下拉框选择。 |
| 召回智能体数量 | `REGISTRY_TOP_K` | `int` | 否 | `3` | 每轮任务最多召回的匹配智能体数量；有效范围为 1–20。 |
| AgentKit 智能体中心地域 | `REGISTRY_REGION` | `str` | 否 | 火山引擎：`cn-beijing`；BytePlus：`ap-southeast-1` | 智能体中心所在地域；修改后会按新地域重新加载下拉列表。默认值随所选云服务商变化。 |
| AgentKit 智能体中心 OpenAPI 地址 | `REGISTRY_ENDPOINT` | `URL` | 否 | 火山引擎：`https://open.volcengineapi.com/`；BytePlus：`https://agentkit.ap-southeast-1.byteplusapi.com/` | 生成项目调用智能体中心时使用的 OpenAPI 地址；仅在需要使用其他公开入口时修改。默认值随所选云服务商变化。 |

例如，创建名为 `support_router` 的 LLM 根智能体，为其添加一个远程智能体子节点，选择「售后服务」智能体中心，并保留召回数量 `3` 与火山引擎北京地域。测试时输入「查询订单配送异常并给出处理建议」；如果中心中存在匹配能力，根智能体会调用相应的远程智能体完成任务。

### 排查远程智能体问题

| 现象 | 检查方法 |
| :- | :- |
| 提示未配置云服务商凭证 | 本地启动时检查对应云服务商的凭证（火山引擎为 `VOLCENGINE_ACCESS_KEY` 与 `VOLCENGINE_SECRET_KEY`，BytePlus 为 `BYTEPLUS_ACCESS_KEY` 与 `BYTEPLUS_SECRET_KEY`）；VeFaaS 部署检查绑定的 IAM Role。凭证只在服务端使用，不会下发到浏览器。 |
| 下拉框为空 | 确认所选地域的 `default` 项目中已创建智能体中心，并确认当前凭证有权查看该中心。 |
| 智能体中心列表加载失败 | 检查 Studio 登录状态、AgentKit OpenAPI 网络连通性和凭证权限，然后使用刷新按钮重试。 |
| 无法生成或测试项目 | 确认远程智能体位于根智能体之下，并且已经选择智能体中心。 |
| 测试时未发现可用智能体 | 确认中心内已有与测试请求匹配且可调用的智能体；必要时调整召回数量。 |
| 发现成功但远程调用失败 | 检查地域、OpenAPI 地址、中心内智能体状态以及运行环境访问 AgentKit 的权限和网络。 |

测试运行进程默认保留 1800 秒，可通过 `--generated-agent-test-run-ttl` 调整。每位登录用户最多同时运行 3 个生成智能体测试进程；超出上限时返回 429，需关闭不再使用的调试页面后重试。刷新页面后遗留的测试进程会被自动清理，单次测试运行最多接受 300 个项目文件。测试代码可能调用外部服务或访问运行环境中的数据，只应测试可信项目，并为 Studio 使用权限受限的凭证。

<Note>
  测试运行会自动规范化生成智能体中配置的 HTTP MCP 工具端点：URL 未以 `/mcp` 结尾时会自动补全 `/mcp`，并通过 Streamable HTTP 验证工具发现。若无法连接 MCP 服务完成工具发现，测试会返回错误，提示确认 URL 是否指向实际 MCP endpoint（通常以 `/mcp` 结尾）并检查 Token；画布中保存的原始 URL 不会被修改。
</Note>

<Note>
  调试运行仅支持当前云服务商的官方 Ark 模型端点。配置了自定义模型地址的智能体无法在调试运行中启动，需改用官方地址或通过部署后的 Runtime 测试。
</Note>

<Note>
  云端部署的 Studio（运行于 VeFaaS）在调试运行时会校验 MCP 与 A2A 端点地址：仅允许连接当前函数所绑定 VPC 网段内的私网端点，位于该 VPC 之外的私网地址、环回地址、链路本地地址和云元数据地址均被禁止。本地启动的 Studio 不受此限制，仍可连接本地资源。若 Studio 无法确认 VPC 网段（例如函数未启用 VPC 或函数角色缺少 VPC 与子网的只读权限），调试运行会报错并提示检查 VPC 配置和 IAM 权限。VPC 网段信息在 Studio 服务端缓存 5 分钟。
</Note>

### 配置记忆

为智能体启用长期记忆后，可在 Studio 中选择以下后端：

| 后端 | 适用场景 |
| :- | :- |
| [本地向量库](/productions/veadk/preview/zh/components/memory/local) | 进程内向量库，适合本地调试，不持久化，需要配置向量化模型。 |
| [OpenSearch](/productions/veadk/preview/zh/components/memory/opensearch) | 使用自建或托管的 OpenSearch 集群，并自行配置向量化模型。 |
| [Redis](/productions/veadk/preview/zh/components/memory/redis) | 使用 Redis 向量检索，并自行配置向量化模型。 |
| [VikingDB Memory](/productions/veadk/preview/zh/components/memory/vikingdb) | 火山 VikingDB 记忆库（支持用户画像），使用 Studio 的火山引擎凭证。 |
| [OpenViking](/productions/veadk/preview/zh/components/memory/openviking) | OpenViking 长期记忆，按用户维度保存和检索偏好、事件与实体。 |
| [mem0](/productions/veadk/preview/zh/components/memory/mem0) | Mem0 托管记忆服务。 |

本地向量库、OpenSearch、Redis 与 mem0 后端的连接和向量化模型参数以环境变量形式写入生成项目；VikingDB Memory 与 OpenViking 使用火山引擎凭证链，由 Studio 服务端转发到调试运行和 AgentKit 运行时，无需在创建页重复填写 AK/SK。各后端的完整参数、默认值和限制见对应组件页面。

选择 VikingDB Memory 时，Studio 会通过服务端凭证列出当前账号在当前云服务商地域下可见的 VikingDB 记忆库集合。列表依次查询 `DATABASE_VIKINGMEM_PROJECT`、`VEADK_STUDIO_PROJECT` 环境变量指定的项目与 `default` 项目中的集合。选择已有集合后，其名称将作为长期记忆的集合索引，Studio 同时根据所选集合自动填充项目、地域和记忆类型（对应 `DATABASE_VIKINGMEM_PROJECT`、`DATABASE_VIKING_REGION`、`DATABASE_VIKINGMEM_MEMORY_TYPE` 环境变量，这些变量不在创建页展示）；未选择已有集合时，集合名称默认根据智能体名称自动生成，运行时若集合不存在会自动创建。需要重新获取列表时，可使用刷新按钮。

本地启动时，通过 `VOLCENGINE_ACCESS_KEY` 和 `VOLCENGINE_SECRET_KEY` 提供查询权限；部署到 VeFaaS 后，使用绑定 IAM Role 的临时凭证。凭证只在服务端使用，不会下发到浏览器。

选择 OpenViking 时，Studio 在创建页填写以下配置项并写入生成项目的环境变量：

| Studio 配置项 | 生成项目环境变量 | 是否必填 | 默认值 / 占位 | 说明 |
| :- | :- | :- | :- | :- |
| OpenViking 服务地址 | `DATABASE_OPENVIKING_URL` | 是 | `https://api.vikingdb.cn-beijing.volces.com/openviking` | OpenViking 服务地址，可在[控制台](https://console.volcengine.com/vikingdb/openviking)获取。 |
| OpenViking API Key | `DATABASE_OPENVIKING_API_KEY` | 是 | — | OpenViking API Key，可在[控制台](https://console.volcengine.com/vikingdb/openviking)获取。 |
| 记忆归属 ID | `DATABASE_OPENVIKING_USER_ID` | 否 | `default` | 对应 `viking://user/<此值>/peers/<请求用户>/memories` 中的 user 段，用于隔离 Agent、租户或业务场景。 |
| 记忆策略 | `DATABASE_OPENVIKING_MEMORY_POLICY` | 否 | — | 记忆的抽取与隔离策略，JSON 格式；不填写时由 OpenViking 服务应用其官方默认策略，结构以 [OpenViking 会话接口](https://github.com/volcengine/OpenViking/blob/main/docs/zh/api/05-sessions.md)为准。 |

<Note>
  OpenViking 的记忆归属 ID（`DATABASE_OPENVIKING_USER_ID`）与运行时用户标识（`Runner.user_id`）是不同的概念：前者隔离不同应用或租户的记忆，后者作为 OpenViking 的 peer ID 隔离终端用户记忆。详见[使用 OpenViking 存储](/productions/veadk/preview/zh/components/memory/openviking)。
</Note>

<Warning>
  启用 OpenViking 长期记忆会把会话写入外部 OpenViking 服务。使用前应确认数据处理、访问控制和保留策略符合业务要求。
</Warning>

### 配置知识库

为智能体启用知识库后，可在 Studio 中选择以下后端：

| 后端 | 适用场景 |
| :- | :- |
| [VikingDB Knowledge](/productions/veadk/preview/zh/components/knowledge/viking) | 默认选项。使用火山引擎托管知识库，由服务端完成切分、向量化和检索，无需配置本地 embedding。 |
| [OpenSearch](/productions/veadk/preview/zh/components/knowledge/opensearch) | 使用自建或托管的 OpenSearch 集群，并自行配置 embedding。 |
| [Context Search](/productions/veadk/preview/zh/components/knowledge/context-search) | 使用火山引擎 Context Search 服务完成检索。 |
| [OpenViking Knowledge](/productions/veadk/preview/zh/components/knowledge/openviking) | 使用 OpenViking 资源目录知识库，由服务端完成资源解析与检索，无需配置本地 embedding。 |

Studio 不提供 `local` 后端，因为创建页面不能为进程内向量库存入文档。如需本地调试，可使用 VeADK SDK [配置本地知识库](/productions/veadk/preview/zh/components/knowledge/local)。

选择 VikingDB Knowledge 时，Studio 会列出北京地域 `default` 项目中当前账号可见的知识库集合。选择已有集合后，其名称将作为知识库索引；未选择已有集合时，索引名称默认为 `<智能体名称>_kb`。需要重新获取列表时，可使用刷新按钮。

本地启动时，通过 `VOLCENGINE_ACCESS_KEY` 和 `VOLCENGINE_SECRET_KEY` 提供查询权限；部署到 VeFaaS 后，使用绑定 IAM Role 的临时凭证。凭证只在服务端使用，不会下发到浏览器。

选择 OpenViking Knowledge 时，Studio 在创建页填写以下配置项并写入生成项目的环境变量：

| Studio 配置项 | 生成项目环境变量 | 是否必填 | 默认值 / 占位 | 说明 |
| :- | :- | :- | :- | :- |
| OpenViking 服务地址 | `DATABASE_OPENVIKING_URL` | 是 | `https://api.vikingdb.cn-beijing.volces.com/openviking` | OpenViking 服务地址，可在[控制台](https://console.volcengine.com/vikingdb/openviking)获取。 |
| OpenViking API Key | `DATABASE_OPENVIKING_API_KEY` | 是 | — | OpenViking API Key，可在[控制台](https://console.volcengine.com/vikingdb/openviking)获取。 |
| 知识库归属 ID | `DATABASE_OPENVIKING_USER_ID` | 否 | `default` | OpenViking owner/context 标识，用于构建默认资源目录 `viking://user/<此值>/resources/<资源索引>/`。 |
| 知识库资源目录 | `DATABASE_OPENVIKING_TARGET_URI` | 否 | — | 导入与检索使用的资源目录；留空时由知识库归属 ID 与资源索引自动生成。填写后直接使用该 URI，优先级最高。 |

此外，Studio 提供「资源索引」字段，用于指定 `KnowledgeBase` 的 `index`。留空时生成项目使用智能体名称自动生成索引（如 `my_agent_kb`）。未配置 `DATABASE_OPENVIKING_TARGET_URI` 时，资源目录自动拼接为 `viking://user/<知识库归属 ID，未填则 default>/resources/<资源索引>/`；填写 `DATABASE_OPENVIKING_TARGET_URI` 后直接使用该完整 URI。

<Note>
  OpenViking 的知识库归属 ID（`DATABASE_OPENVIKING_USER_ID`）与运行时用户标识（`Runner.user_id`）是不同的概念：前者隔离不同应用或租户的资源目录，后者标识终端用户。详见[使用 OpenViking 存储](/productions/veadk/preview/zh/components/knowledge/openviking)。
</Note>

<Warning>
  启用 OpenViking 知识库会把导入的文档发送到外部 OpenViking 服务。使用前应确认数据处理、访问控制和保留策略符合业务要求。
</Warning>

| 现象 | 检查方法 |
| :- | :- |
| 知识库列表为空 | 确认北京地域 `default` 项目中已有 VikingDB 知识库集合，并确认当前凭证有权查看。 |
| 知识库列表加载失败 | 检查 Studio 登录状态、VikingDB Knowledge 服务的网络连通性和凭证权限，然后刷新列表。 |
| 生成或测试失败 | 确认知识库配置完整，并检查运行环境能否访问对应后端。 |

### 添加代码执行工具

在自定义创建的内置工具中选择「代码执行」后，Studio 会把 `run_code` 工具加入生成的 Python 代码，并在内置工具列表下方显示该工具依赖的沙箱配置。代码、语言和超时由智能体按 `run_code` 的工具函数签名在运行时传入，`tool_context` 由 ADK 自动注入，无需在 Studio 中填写。

| Studio 配置 | 生成项目环境变量 | 类型 | 是否必填 | 默认值 | 说明 |
| :- | :- | :- | :- | :- | :- |
| 代码执行沙箱 ID | `AGENTKIT_TOOL_ID` | `str` | 是 | — | `run_code` 使用的 AgentKit 代码执行沙箱 ID，形如 `t-xxxxxxxx`。 |
| AgentKit Tools 地域 | `AGENTKIT_TOOL_REGION` | `str` | 否 | `cn-beijing` | 调用 AgentKit Tools 的地域。火山引擎模式下未设置时回退到 `REGION` 环境变量，仍为空时默认 `cn-beijing`；BytePlus 模式不读取 `REGION`，使用 BytePlus 默认地域。 |

<Note>
  这两个值会同时用于本地调试运行和部署后的运行时，生成的 `.env.example` 也会包含这两个变量。沙箱 ID 与地域只在 Studio 服务端使用，不会下发到浏览器。
</Note>

关于 `run_code` 的完整参数、Shell 执行和凭证要求，参见[代码沙箱](/productions/veadk/preview/zh/components/tools/code-sandbox)。

## 查看子智能体移交

在多智能体项目中，根智能体可以把任务移交给子智能体执行。当发生移交时，Studio 会在对话中为子智能体的回复单独显示一张标注「智能体移交」的卡片，并展示该子智能体的名称和描述；子智能体的输出不再与根智能体的回复混在同一个消息气泡中。

子智能体的名称和描述来自项目结构中的智能体配置。如果子智能体未配置描述，卡片会显示默认说明。子智能体完成输出后，后续回复继续显示为根智能体的消息。

<Note>
  该展示适用于本地子智能体和远程智能体。远程智能体只能作为子智能体，不能作为根智能体。
</Note>

## 对话调用链路与问题反馈

在对话页面，每条助手回复旁提供调用链路查看和问题反馈入口，便于排查单轮执行问题。这些入口仅在普通智能体对话中可用，内置 Codex 智能体对话不提供。

### 查看调用链路

每条助手回复旁的「Tracing 火焰图」按钮打开调用链路观测面板，以 span 树和详情面板展示该会话的执行轨迹，并在打开时以该轮回复的结束时间作为查询截止点。

* 本地调试会话直接读取 ADK 调试链路。
* 连接云端 Runtime 时，Studio 服务端使用自身配置的云服务商凭证向 APMPlus 查询该会话的链路，浏览器不接触凭证。查询使用的 APMPlus OpenAPI 接入地址按当前云服务商选择：火山引擎为 `open.volcengineapi.com`，BytePlus 为 `open.byteplusapi.com`。

<Note>
  云端 Runtime 的链路观测需在火山引擎控制台为对应智能体开启 APMPlus 链路观测。通过 Studio 部署的 Runtime 默认启用 APMPlus 链路观测。打开链路面板时，Studio 根据查询结果显示不同状态：

  | 状态 | 说明 |
  | :- | :- |
  | 加载中 | 正在向 APMPlus 查询链路数据。 |
  | 采集中 | 链路数据尚未到达 APMPlus，面板显示采集中状态并提供重试按钮，Studio 会自动重试两次后仍无数据时需手动重试。 |
  | 未开启 | Runtime 未开启链路观测，提示到控制台开启后重试。 |
  | 权限不足 | Studio 运行角色缺少 APMPlus 只读权限，提示联系管理员补充权限。 |
  | 加载失败 | 链路查询发生其他错误，面板提供重新加载按钮。 |

  查询链路时，Studio 服务端优先按 `POST /run_sse` 入口 span 定位目标链路；未命中时回退到对会话时间窗口的广泛扫描，选取与该轮回复结束时间最接近的链路。链路数据可能因采集延迟而短暂不可见，稍后重试即可恢复。
</Note>

<Note>
  链路面板展示模型输出时，Studio 会自动移除流式输出中因递进产生的空占位符（`null` 条目），仅显示实际生成的内容片段。
</Note>

### 问题反馈

每条助手回复旁的「问题反馈」按钮可针对该轮回复上报问题。在对话框中选择问题类型并补充描述后提交，提交内容会一并携带该轮的输入、输出、工具调用记录和链路信息，便于排查，并在上报前做凭据脱敏处理。可选问题类型如下：

| 问题类型 | 说明 |
| :- | :- |
| 执行速度慢 | 回复生成或工具调用耗时过长。 |
| 运行崩溃 | 智能体执行中断或报错。 |
| 结果不准确 | 回复内容与预期不符或存在错误。 |
| 工具调用失败 | 工具执行失败或返回异常。 |
| 其他问题 | 不属于以上类别的问题。 |

侧边栏底部的「问题反馈」入口（标记为 Beta）用于反馈 Studio 整体使用问题：选择所属模块、问题类型并填写描述后提交。所属模块与当前所在页面对应，可在对话、智能体、自动化、搜索或其他之间选择；平台问题类型包括页面加载慢、功能无法使用、页面显示异常、操作无响应和其他问题。

<Note>
  问题反馈数据会上报到 AgentKit 团队用于改进产品，提交成功后会显示确认信息。请在描述中避免填写密钥、Token 等敏感信息；当前会话不可用时反馈可能失败，可关闭后重试。
</Note>

## 分享对话为图片

每条助手回复旁的「分享为图片」按钮可将截至该轮回复的全部输入与输出导出为一张 PNG 图片。图片在浏览器本地生成，不依赖网络请求；导出内容包含从会话开始到当前回复的所有用户消息和助手回复，并在底部附加「上述会话由 AgentKit Studio 导出，仅供参考」的说明。

生成完成后可在对话框中预览图片，支持以下操作：

| 操作 | 说明 |
| :- | :- |
| 下载 PNG | 将图片保存到本地，文件名包含导出时间戳。 |
| 复制图片 | 将图片复制到系统剪贴板，便于直接粘贴到其他应用；该操作依赖浏览器的剪贴板写入能力，不支持时提示改用下载。 |

<Note>
  该按钮在普通智能体对话和内置 Codex 智能体对话中均可用，仅在回复完成（非流式输出中且未等待 OAuth 授权）时显示。当会话过长导致图片尺寸超出浏览器画布限制时，生成会失败并提示会话过长，可在缩短会话后重试。
</Note>

## 使用智能搜索

智能搜索提供会话、网络、知识库和长期记忆四种检索源：

* **会话**：在当前智能体的历史消息中执行全文检索。
* **网络**：调用当前智能体挂载的 `web_search` 工具实时检索。
* **知识库**：使用当前智能体挂载的知识库执行语义检索。
* **长期记忆**：使用当前智能体挂载的长期记忆后端执行语义检索。

Studio 根据智能体元数据启用实际可用的检索源，未挂载的来源会被禁用。知识库和长期记忆结果会分别显示索引或来源名称及后端类型。

## 部署网络模式

在部署页可为 AgentKit Runtime 选择网络模式，决定 Runtime 的公网暴露方式：

| 网络模式 | 说明 |
| :- | :- |
| 公网 | Runtime 暴露公网数据面地址。 |
| VPC | Runtime 仅部署在指定 VPC 与子网内，不暴露公网数据面地址；可勾选在 VPC 内启用共享公网出口。 |
| 公网 + VPC | 同时分配公网地址与 VPC 内地址。 |

选择 VPC 或公网 + VPC 模式时，需要填写 VPC ID 和子网 ID。

VPC 私有 Runtime 部署完成后不返回公网数据面地址，Studio 通过服务端运行时代理访问该 Runtime，数据面 API Key 始终保留在服务端，不会下发到浏览器。该连接方式与「选择云端 Runtime」中所述的服务端运行时代理一致。

<Note>
  部署完成后，Studio 会自动连接新创建的 Runtime。连接时 Studio 会最多等待 60 秒重试探测 Runtime 端点，直到端点可达或超时。若超时后仍无法连接（网关域名可能仍在生效，或当前网络/DNS 无法访问该 Runtime），部署任务会标记为「部署完成，暂未连接」并保留进度卡片与提示信息，可在「管理智能体」中重试连接。
</Note>

## 管理智能体

「管理智能体」列出当前用户可见的 AgentKit Runtime，可见范围由登录账号的角色决定：`admin` 可见全部 Runtime，`developer` 和普通用户仅可见自己创建的 Runtime。列表默认展示北京区域的 Runtime，也可以切换到上海。当可见范围包含全部 Runtime 时，当前用户创建的 Runtime 会标注「我创建的」。可以查看：

* Runtime 名称、ID、状态、区域和创建时间；
* 模型、描述、项目、版本、资源规格和更新时间；
* 绑定的 Memory、Tool、Knowledge 与 MCP Toolset 标识；
* Runtime 环境变量和主智能体信息。
* 智能体拓扑、远端调用链路与全局部署任务状态。

Studio 不会在浏览器中保存 Runtime API Key，因此管理页只显示 Runtime 返回的主智能体摘要，不加载完整子智能体树。

<Warning>
  删除操作会永久删除对应的 AgentKit Runtime。确认该 Runtime 不再承载业务流量，并完成必要的数据和配置备份后再操作。
</Warning>

<Note>
  删除前 Studio 会弹出确认对话框，列出即将删除的智能体或草稿；确认后才会执行删除。删除过程中，被删除的智能体会从列表中暂时隐藏。若当前对话正在使用被删除的智能体，Studio 会清除当前选择并返回智能体管理页。
</Note>

管理页可能展示 Runtime 的环境变量值。仅应向经过授权的用户开放 Studio，并避免把明文密钥放入普通环境变量；优先使用平台支持的密钥管理能力。

智能体工作台将已部署 Runtime 与本地草稿统一管理。每个已部署智能体显示当前版本号，并标注部署状态：部署中、待更新、尚未发布、失败或已取消。已部署的智能体可直接在工作台中重新编辑并更新到同一 Runtime，无需新建部署。

<Note>
  构建或部署阶段失败时，Studio 会在工作台展示服务端返回的完整错误信息，默认展开且可复制，便于直接定位问题；部署与更新失败时还可在错误面板中重新发起。部署失败或取消后，进度卡片提供「返回编辑」按钮，可直接回到草稿继续调整配置后重新发起部署。
</Note>

### 管理草稿

在自定义创建过程中，Studio 会将未发布的智能体草稿保存在当前浏览器中，并按登录用户隔离。草稿与已部署 Runtime 一并出现在「管理智能体」列表，每条草稿显示更新时间与「草稿」标识；正在部署的草稿显示「部署中」标识，可在该草稿上查看部署进度。草稿支持编辑与删除，删除前会弹出确认对话框。

<Warning>
  草稿仅保存在当前浏览器，不会同步到服务器或其他设备。清除浏览器存储、使用隐私模式或更换浏览器后草稿会丢失。
</Warning>

<Note>
  MCP 工具的鉴权 Token 会转换为环境变量引用保存：生成源码仅保留 `${ENV_NAME}` 引用，Token 值写入部署环境变量；YAML 导出与浏览器草稿均保留对应的环境变量值。更新已部署的 Runtime 时会重新加载已有环境变量值，在部署表单中输入新的 Token 会覆盖原有值。
</Note>

草稿保存使用浏览器本地存储空间。存储空间不足或被浏览器拒绝写入时，Studio 会提示对应原因，可删除不再需要的草稿或清理站点存储后重试。

## 端云接力到云端继续执行

端云接力用于把本地 Codex 正在进行的会话与项目迁移到 Studio 云端 Codex Sandbox，并在云端继续执行任务。适用于本地算力、环境或运行时长受限，需要把当前编码任务转到云端 Codex 继续推进的场景。该入口位于「管理智能体」页面的 Codex 标签下，仅对具备创建智能体权限的角色（`admin` 与 `developer`）可见。

<Warning>
  端云接力只迁移项目代码与可见会话历史，不复制本地 Codex 的系统提示词、推理过程、工具调用记录、运行时状态、SSH 私钥或全局配置。配对码为一次性凭证，请勿公开分享。
</Warning>

<Steps>
  <Step title="安装 AgentKit Studio Plugin">
    首次使用时，在「接力到云端继续执行」对话框中选择安装方式。选择「与 Codex 对话安装」可复制一段提示词，粘贴到本地 Codex 对话中由其执行安装；选择「从终端安装」则复制以下命令在本地终端执行：

    ```bash lines theme={null}
    codex plugin marketplace add volcengine/veadk-python \
      --sparse .agents/plugins \
      --sparse plugins/agentkit-studio \
      && codex plugin add agentkit-studio@veadk-python
    ```
  </Step>

  <Step title="复制接力提示词">
    插件安装完成后，点击「复制接力提示词」。提示词中包含当前 Studio 地址和一次性配对码，配对码默认有效期 20 分钟，并在对话框中显示倒计时。配对码过期或失效时可点击「刷新配对码」重新生成。
  </Step>

  <Step title="在本地 Codex 中执行接力">
    将提示词粘贴到本地 Codex 对话中。插件会将当前项目的 Git 跟踪文件与非忽略的未跟踪文件、Git 元数据，以及当前任务中可见的用户与助手消息（含用户消息附带的本地图片）打包上传到 Studio，创建一个临时云端 Codex Sandbox Session，恢复项目并注入会话历史，最后发送一条续跑消息让云端 Codex 继续任务。上传完成后云端任务独立运行，本地终端可断开。
  </Step>

  <Step title="查看进度并进入云端会话">
    对话框的「接力状态」面板按「等待端侧请求」「创建云端 Session」「恢复项目」「发送续跑任务」四个阶段展示进度。接力完成后点击「进入 Codex」即可在 Studio 中打开创建的云端 Sandbox Session 继续对话。
  </Step>
</Steps>

接力过程中云端 Codex 在后台执行，Studio 会在会话页面同步展示云端任务的进度与回复。若接力在创建 Session 之后、恢复项目或上传阶段失败，可使用原配对码重试，Studio 会复用已创建的 Session 而不会重复创建。

会话历史与图片迁移存在以下限制：

| 项目 | 限制 |
| :- | :- |
| 可见消息数 | 至多 100 条 |
| 单条消息字符数 | 至多 20,000 字符 |
| 会话历史总字符数 | 至多 100,000 字符 |
| 用户消息附带图片 | 至多 10 张，支持 PNG、JPEG、GIF、WebP |
| 单张图片大小 | 至多 4 MB |
| 图片总大小 | 至多 8 MB |
| 续跑消息长度 | 至多 20,000 字符 |
| 云端 Session 类型 | 仅临时 Session |

### 端云接力环境变量

| 环境变量 | 默认值 | 说明 |
| :- | :- | :- |
| `STUDIO_CODEX_PROJECT_HANDOFF_PAIRING_TTL_SECONDS` | `1200`（20 分钟） | 配对码有效期，取值范围 60–3600 秒。本地启动时通过环境变量配置，云端部署时写入 VeFaaS Function 环境。 |

## 更新已部署的智能体

已部署到 AgentKit 的智能体可以在 Studio 中重新编辑并更新到同一 Runtime，而不必每次创建新部署。更新会基于该 Runtime 的当前版本生成递增的镜像版本，并在原 Runtime 上发布新版本。

<Steps>
  <Step title="选择已部署的智能体">
    在智能体工作台中选择一个已部署的智能体。Studio 从该 Runtime 读取智能体的名称、描述、模型、系统提示词、工具与子智能体结构，并加载到可编辑草稿中。
  </Step>

  <Step title="修改配置">
    在画布或配置面板中调整模型、系统提示词、工具、技能或子智能体结构，与创建智能体时使用相同的编辑能力。
  </Step>

  <Step title="更新并发布">
    选择「更新并发布」。Studio 按准备、构建镜像、部署服务、发布的阶段展示进度；部署服务阶段会复用原 Runtime 标识并发布递增版本。
  </Step>

  <Step title="验证更新">
    更新完成后，工作台中该智能体的版本号递增，部署状态恢复为已发布。可在对话页面连接该 Runtime 验证新配置是否生效。
  </Step>
</Steps>

<Note>
  在更新过程中取消部署任务不会销毁已有 Runtime，原版本仍保持可用。仅创建全新部署时，取消任务才会清理未完成的 Runtime 资源。
</Note>

更新操作仍然受 Studio 角色权限约束：`admin` 可更新全部 Studio 管理的 Runtime，`developer` 只能更新自己创建的 Runtime，普通用户无权更新。

<Note>
  更新 Runtime 时，Studio 会从该 Runtime 加载已有环境变量并保留；在部署表单中显式填写的值覆盖原有值。选择 Runtime 目标进行调试测试时，该 Runtime 的环境变量会注入测试进程。
</Note>

<Note>
  更新已部署的智能体时，Studio 以该 Runtime 当前部署的配置为唯一来源重建可编辑草稿，不混入本地保存的旧草稿内容。若因网络或服务端错误无法读取该 Runtime 的 Agent 配置，更新入口会显示提示并暂时禁用更新，请稍后重试。
</Note>

### 更新模式

Studio 支持两种 Runtime 更新模式，根据该 Runtime 的当前状态自动选择：

| 更新模式 | 说明 |
| :- | :- |
| 重新生成 | 基于编辑后的草稿重新构建完整项目镜像并发布。适用于从草稿重新生成的常规更新。 |
| 保留源码更新 | 保留已部署的源镜像不变，仅将编辑后的配置（智能体草稿、技能和 MCP 认证）作为覆盖层发布到原镜像之上。适用于已部署镜像结构完整、只需调整配置的场景。 |

保留源码更新不会重新构建镜像，发布速度更快，且镜像中已有的技能文件保持不变。该模式下仅支持编辑根智能体的技能，不支持修改子智能体中的技能。

<Note>
  更新模式由 Studio 根据 Runtime 的当前镜像与配置自动判定，用户无需手动选择。若已部署镜像的结构不支持保留源码更新，Studio 自动使用重新生成模式。
</Note>

<Note>
  保留源码更新模式下，MCP 认证配置的更新依赖已发布草稿中的认证引用。如果 MCP 配置在发布后发生过变化，Studio 会提示重新打开智能体详情并确认最新配置后再更新。
</Note>

### 旧版 Runtime 恢复

对于在更新能力引入之前部署的 Runtime（缺少已发布配置草稿），Studio 可以从已部署的镜像和运行时环境中恢复智能体配置，使其同样支持更新。恢复过程包括：

* 从运行时环境变量和 MCP 工具集重建 MCP 工具配置；
* 从镜像中提取已部署的技能文件；
* 基于恢复的配置生成可编辑草稿。

<Warning>
  旧版 Runtime 恢复需要 Studio 运行身份对已部署镜像所在的容器镜像仓库具备只读权限。若当前身份缺少 CR 只读权限，技能文件无法提取，Studio 会提示为运行身份授予对应 CR 实例或仓库的只读权限后重试。
</Warning>

### 更新安全校验

更新 Runtime 时，Studio 在发布前后执行安全校验，防止并发修改导致线上配置被覆盖：

* 发布前检查 Runtime 的版本号和镜像标识是否与编辑时一致；若在此期间 Runtime 已被其他操作修改，更新会被拒绝并提示重新打开智能体详情。
* 发布后验证 Runtime 版本号已递增且状态为 Ready；若版本未递增或状态异常，更新标记为失败并提示刷新详情确认线上状态。

<Note>
  同一 Runtime 上已有正在进行的部署任务时，新的部署或更新请求会被拒绝并提示等待当前任务完成后再重试，避免并发部署产生冲突。
</Note>

<Note>
  部署进度通过流式连接实时展示。长时间构建期间，Studio 定期发送心跳保活消息，防止代理或浏览器因空闲超时断开连接。
</Note>

<Note>
  更新能力检查可能需要读取运行时配置，首次检查耗时较长时显示「恢复中」状态并暂时禁用更新；检查完成后自动恢复更新入口。
</Note>

## 通过 GitHub 交付智能体

Studio 可将自定义创建生成的智能体源码交付到 GitHub 仓库，提供两种交付模式。「GitHub 代码同步」把生成的源码直接推送到目标分支，Runtime 仍由部署按钮发布；「挂载持续交付」在目标分支写入 AgentKit Runtime 的 GitHub Actions 工作流，后续向该分支推送代码会自动构建并发布到绑定的 Runtime。两种模式适用于需要版本管理与持续交付的团队。

<Note>
  「挂载持续交付」会向仓库写入 GitHub Actions Secret，需要安装 `github-cicd` 可选依赖组以提供加密能力，安装方式见[安装](/productions/veadk/preview/zh/get-started/installation)。「GitHub 代码同步」不写入 Secret，无需该依赖。
</Note>

### 交付模式

在部署配置区选择 GitHub 交付后，可在以下两种模式间切换：

| 模式 | 行为 | 是否写入工作流与 Secret |
| :- | :- | :- |
| GitHub 代码同步 | Studio 将生成的源码直接推送到目标分支；该分支由 Studio 管理，远端冲突时同步会失败。Runtime 仍由部署按钮发布。 | 否 |
| 挂载持续交付 | 首次部署成功后初始化目标分支（写入源码与 GitHub Actions 工作流），后续向该分支推送代码会触发工作流并更新绑定的 Runtime。 | 是 |

### 配置 GitHub 交付

两种模式共用以下表单字段：

| 字段 | 必填 | 默认值 | 说明 |
| :- | :- | :- | :- |
| GitHub 仓库 URL | 是 | — | 支持 `owner/repository` 或完整 GitHub HTTPS/SSH 地址，仅支持 `github.com`。 |
| GitHub Token | 是 | — | 需要对目标仓库的 contents 写入和 pull request 权限；仅用于当前请求，不下发浏览器持久化。 |
| 目标分支 | 否 | `main` | 源码推送与工作流监听的分支。 |
| 火山引擎 Access Key | 挂载持续交付必填 | — | 用于写入 GitHub Actions Secret，供工作流发布 Runtime。 |
| 火山引擎 Secret Key | 挂载持续交付必填 | — | 用于写入 GitHub Actions Secret。 |
| 火山引擎 Session Token | 否 | — | 使用临时凭据时必填。 |

使用 BytePlus 作为云服务商时，对应的 Secret 名称与 Runtime 发布凭据为 `BYTEPLUS_ACCESS_KEY`、`BYTEPLUS_SECRET_KEY` 和可选的 `BYTEPLUS_SESSION_TOKEN`；火山引擎模式下为 `VOLCENGINE_ACCESS_KEY`、`VOLCENGINE_SECRET_KEY` 和可选的 `VOLCENGINE_SESSION_TOKEN`。地域沿用部署配置区的发布区域。

<Warning>
  挂载持续交付会将火山引擎或 BytePlus 凭据加密写入目标仓库的 GitHub Actions Secret。请确认目标仓库的访问范围与协作权限符合数据安全要求，并使用具备最小权限的凭据。
</Warning>

### 部署时挂载持续交付

选择「挂载持续交付」创建新 Runtime 时，点击部署后 Studio 会先创建 Runtime，再执行「挂载 GitHub 持续交付」阶段：初始化目标分支并写入 GitHub Actions 工作流，初始化成功后才完成部署流程。该阶段在部署进度中独立展示，并实时显示 GitHub 挂载日志，可在同步中、已同步或读取失败等状态间展开与复制，日志在服务端完成凭据脱敏后下发。

工作流文件写入仓库的 `.github/workflows/publish-agentkit.yml`，在以下情况触发：

* 推送到目标分支（提交信息包含 `[skip runtime]` 时跳过发布）；
* 手动触发。

工作流使用与 Runtime 绑定的并发组，安装项目依赖与 AgentKit Python SDK，并发布 Runtime 的递增版本。BytePlus 模式下工作流额外注入 BytePlus 凭据与记忆地域环境变量。

### 版本管理与回退

在工作台选中已绑定 GitHub 持续交付的 Runtime 后，详情页提供「版本」标签。该标签列出目标分支的提交历史与工作流运行记录，每个版本显示提交、分支、来源、发布状态与创建时间：

| 发布状态 | 含义 |
| :- | :- |
| 已发布 | 该版本已成功发布到 Runtime。 |
| 发布中 | 工作流正在构建或发布。 |
| 等待发布 | 源码已推送，等待工作流触发。 |
| 发布失败 | 工作流运行失败。 |

选择某个历史版本可创建回退。已挂载持续交付时，Studio 自动合并回退 Pull Request，将目标分支恢复到所选版本并触发工作流发布该版本；仅做代码同步时，Studio 创建回退 Pull Request 等待人工合并。回退事件同样记录在版本列表中。

### 使用命令行同步源码

除 Studio 界面外，可使用 `veadk github-cicd-pipeline` 命令将 Studio 导出的 AgentProject JSON 推送到目标分支，对应「GitHub 代码同步」模式：

```bash lines theme={null}
veadk github-cicd-pipeline \
  --github-url https://github.com/org/repo \
  --github-branch main \
  --github-token "$GITHUB_TOKEN" \
  --project-json ./agent-project.json \
  --region cn-beijing
```

| 参数 | 必填 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `--github-url` | 是 | — | GitHub 仓库地址。 |
| `--github-branch` | 否 | `main` | 源码推送的目标分支。 |
| `--github-token` | 是 | — | GitHub Token，需对目标仓库有 contents 写入权限。 |
| `--project-json` | 是 | — | Studio 导出的 AgentProject JSON 文件路径。 |
| `--region` | 否 | `cn-beijing` | AgentKit Runtime 地域。 |

该命令仅同步源码到目标分支，不写入 GitHub Actions 工作流与 Secret，也不会发布 Runtime。

<Note>
  与「自动化集成」中的 [AgentKit Runtime 持续交付](#agentkit-runtime-持续交付) 不同，本节能力内嵌在自定义创建的部署流程中，针对 Studio 生成的智能体源码，并可在创建 Runtime 的同时初始化 GitHub 交付。两者可按需分别使用。
</Note>

## 查看接入方式

在「管理智能体」中选择一个已部署的智能体后，详情页提供「接入方法」标签。该标签探测当前 Runtime 实际暴露的公开接入协议与端点，并给出可直接参考的调用示例，方便在不查阅控制台的情况下从外部调用该智能体。

<Note>
  接入方式由 Studio 在打开标签时向 Runtime 发起只读探测确认，仅展示已确认的协议与地址。Runtime 未暴露的协议显示为不可用，Studio 不会虚构未确认的端点。
</Note>

### 支持的协议

| 协议 | 发现方式 | 调用地址 |
| :- | :- | :- |
| API Server | 探测 Runtime 的 `/list-apps` 接口 | `<Runtime 公网端点>/run_sse` |
| A2A | 读取 Runtime 的 `/.well-known/agent-card.json` | Agent Card 中声明的调用地址 |

探测期间 Studio 会显示加载状态。若探测因网络或鉴权问题失败，标签内会显示错误提示并提供「重试」按钮；Runtime 未暴露某个协议时该协议显示为不可用，不影响另一协议的展示。

### 鉴权方式与 API Key

标签会显示 Runtime 当前的鉴权方式：

| 鉴权方式 | 说明 |
| :- | :- |
| API Key | Runtime 使用 API Key 鉴权。 |
| OAuth / JWT | Runtime 使用自定义 JWT 鉴权。 |
| 无需鉴权 | Runtime 未启用鉴权。 |

当鉴权方式为 API Key 时，标签会显示 API Key 字段。出于安全考虑，API Key 默认以 `****` 掩码显示，仅当点击显示按钮后才会向 Runtime 请求真实值并在页面中短暂展示；切换标签或离开当前智能体后会自动清除已显示的值。示例代码中的凭证始终使用占位符，不会填入真实 API Key。

<Warning>
  显示的 API Key 会出现在浏览器中。仅向经过授权的用户开放 Studio，并在使用后及时关闭显示；如需在程序中调用，应通过密钥管理服务或环境变量获取凭证，不要从 Studio 页面复制明文密钥长期保存。
</Warning>

### 调用示例

标签根据探测到的协议和鉴权方式，生成对应的 Python 请求示例。示例中的端点和应用名称来自探测结果，凭证使用占位符。

API Server 协议的示例通过 `requests` 创建会话并调用 `/run_sse` 流式接口：

```python lines theme={null}
import uuid

import requests

BASE_URL = "<Runtime 公网端点>"
APP_NAME = "<应用名称>"
USER_ID = "demo-user"
SESSION_ID = str(uuid.uuid4())
API_KEY = "<API_KEY>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

session_response = requests.post(
    f"{BASE_URL}/apps/{APP_NAME}/users/{USER_ID}/sessions/{SESSION_ID}",
    headers=HEADERS,
    json={},
    timeout=30,
)
session_response.raise_for_status()

with requests.post(
    f"{BASE_URL}/run_sse",
    headers=HEADERS,
    json={
        "app_name": APP_NAME,
        "user_id": USER_ID,
        "session_id": SESSION_ID,
        "new_message": {
            "role": "user",
            "parts": [{"text": "你好，请介绍一下自己"}],
        },
        "streaming": True,
    },
    stream=True,
    timeout=120,
) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line:
            print(line.decode("utf-8"))
```

A2A 协议的示例通过 JSON-RPC `message/send` 方法调用智能体：

```python lines theme={null}
import uuid

import requests

AGENT_URL = "<A2A 调用地址>"
API_KEY = "<API_KEY>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

response = requests.post(
    AGENT_URL,
    headers=HEADERS,
    json={
        "jsonrpc": "2.0",
        "id": str(uuid.uuid4()),
        "method": "message/send",
        "params": {
            "message": {
                "messageId": str(uuid.uuid4()),
                "role": "user",
                "parts": [{"kind": "text", "text": "你好，请介绍一下自己"}],
            }
        },
    },
    timeout=120,
)
response.raise_for_status()
print(response.json())
```

<Note>
  示例仅用于说明调用方式。实际端点、应用名称和鉴权方式以标签中探测到的结果为准；未启用鉴权时无需传入 `Authorization` 头。
</Note>

## 浏览智能体

侧边栏的「智能体」入口打开智能体目录，用于浏览、连接和查看当前账号下的 AgentKit Runtime。对话页面顶部导航栏的智能体选择器也提供进入该目录的入口。

智能体目录通过顶部的类型筛选切换，默认显示「通用智能体」：

| 类型 | 说明 |
| :- | :- |
| 通用智能体 | 列出当前用户可见的 AgentKit Runtime，可见范围取决于角色权限。 |
| Codex | 跳转到 Codex 临时会话创建入口。 |
| DeepSeek | 跳转到 DeepSeek 工作区会话创建入口。 |
| OpenClaw | 暂未开放。 |
| Hermes | 暂未开放。 |

通用智能体列表提供创建人、区域和名称筛选。创建人筛选可在「全部」与「我创建的」之间切换：「全部」仅对 `admin` 角色可用，`developer` 和普通用户仅能查看自己创建的 Runtime。区域筛选默认为 Studio 当前地域，可切换到当前云服务商支持的其他地域。列表按所选地域分页加载，滚动到底部时自动加载下一页，加载完成后提示「已加载全部智能体」。使用搜索框可按名称过滤已加载的智能体。

每张智能体卡片显示 Runtime 名称、描述、创建人和创建时间。创建时间以相对时间显示（如「3 分钟前」）。点击卡片进入该 Runtime 的详情视图，卡片上的「连接」按钮将该 Runtime 设为当前对话使用的智能体并切换到对话页面；已连接的智能体会置顶显示。具备创建权限时，列表首张卡片为「创建智能体」入口。列表加载失败时显示错误信息并提供「重新加载」按钮，列表为空时显示对应的空状态提示。连接失败时的排查方式与[选择云端 Runtime](#选择云端-runtime)一致。

<Note>
  智能体目录中的每张 Runtime 卡片在加载后会自动检测该 Runtime 是否支持 Studio 对话。检测期间卡片显示「检测中」状态并禁用「连接」按钮。检测完成后，支持对话的 Runtime 不显示额外标识；不支持对话的 Runtime 显示「不支持对话」标识；检测出错时显示「检测失败」标识。检测失败或不支持对话时，卡片提供「重试」按钮以重新发起检测。检测结果按 Runtime 版本缓存，Runtime 版本更新后自动重新检测。
</Note>

## 选择云端 Runtime

在云端模式下，对话页面顶部的智能体选择器会列出当前用户可见的 AgentKit Runtime，可见范围与「管理智能体」一致，由登录账号的角色决定，并按区域分页浏览。每条 Runtime 提供两个独立操作：

* **连接**：将该 Runtime 设为当前对话使用的智能体，选择器随即关闭并切换到该 Runtime。
* **信息**：展开一个分标签信息面板，无需连接或持久化即可预览该 Runtime 的能力。

信息面板包含两个标签：

* **智能体信息**：读取 Runtime 提供的名称、模型、描述、子智能体、工具、技能、可用检索源，以及已挂载组件及其后端类型。该信息不包含系统提示词、凭据或环境变量值。
* **Runtime 详情**：展示 Studio 可读取的模型、描述、状态、区域、资源规格、版本和环境变量。

<Note>
  「Runtime 详情」标签可能展示 Runtime 的环境变量值。仅向经过授权的用户开放 Studio，并优先使用平台支持的密钥管理能力。
</Note>

连接 Runtime 时，Studio 会先对只读接口（智能体列表、智能体信息、会话列表）进行就绪探测：若 Runtime 刚部署尚未就绪，Studio 会自动重试，最多 3 次，每次间隔递增（最长 5 秒）。私网 Runtime 不进行重试。重试耗尽或遇到其他错误后仍无法连接时，Studio 会区分失败原因并给出对应提示，便于直接定位问题：

* **权限不足**：当前账号无权访问该 Runtime，可刷新列表或重新登录后重试。
* **Agent Server 不可连接**：Runtime 的 Agent Server 未提供连接接口，通常是 Runtime 尚未就绪或版本不兼容，需确认 Runtime 状态与版本。
* **私网 Runtime 不可达**：Runtime 仅部署在 VPC 内且未暴露公网地址，而当前 Studio 所在环境无法访问该 VPC。请使用已绑定相同 VPC 的 Studio 访问，或改用公网或公网 + VPC 部署模式。
* **鉴权失败**：Runtime 服务拒绝了连接请求，需检查 Runtime 的鉴权配置。

这样无需查看日志即可判断应刷新、重新登录，检查 Runtime 就绪状态，还是调整网络部署模式。

<Note>
  加载智能体信息或 Runtime 详情失败时，详情面板会显示错误信息并提供「重试」按钮，可重新加载对应内容。
</Note>

## 新会话工作区

新建会话时，Studio 在会话页面顶部提供三种工作区模式，模式选择器对所有已登录用户可见：

* **智能体**：与当前选中的智能体对话，或使用内置智能体进行临时会话。
* **技能定制**：从自然语言描述生成新技能，或对已有技能进行优化。该模式仅在管理员配置了可用的 Dev Sandbox 时显示。
* **视频创作**：根据文本提示和可选的参考素材生成视频。

### 智能体对话与内置智能体

智能体工作区支持两种模式：

* **智能体对话**：与当前选中的智能体进行普通多轮对话。空输入时显示快捷提示，可点击快速填入常用提问。
* **内置智能体**：使用平台提供的智能体进行对话。当前可选 Codex 智能体和 DeepSeek Harness。Codex 智能体在独立的 AgentKit CodeEnv Session 中使用专用编辑器进行多轮对话；DeepSeek Harness 在独立的 AgentKit CodeEnv Session 中打开 DeepSeek Harness 工作区。两者退出后均删除云端 Session，内容不写入普通历史会话。

普通对话在同一会话中发送后续消息时会继续使用已有消息历史；只有新建会话才会从空上下文开始。若 Runtime 无法连接，Studio 会区分权限不足、Agent Server 不可达、私网 Runtime 不可达和鉴权失败，并显示对应的排查方向。

<Note>
  与内置 Codex 智能体对话时，若 Codex app-server 返回错误或连接中断，Studio 会在对话中展示完整的错误详情，包括 JSON-RPC 错误码、错误消息和附加数据，以及导致错误的底层原因。所有错误信息在展示前均做凭据脱敏处理。
</Note>

<Note>
  内置 Codex 会话在连接空闲超时或传输层断开后会自动恢复。Studio 会在下一次发送消息或请求时重建连接并恢复当前 Thread，保留已有的对话历史、工作空间锁定状态与上下文用量，无需手动新建会话。恢复过程对用户透明；若恢复失败，仍会在对话中展示经过凭据脱敏的错误详情。
</Note>

<Note>
  在云端模式下，Studio 不会自动选择第一个可用智能体。开始新会话前需在对话页面顶部的智能体选择器中手动连接一个 Runtime；未选择智能体时开始新会话会提示先选择智能体，并打开智能体管理页。
</Note>

### 本地配置

本地使用内置智能体前，准备一个处于 `Ready` 状态的 AgentKit CodeEnv Tool，并配置其 ID：

```bash lines theme={null}
export SANDBOX_CHAT_CODEX="your-chat-code-env-tool-id"

veadk studio --agents-dir ./agents --open
```

| 环境变量 | 默认值 | 说明 |
| :- | :- | :- |
| `SANDBOX_CHAT_CODEX` | — | 内置智能体使用的 AgentKit CodeEnv Tool ID；本地使用该模式时必填。 |
| `AGENTKIT_SANDBOX_REGION` | `cn-beijing` | 内置智能体在创建 Session、查找 Tool 时优先使用的地域，支持 `cn-beijing` 与 `cn-shanghai`。 |

<Note>
  创建内置智能体的 Session、查找对应 Tool 时，Studio 会优先使用 `AGENTKIT_SANDBOX_REGION` 指定的地域；火山引擎模式下未设置时依次回退到 `REGION` 环境变量与默认 `cn-beijing`。若该地域返回资源不存在，会自动回退到另一个支持地域（北京 ↔ 上海）继续操作，其他错误不会触发回退。部署到 VeFaaS 时该地域与 `--region` 一致。
</Note>

<Note>
  Codex 智能体和 DeepSeek Harness 共用同一个 AgentKit CodeEnv Tool（`SANDBOX_CHAT_CODEX`），无需为 DeepSeek Harness 单独配置 Tool。两类内置智能体的会话通过 agent 类型标识区分，不会互相影响。
</Note>

### Codex 会话控件

选择 Codex 智能体后，对话使用专用的 Codex 会话编辑器。该编辑器在输入框左侧提供权限与工作空间入口，在「添加」菜单中提供终端、浏览器与文件上传入口，并支持快捷命令、模型切换和 Skill 调用。这些控件只作用于当前 Sandbox Session，不修改已部署的智能体。

#### 快捷命令

在输入框中以 `/` 开头可调出快捷命令菜单，支持按名称或关键词筛选。选中的命令会填入输入框，回车发送后由当前 Codex Session 执行。

| 命令 | 说明 |
| :- | :- |
| `/model [model]` | 显示或切换当前对话模型。不带参数时列出可用模型供选择。 |
| `/models` | 列出当前可用的模型。 |
| `/skill` | 浏览并调用当前工作区可用的 Skill。 |
| `/skills` | 浏览并调用当前工作区可用的 Skills。 |
| `/new` | 开始一个新对话。 |
| `/resume [thread]` | 打开历史会话列表，或恢复指定的 thread。 |
| `/fork` | 从当前上下文分叉一个新对话。 |
| `/compact` | 压缩当前对话上下文。 |
| `/archive` | 归档当前对话并新建对话。 |
| `/status` | 显示当前连接、thread、模型与 token 状态。 |
| `/clear` | 清空当前视图并开始新对话。 |
| `/help` | 显示支持的快捷命令。 |

#### 模型与 Skill

输入 `/model ` 可触发模型列表，从中选择或直接输入模型 ID 切换当前对话使用的模型。输入 `$` 可浏览当前工作区可用的 Skill，选中后以标签形式插入输入框，发送时一并提交；在输入框为空时按退格键可移除最后一个已选 Skill。

#### 工作空间

点击输入框左侧的工作空间按钮可选择当前 Codex Thread 执行命令与修改文件的目录。在对话框中可直接输入绝对路径或浏览目录树选择。对话开始后工作空间会被锁定，需新建 Sandbox 会话后才能重新选择。

<Note>
  当管理员启用 `STUDIO_EXPOSE_SANDBOX_ENDPOINT` 环境变量（设为非 `0`/`false` 值）后，Codex 会话编辑器输入框旁会显示「复制 Sandbox Endpoint」按钮，可将当前 Sandbox 的公开端点复制到剪贴板。未启用时该按钮不显示。该变量在本地启动与云端部署的 Studio 中均通过环境变量配置，默认关闭。
</Note>

#### 权限

点击输入框左侧的权限按钮可打开「Codex 权限」对话框。设置保存到当前 Sandbox Session，并同步到其中的所有 Thread。

| 设置 | 可选值 | 说明 |
| :- | :- | :- |
| 沙箱模式 | 只读 / 工作区写入 / 完全访问 | 控制文件系统隔离范围。选择「完全访问」时会关闭文件系统与网络隔离，并自动启用网络访问。 |
| 审批策略 | 仅不可信命令 / 按需审批 / 不审批 | 决定 Codex 何时暂停并请求人工确认命令或文件修改。 |
| 审批方式 | 由我审批 / 自动审查 | 选择审批请求由你在 Studio 中处理，还是交由 Codex 自动审查流程处理。 |
| 允许网络访问 | 开 / 关 | 控制「工作区写入」与「只读」模式中的外部网络访问。「完全访问」时固定为开且不可关闭。 |

<Warning>
  「完全访问」会关闭文件系统与网络隔离，仅应在任务可信且需要完整主机权限时使用。
</Warning>

#### 操作审批

当审批策略需要人工确认且 Codex 请求执行命令或修改文件时，Studio 会弹出审批对话框，展示待审批的命令、文件变更和执行目录。可选择「拒绝」「仅本次允许」或「本会话允许」。审批结果会以活动记录的形式显示在对话中。

#### 终端与浏览器

在「添加」菜单中选择「进入终端」或「查看浏览器」，可在当前 AgentKit Session 中打开交互式终端或浏览器视图。连接过程中显示加载状态，打开失败时可重试。还可以从该菜单上传图片、文档或 PDF 以及视频到当前对话；上传的图片会在对话中显示预览，点击后通过共享图片查看器打开。

#### 状态与历史

`/status` 会以活动记录形式展示当前 Thread、工作空间、模型、运行状态、累计 Token 与上下文窗口。每轮助手回复后会显示该轮的 Token 用量。输入 `/resume` 可打开「恢复 Codex 对话」对话框，选择最近更新的 Thread 恢复。

<Note>
  沙箱会话列表中的「创建者」显示当前登录用户的显示名称（OAuth 邮箱或本地用户名），便于在多用户部署中区分会话归属；未获取到显示名称时回退为内部用户标识。显示名称的 UTF-8 编码超出会话元数据字节上限时，Studio 会按字符边界截断并追加省略号，确保会话创建不受影响。
</Note>

<Note>
  当内置智能体的会话结束后留下可恢复的快照时，管理员打开沙箱会话列表会自动恢复当前智能体类型的可恢复快照：Studio 在后台并发恢复（至多 3 个），恢复完成后列表刷新并直接展示就绪的会话，无需手动唤醒。恢复失败的快照会被跳过，不影响其余会话展示。该能力仅对 `admin` 角色开放，且仅在已配置对应的沙箱快照 Tool 时可用。
</Note>

## 技能定制

技能定制工作区在新建会话页面提供技能生成与优化的快捷入口，复用技能中心的 Dev Sandbox 技能生成能力。该模式仅对 `developer` 和 `admin` 角色开放，且仅在管理员配置了处于可用状态的 Dev Sandbox 及其模型凭据后才会在工作区模式选择器中显示；未配置时该模式被隐藏，不会展示无法完成的操作。

### 技能生成

在输入框中用自然语言描述目标技能，例如「生成一个用于分析 CSV 文件并输出统计摘要的技能」，发送后 Studio 会跳转到技能中心 Dev Sandbox 技能生成工作台，并以该描述作为初始意图预填入。

### 技能优化

切换到「技能优化」后，先从 AgentKit SkillSpace 中选择需要优化的技能空间与技能，再在输入框中描述优化目标，例如「增强对中文列名的兼容性」。发送后 Studio 跳转到技能中心工作台，对所选技能执行优化并可覆盖发布到原技能空间。

<Note>
  技能定制的生成与优化流程、Dev Sandbox 会话管理、候选方案对比与发布方式与[技能中心](#技能中心)一致，工作区仅作为快捷入口。浏览 AgentKit SkillSpace 由 Studio 服务端使用自身配置的火山引擎凭证完成，浏览器不接触凭据。
</Note>

## 视频创作

视频创作工作区根据文本提示和可选的参考素材生成视频，适用于内容创作、素材预览等场景。该模式对所有已登录用户开放；上传参考素材需要管理员配置持久化存储，未配置时参考素材上传被禁用，但文生视频不受影响。

### 使用方式

1. 在新建会话页面选择「视频创作」工作区。
2. 选择视频任务模式，并按需上传参考素材、设置画面比例、分辨率和时长。
3. 在输入框中输入视频描述，发送后 Studio 会先优化提示词，再创建视频生成任务。
4. 在视频任务对话框中查看生成进度：生成阶段会区分任务排队与模型生成状态并显示已等待时长。生成过程中可以关闭对话框，任务会在后台继续运行，不影响生成结果；生成完成后可预览和下载结果视频。

### 视频任务模式

| 模式 | 说明 | 参考素材 |
| :- | :- | :- |
| 自动识别 | 根据提示词和已上传素材自动判断使用以下哪种模式。 | 按实际模式要求 |
| 文生视频 | 仅根据文本提示生成视频，不使用参考素材。 | 无 |
| 参考素材生视频 | 根据参考图片或参考视频生成新视频。 | 参考图片或参考视频 |
| 视频编辑 | 对已有视频按提示词进行编辑。 | 待编辑视频 |
| 视频续写 | 在已有视频末尾续写新内容。 | 基础视频 |
| 首尾帧生成 | 根据首帧和可选尾帧图片生成视频。 | 首帧图片（必需），尾帧图片（可选） |

### 生成参数

| 参数 | 可选值 | 默认值 | 说明 |
| :- | :- | :- | :- |
| 画面比例 | `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` | `16:9` | 生成视频的宽高比。 |
| 分辨率 | `480p`、`720p` | `720p` | 生成视频的清晰度。 |
| 时长 | 4–30 秒 | 8 秒 | 生成视频的时长；视频编辑模式按原视频时长处理。 |

### 生成流程

视频生成分为两个阶段，均在 Studio 服务端完成：

1. **提示词优化**：使用增强模型对输入的提示词进行扩写和规范化，并解析最终的任务模式。
2. **视频生成**：使用生成模型按优化后的提示词和参数创建视频任务，任务完成后返回预览地址和下载链接。

不同云服务商使用的模型如下：

| 云服务商 | 生成模型 | 增强模型 |
| :- | :- | :- |
| 火山引擎 | `doubao-seedance-2-5-260628` | `doubao-seed-2-1-pro-260628` |
| BytePlus | `dreamina-seedance-2-5-260628` | `dola-seed-2-1-turbo-260628` |

<Note>
  视频生成过程异步执行，对话框实时显示优化和生成两个阶段的状态：生成阶段会区分任务排队与模型生成并显示已等待时长。生成过程中可以关闭对话框，任务会在后台继续运行，不影响生成结果。任一阶段失败时，对话框会显示服务端返回的错误详情（已自动脱敏其中的密钥与签名信息），可从失败阶段重试，无需重新输入提示词。
</Note>

### 参考素材与持久化存储

参考素材上传和生成结果保存依赖 Studio 持久化存储。未配置持久化存储时，参考素材上传控件被禁用并在对应位置显示「管理员未配置持久化存储」，文生视频等纯文本功能不受影响。持久化存储的配置方式见 [Studio 持久化存储](#studio-持久化存储)。

<Warning>
  参考素材和生成结果存储在 Studio 配置的 TOS 存储桶中，按登录用户隔离。请勿上传包含敏感信息的素材。
</Warning>

## 管理会话能力

VeADK 1.0.9 起，连接的 Runtime 暴露会话级能力叠加接口时，Studio 可管理当前会话的工具与技能。

当连接的 Runtime 暴露会话级能力叠加接口时，对话页面的智能体信息面板会在工具与技能列表中显示「在此对话中添加工具」与「在此对话中添加技能」入口。添加的能力仅对当前会话生效，不修改已部署的根智能体，也不会写入其他会话。

* **内置工具**：从 VeADK 内置工具目录中选择，可按中文名称或工具标识搜索。
* **远程技能**：从公域 Skill Hub 搜索，或从 AgentKit Skill 中心按地域与项目浏览后选择。

已挂载的会话能力可在同一面板中移除，移除后该能力在当前会话中不再可用。会话中的对话通过会话感知的运行接口执行，确保叠加的工具与技能实际参与调用。

列举与挂载远程技能需要火山引擎凭证；本地通过 `VOLCENGINE_ACCESS_KEY` 与 `VOLCENGINE_SECRET_KEY` 提供，VeFaaS 部署使用绑定的 IAM Role。能力叠加接口的完整端点与参数见[部署到 AgentKit](/productions/veadk/preview/zh/deploy/agentkit)。

## 自动评测与优化反馈

部署到 AgentKit 的智能体在工作台中支持自动评测和优化反馈。部署时开启「自动创建评测集」后，Studio 会为该智能体创建 Good Case 和 Bad Case 评测集；会话结束后，Studio 自动评估每轮对话的质量并归入对应评测集，再基于累计的评测案例生成优化建议。

### 评测集创建

部署配置区提供「自动创建评测集」开关，默认开启。部署成功后，Studio 调用 AgentKit 评测接口为该智能体幂等创建 `{agent_name}_good_case` 与 `{agent_name}_bad_case` 两个评测集。创建过程在「创建评测集」阶段执行，完成后部署流程进入结束阶段。

<Note>
  评测集创建失败不影响已部署的 Runtime。失败时部署结果中会显示警告信息，已成功部署的智能体仍可正常使用。
</Note>

### 自动评测

用户在 Studio 中与已部署智能体对话时，每轮对话结束后 Studio 会等待一段静默时间（默认 300 秒），然后自动评估该轮对话的质量。评估过程如下：

1. Studio 从 Runtime 读取该轮会话的最新助手回复。
2. 调用 `doubao-seed-2-0-lite-260428` 模型，从任务完成度、事实与逻辑可靠性、工具使用合理性、清晰度和安全性等维度对回复评分。
3. 评分范围为 0–1；评分不低于 0.6 的归入 Good Case 评测集，低于 0.6 的归入 Bad Case 评测集。
4. 自动评测案例会写入对应的 AgentKit 评测集，并在案例列表中标记来源为「自动回流」，同时展示评分和评分理由。

<Note>
  如果用户在同一会话中发送新消息，静默计时会被重置，确保只在对话暂停后才执行评测。
</Note>

### 优化建议

当自动评测积累了足够的案例后，Studio 基于该智能体已有的评测案例生成优化建议。优化建议按优先级和模块分组展示在工作台的「优化项」标签中：

| 字段 | 说明 |
| :- | :- |
| 修复优先级 | 按高、中、低标注每组的修复紧迫程度。 |
| 建议优化模块 | 标注建议改进的模块，包括智能体结构、提示词、工具、知识库、记忆、工作流等。 |
| 优化建议和理由 | 每条建议包含具体的改进描述和对应的评分依据。 |

<Note>
  优化建议由 `doubao-seed-2-0-lite-260428` 模型根据累计评测案例和智能体配置生成，仅供参考。评测模型可通过环境变量 `VEADK_STUDIO_EVALUATION_MODEL` 覆盖。
</Note>

<Note>
  配置 Studio 持久化存储时，优化项快照保存在 TOS 中，进程重启后仍然可见，并在多个实例间共享；未配置持久化存储时，优化项快照仅保留在进程内存中，重启后丢失。持久化存储的配置方式见 <a href="#studio-持久化存储">Studio 持久化存储</a>。
</Note>

### 标注回复为 Bad Case

在与已部署智能体对话时，可以直接在助手回复中选中一段文字并添加批注，将该轮回复作为 Bad Case 评测案例保存到对应的 Bad Case 评测集。批注会保留选中的文字片段和说明，便于后续基于具体片段定位问题。

该能力仅在以下条件同时满足时可用：

* 连接到已部署的火山引擎 Runtime（BytePlus 部署和本地调试会话不支持）；
* 回复已生成结束（流式输出进行中或等待授权时不可用）。

使用方式：

1. 在助手回复气泡中选中一段文字，松开鼠标后会在选区附近弹出批注弹窗，并展示已选中的文字片段。
2. 在「批注内容」输入框中说明问题或期望的修改方式。
3. 点击「加入 Bad Case」，Studio 将选中片段与批注说明组合保存为评测案例的备注，并把该轮回复写入 Bad Case 评测集。提交成功后弹窗显示确认信息。

选中文字至多保留 700 个字符，批注说明至多 1200 个字符，组合后的备注至多 2000 个字符，超出部分会被截断。若保存失败，批注弹窗保持打开并提示错误，可在修正后重试。

<Note>
  标注保存的 Bad Case 评测案例在案例列表中标记来源为「手动回流」，评分显示为 0 分，评分理由显示为批注内容；通过赞/踩创建且未附带批注的手动回流案例评分仍显示为「—」。
</Note>

### 查看评测案例

工作台的「评测集」标签展示该智能体的所有评测案例，支持按 Good Case / Bad Case 和自动回流 / 手动回流筛选。自动回流案例显示评分（0–100 分制）和评分理由；通过赞/踩创建且未附带批注的手动回流案例评分列显示为「—」，通过标注创建的手动回流案例显示评分与批注理由。两种来源的案例均可删除。

## 自动化集成

Studio 侧边栏的「自动化」页面提供研发工具和消息渠道的自动化集成。自动化按分类组织，当前包括「研发」和「消息渠道」两个分类。Coding Agents 集成在本地检测并配置已安装的编程智能体客户端；GitHub 自动化通过浏览器直接调用 GitHub API 创建分支、文件和 Pull Request；飞书自动化在 Studio 中生成基础智能体并直接部署到 AgentKit Runtime；网站集成将已部署 Runtime 以悬浮聊天窗口嵌入外部网站。

### 配置 Coding Agents

将 VeADK 与 AgentKit 内置 Skills 全局安装到本机已安装的编程智能体客户端，使其在开发 VeADK 应用时具备构建、调试、部署与平台操作能力。该集成标记为「本地」，仅在启动 Studio 的本机执行检测与安装，不访问云资源。

<Note>
  「配置 Coding Agents」卡片仅在通过 `http://127.0.0.1` 访问 Studio 时启用。通过其他主机名（包括 `localhost` 或已部署的 VeFaaS 公网地址）访问时，该卡片显示为禁用状态，并提示「仅本地部署可用」。
</Note>

打开「自动化」页面中的「配置 Coding Agents」卡片后，Studio 会检测当前操作系统（macOS、Linux、Windows）下已安装的编程智能体客户端，并展示可全局安装的内置 Skills。

支持的编程智能体客户端：

| 客户端 | 检测方式 | 全局 Skills 安装路径 |
| :- | :- | :- |
| Trae | 命令行 `trae` 或 `trae-cn`、主目录下的 `.trae` 或 `.trae-cn` 标记，或已安装的 Trae 应用（macOS 的 `/Applications`、Windows 的程序目录） | `~/.trae/skills` |
| Claude Code | 命令行 `claude` 或主目录下的 `.claude` 标记 | `~/.claude/skills` |
| Codex | 命令行 `codex`、主目录下的 `.codex` 或 `.agents` 标记，或已安装的 ChatGPT/Codex 应用 | `~/.agents/skills` |

检测到命令行可执行文件时，Studio 还会显示其版本号；未检测到时标注为不可用。

内置 Skills 为固定集合，不可自定义内容：

| Skill | 说明 |
| :- | :- |
| `veadk-agent-development` | VeADK 开发技能，用于构建、调试并交付基于 VeADK 的智能体应用。 |
| `agentkit-cli` | AgentKit 平台操作技能，使用 AgentKit CLI 管理部署、运行时与平台资源。 |

选择一个或多个已检测到的客户端与一个或多个内置 Skills 后，Studio 会将所选 Skills 写入对应客户端的全局 Skills 目录（如 `~/.claude/skills/<skill_id>`）。每个 Skill 以独立子目录写入，包含 `SKILL.md` 及其附带的脚本、参考文档和资源。

<Note>
  浏览器只能从固定的客户端与 Skill 标识中选择，不接受任意的 Shell 命令、文件系统路径或 Skill 内容；Skills 来源于 Studio 内置资源，不来自浏览器上传。安装前可预览每个 Skill 包含的文件。
</Note>

安装采用原子替换：Studio 先将 Skill 文件写入临时目录，校验通过后再替换目标目录；目标目录已存在同名 Skill 时会先备份再替换，安装失败时自动回滚到原内容。

<Warning>
  安装会写入启动 Studio 的用户主目录下的全局 Skills 路径。请确认运行 Studio 的用户身份与编程智能体客户端所属用户一致，避免 Skills 安装到错误的用户目录。
</Warning>

启用角色权限控制时，配置 Coding Agents 需要 `developer` 或 `admin` 角色。

### 模板项目导入

在目标仓库中创建一个包含完整 Studio App Server 的最简 VeADK 智能体项目，并附带持续交付工作流。提交后 Studio 在目标仓库创建发布分支，发起包含模板文件和 GitHub Actions 工作流的 PR。

模板项目包含 `app.py` 服务入口、一个带示例工具的智能体、`requirements.txt`、`Dockerfile`、`.env.example`、`.gitignore` 和 `.dockerignore`，以及持续交付工作流文件。合并 PR 后，推送到目标分支即触发 AgentKit Runtime 发布。

| 参数 | 必填 | 默认值 | 说明 |
| :- | :- | :- | :- |
| GitHub Repo | 是 | — | 支持 `owner/repository` 或完整 GitHub URL。 |
| 目标分支 | 否 | `main` | PR 的 base 分支。 |
| Agent 项目目录 | 是 | `agentkit-basic-agent` | 模板文件创建的目录。 |
| Runtime 名称 | 是 | — | 用于发布配置的 Runtime 名称，以字母开头，仅含字母、数字、下划线和连字符。 |
| Runtime ID | 是 | — | 持续更新的目标 AgentKit Runtime ID。 |
| 地域 | 是 | `cn-beijing` | 必须与目标 Runtime 所在地域一致。 |
| GitHub Token | 是 | — | 需要对目标仓库的写入权限；仅用于当前请求，不持久化。 |

### AgentKit Runtime 持续交付

为已有仓库添加持续发布到 AgentKit Runtime 的 GitHub Actions 工作流。推送代码到目标分支时自动构建并发布 Runtime 新版本。

| 参数 | 必填 | 默认值 | 说明 |
| :- | :- | :- | :- |
| GitHub Repo | 是 | — | 支持 `owner/repository` 或完整 GitHub URL。 |
| 目标分支 | 否 | `main` | 工作流监听的分支，也是 PR 的 base 分支。 |
| Agent 项目目录 | 否 | `.` | 包含 `app.py` 的项目目录；留空时使用仓库根目录。 |
| Runtime 名称 | 是 | — | 用于发布配置的 Runtime 名称。 |
| Runtime ID | 是 | — | 持续更新的目标 AgentKit Runtime ID。 |
| 地域 | 是 | `cn-beijing` | 必须与目标 Runtime 所在地域一致。 |
| GitHub Token | 是 | — | 需要对目标仓库的写入权限；仅用于当前请求，不持久化。 |

<Note>
  持续交付和模板导入工作流均需要在仓库中配置 `VOLCENGINE_ACCESS_KEY` 和 `VOLCENGINE_SECRET_KEY` GitHub Secrets；使用临时凭据时还需配置 `VOLCENGINE_SESSION_TOKEN`。这些 Secrets 在 GitHub 中管理，不经过 Studio。
</Note>

### PR 自动评审

在目标仓库中添加 GitHub Actions 工作流，在隔离的 AgentKit Sandbox 中评审同仓库的非草稿 PR，并将评审结果发布为 GitHub Review。

<Warning>
  PR 评审工作流仅评审与目标仓库相同的非草稿 PR，不评审 fork 仓库的 PR，不会读取 fork PR 的仓库 Secrets。
</Warning>

| 参数 | 必填 | 默认值 | 说明 |
| :- | :- | :- | :- |
| GitHub Repo | 是 | — | 支持 `owner/repository` 或完整 GitHub URL。 |
| 目标分支 | 否 | `main` | PR 的 base 分支。 |
| Sandbox Tool ID | 是 | — | 用于运行每次评审的 AgentKit CodeEnv Tool ID。 |
| 评审模型 | 是 | — | 注入 Sandbox 的代码评审模型名称。 |
| 模型 API 地址 | 是 | `https://ark.cn-beijing.volces.com/api/coding/v3` | 必须使用 OpenAI 兼容的 HTTPS 地址，不能包含凭据、查询参数或锚点。 |
| 地域 | 是 | `cn-beijing` | 必须与 Sandbox Tool 所在地域一致。 |
| GitHub Token | 是 | — | 需要对目标仓库的写入权限；仅用于当前请求，不持久化。 |

PR 评审工作流需要在仓库中配置以下 GitHub Secrets：

| Secret | 说明 |
| :- | :- |
| `VOLCENGINE_ACCESS_KEY` | 火山引擎 Access Key（必填）。 |
| `VOLCENGINE_SECRET_KEY` | 火山引擎 Secret Key（必填）。 |
| `CODEX_MODEL_API_KEY` | 评审模型的 API Key（必填）。 |
| `VOLCENGINE_SESSION_TOKEN` | 使用临时凭据时必填。 |

### 飞书机器人

<Note>
  飞书机器人自动化当前标记为 Beta。
</Note>

在 Studio 中直接创建一个由 AgentKit Runtime 驱动的飞书智能体。填写已发布飞书应用的凭据后，Studio 生成基础智能体、创建独立 Runtime，并启用飞书消息长连接。部署按生成智能体、构建镜像、创建 Runtime 和发布服务四个阶段展示进度。部署完成后可在页面中打开 Runtime 控制台。

| 参数 | 必填 | 默认值 | 说明 |
| :- | :- | :- | :- |
| 智能体名称 | 是 | `feishu_assistant` | 将作为新 Runtime 中的根智能体名称。 |
| 部署地域 | 是 | `cn-beijing` | Runtime 与构建产物创建的地域，可选 `cn-beijing` 或 `cn-shanghai`。 |
| 飞书 App ID | 是 | — | 来自飞书开放平台的应用凭证。 |
| 飞书 App Secret | 是 | — | 仅用于本次部署，不会写入生成源码或浏览器存储。 |

<Note>
  飞书机器人的 App Secret 仅用于本次部署，不写入生成源码、工作流或日志。部署期间可取消部署，取消将停止任务并清理已创建的 Runtime。
</Note>

### 网站集成

将已部署的 AgentKit Runtime 以悬浮聊天窗口嵌入外部网站，使网站访客无需登录即可与智能体对话。在 Studio 的「自动化」页面中打开「网站集成」卡片后，选择目标 Runtime、填写网站域名，Studio 会生成专属 Token 和嵌入代码片段。

<Note>
  网站集成当前标记为 Beta。
</Note>

#### 使用前提

* 已部署至少一个 AgentKit Runtime，且该 Runtime 中存在可对话的智能体。
* 目标 Runtime 的访问鉴权方式为 API Key。使用自定义 JWT 鉴权的 Runtime 暂不支持网站集成。
* 已配置 Studio 持久化存储（`VEADK_STUDIO_TOS_BUCKET` 与 `VEADK_STUDIO_TOS_REGION`）时，网站集成记录持久化保存在 TOS 中；未配置时使用进程内存存储，Studio 重启后集成记录会丢失。

#### 创建网站集成

1. 在「添加网站」区域中选择目标 AgentKit Runtime，并输入要嵌入聊天窗口的网站域名。
2. 点击「生成 Token」，Studio 会校验所选 Runtime 中可对话的智能体，并生成与域名绑定的集成记录和 Token。
3. 在「已添加网站」列表中查看创建的集成，每条记录包含域名、Runtime 名称、智能体名称和创建时间。

域名需为有效的 `http` 或 `https` 地址，支持带端口号（如 `localhost:5173` 或 `example.com:8080`），但不能包含路径、查询参数或登录信息。

| 参数 | 说明 |
| :- | :- |
| AgentKit Runtime | 从当前账号可见的 Runtime 列表中选择目标 Runtime。 |
| 网站域名 | 将嵌入聊天窗口的网站域名，如 `example.com` 或 `localhost:5173`。 |

#### 嵌入聊天窗口

在「引入方法」区域中复制生成的 `<script>` 标签，将其粘贴到目标网页的 `</body>` 标签之前。脚本会从 Studio 服务加载聊天组件，并在页面右下角渲染一个可展开的悬浮聊天窗口。

```html lines theme={null}
<script async src="https://your-studio-url/website-integration.js" data-token="wsi_xxx"></script>
```

<Warning>
  嵌入代码中的 `src` 地址需指向可公开访问的 Studio 服务地址。Studio 服务必须允许来自目标网站的跨域请求；网站集成的域名与 Token 绑定，Studio 会在运行时校验浏览器请求的 Origin 是否与配置的域名匹配，不匹配时拒绝请求。
</Warning>

#### 工作方式

访客打开嵌入聊天窗口的网页后，聊天组件会向 Studio 的嵌入接口发起会话创建请求，获取一个有效期为一小时的会话令牌。此后每条消息通过会话令牌经由 Studio 转发到绑定的 Runtime，并以流式方式返回回复。会话令牌过期后需重新创建会话。

Studio 使用配置的火山引擎或 BytePlus 凭证访问 Runtime，网站访客不接触任何凭证或 Runtime 直连地址。

#### 删除网站集成

在「已添加网站」列表中点击对应记录的「删除」按钮，确认后移除该集成。删除后，使用该 Token 的嵌入代码将无法再创建新会话，已打开的会话在令牌过期后失效。

## 资源库

侧边栏的「资源库」页面集中管理技能、知识库和产物，分为三个标签页：

| 标签 | 说明 |
| :- | :- |
| 技能库 | 管理技能空间和技能，包括上传、浏览、通过 Dev Sandbox 生成和优化技能。 |
| 知识库 | 创建和管理用户拥有的 AgentKit 知识库，上传文件或导入网页作为知识数据。 |
| 产物 | 浏览和管理对话中生成的文档、图片和视频等产物，其中图片和视频可持久化保存、编辑和删除。 |

### 技能库

技能库标签页提供技能空间管理和 Dev Sandbox 技能生成。在此页面可以创建和管理技能空间、上传和浏览技能、以及通过 Dev Sandbox 从自然语言描述生成新技能或优化已有技能。生成技能使用独立的 AgentKit DevEnv Tool，与内置智能体的 CodeEnv 模式互不影响。

#### 前提条件

技能中心的管理和生成操作由 Studio 服务端使用自身配置的火山引擎凭证完成，浏览器不接触凭证。本地启动时通过 `VOLCENGINE_ACCESS_KEY` 与 `VOLCENGINE_SECRET_KEY` 提供访问权限；部署到 VeFaaS 时使用绑定 IAM Role 的临时凭证。

Dev Sandbox 技能生成需要管理员配置处于 `Ready` 状态的 AgentKit DevEnv Tool。本地启动时通过 `SANDBOX_DEV` 环境变量指定 Tool ID；部署到 VeFaaS 时通过 `--sandbox-dev-tool-id` 自动创建或复用。未配置时，技能空间的管理和上传功能不受影响，但「创建技能」和「优化」入口会显示「管理员未配置 Dev Sandbox」并禁用。

<Note>
  Dev Sandbox 技能生成仅对 `developer` 和 `admin` 角色开放。技能空间的浏览对所有已登录用户开放，但非管理员仅能看到自己创建的技能空间。
</Note>

#### 技能发布存储

发布技能到技能空间时，Studio 会将技能包上传到 TOS 存储桶。存储桶按以下优先级选择：

| 优先级 | 来源 | 说明 |
| :- | :- | :- |
| 1 | `VEADK_SKILL_CREATOR_TOS_BUCKET` | 为技能发布显式指定的 TOS 存储桶。 |
| 2 | Studio 持久化存储桶 | 由 `VEADK_STUDIO_TOS_BUCKET` 与 `VEADK_STUDIO_TOS_REGION` 配置。使用时会校验存储桶地域与技能发布地域是否一致，不一致则发布失败。 |
| 3 | AgentKit 全局配置中的存储桶 | 通过 AgentKit CLI 全局配置设定的存储桶。 |
| 4 | 自动生成 | 由系统自动生成存储桶名称并创建。 |

存储桶内对象前缀通过 `VEADK_SKILL_CREATOR_TOS_PREFIX` 环境变量指定，默认为 `agentkit/skills`。

<Note>
  已配置 Studio 持久化存储时，技能发布会自动复用该存储桶，无需额外配置。如需为技能发布使用独立存储桶，设置 `VEADK_SKILL_CREATOR_TOS_BUCKET` 环境变量即可。
</Note>

#### 管理技能空间

技能空间按地域加载，支持按名称搜索。管理员可以查看全部地域中当前账号可见的全部技能空间；非管理员仅能看到自己创建的空间。

| 操作 | 说明 |
| :- | :- |
| 新建空间 | 填写名称（至多 128 字符）和可选描述（至多 1024 字符），选择地域后创建。空间创建者会记录在空间的标签中。 |
| 编辑空间 | 修改空间名称和描述。 |
| 删除空间 | 删除前需确认空间中的技能已删除；空间中仍有技能时会提示先删除。 |

<Note>
  新建技能空间时需选择地域：火山引擎可选 `cn-beijing` 与 `cn-shanghai`，默认 `cn-beijing`；BytePlus 为 `ap-southeast-1`。技能空间卡片会展示其所属地域，未显式记录地域的空间显示当前云服务商的默认地域。
</Note>

#### 管理技能

进入某个技能空间后，可以浏览其中全部技能并按名称搜索。每个技能支持以下操作：

| 操作 | 说明 |
| :- | :- |
| 查看文件 | 以文件树展示技能的完整文件列表，`SKILL.md` 内容直接在页面中预览。 |
| 下载 ZIP | 将技能完整文件包下载为 ZIP 压缩包。 |
| 优化 | 使用 Dev Sandbox 对现有技能进行优化，生成改进版本后可覆盖原技能。需要 Dev Sandbox 已配置。 |
| 删除 | 删除技能前需确认。删除会影响所有引用该技能的空间。 |
| 本地上传 | 选择 ZIP 文件上传到当前技能空间。ZIP 文件大小不能超过 20 MiB，上传前会校验文件格式、数量和路径安全。 |

<Note>
  上传 ZIP 时，Studio 会检查压缩包是否包含 `SKILL.md`、文件数量和路径安全，并自动忽略 `__MACOSX` 目录中的 macOS 元数据文件。完整的 frontmatter 与技能格式由 ADK 在加载时校验。上传前可使用校验功能预检 ZIP 内容。

  技能名称需在目标技能空间内唯一。如果目标技能空间中已存在同名技能，上传会被拒绝，可重命名后重新上传或使用优化功能覆盖。
</Note>

<Note>
  查看文件与下载 ZIP 时，Studio 按技能空间所在地域从存储下载技能文件包，解包时自动忽略 `__MACOSX` 目录、`.DS_Store` 等以 `._` 开头的 macOS 元数据文件。对使用旧版 SkillSpace 接口类型的技能，Studio 会回退到按技能名称解析详情，确保这类技能的文件列表与 `SKILL.md` 也能正常加载。下载或解析失败时返回可重试的结构化错误，可在排查地域、凭证与网络后重试。
</Note>

#### 通过 Dev Sandbox 生成技能

在技能空间页面中选择「创建技能」可进入 Dev Sandbox 技能生成工作台。该工作台通过 DevEnv Tool 创建独立的开发沙箱会话，根据自然语言描述生成符合 ADK 技能格式的 `SKILL.md` 及其相关文件。

##### 生成方案

| 配置项 | 说明 |
| :- | :- |
| 目标 | 必填。用自然语言描述希望技能完成的任务，至多 20000 字符。 |
| Skill 名称 | 可选。只能包含小写字母、数字和连字符，至多 64 字符；留空时自动生成。 |
| 生成方案 | 每组配置启动独立的 Dev Sandbox 会话。最多可添加 3 组，每组选择模型和风格后并行生成候选方案。 |

每组配置可选择的风格预设：

| 风格 | 说明 |
| :- | :- |
| 简洁实用 | 生成简短、直接可执行的指令。 |
| 严谨稳健 | 优先约束明确、边界条件完善、安全失败和边缘场景处理。 |
| 教程友好 | 清晰的步骤顺序和具体的小示例。 |
| 自动化优先 | 面向可重复的自动化，确定性步骤，尽量减少人工干预。 |
| 自定义 | 自行描述表达方式、严谨程度或输出偏好。 |

模型列表从 DevEnv Tool 的配置中读取，也可直接输入模型 ID。

##### 生成流程

<Steps>
  <Step title="填写目标与配置">
    在生成工作台中填写目标描述、可选的 Skill 名称，并为每组候选方案选择模型和风格。
  </Step>

  <Step title="生成候选方案">
    点击「生成」后，每组配置会启动独立的 Dev Sandbox 会话并行生成。生成过程中实时展示活动记录，包括状态、思考内容和工具调用。
  </Step>

  <Step title="校验与自动修复">
    生成完成后，Studio 会校验技能格式。若校验未通过且属于格式问题（如 `SKILL.md` 缺失、frontmatter 不符、目录名不匹配等），会自动修复至多 2 次；自动修复耗尽后仍可手动再次修复。
  </Step>

  <Step title="预览与调整">
    校验通过的候选方案会展示完整文件树。可以在输入框中继续描述调整需求，对当前候选方案进行迭代优化。
  </Step>

  <Step title="下载或发布">
    生成完成后可将技能下载为 ZIP，或直接发布到当前技能空间。发布时技能名称需在目标技能空间内唯一；如果已存在同名技能，发布会被拒绝，可重命名后发布或使用优化功能覆盖。优化已有技能时可选择覆盖原技能。
  </Step>
</Steps>

<Note>
  Dev Sandbox 会话的有效期为 1 小时。离开工作台时会停止正在运行的会话并释放资源。生成过程中刷新或关闭页面不影响已启动的会话，但建议保持页面打开以便跟踪进度。
</Note>

<Warning>
  Dev Sandbox 会话在 AgentKit 开发环境中运行。生成的技能内容来自模型的输出，发布前应检查文件内容，确认不包含敏感信息或不当内容。
</Warning>

##### 优化已有技能

在技能空间中浏览技能时，可对已有技能选择「优化」。优化流程与创建类似，但以现有技能作为来源：填写优化目标后启动 Dev Sandbox 会话，生成改进版本。优化完成后可选择覆盖原技能或作为新技能发布。

### 知识库

知识库标签页用于创建和管理用户拥有的 AgentKit 知识库，并上传文件或导入网页作为知识数据。知识库创建在 AgentKit 平台上，创建和写入操作需要 Studio 使用火山引擎或 BytePlus 凭证调用 AgentKit 知识库服务。

#### 创建知识库

点击「新建知识库」打开创建对话框，填写以下信息：

| 字段 | 必填 | 说明 |
| :- | :- | :- |
| 名称 | 是 | 1–48 个字符，以字母开头，仅支持字母、数字和下划线。 |
| 描述 | 否 | 至多 80 个字符。 |

<Note>
  知识库描述限制为 80 个字符，是因为 Studio 会在描述中追加签名标记以标识知识库归属，该标记与描述合计不超过 AgentKit 知识库的 200 字符描述上限。
</Note>

知识库按地域加载并支持按名称搜索。火山引擎部署时列出 `cn-beijing` 和 `cn-shanghai` 两个地域的知识库；BytePlus 部署时列出 `ap-southeast-1` 地域的知识库。新建知识库时，火山引擎部署的地域选项为 `cn-beijing`，BytePlus 部署为 `ap-southeast-1`。

#### 管理知识库

每个知识库卡片展示名称、描述、创建者和状态。有管理权限的用户可以编辑知识库描述、添加数据或删除知识库；无管理权限的用户仅可浏览。

| 操作 | 说明 |
| :- | :- |
| 编辑描述 | 修改知识库描述，至多 80 个字符。名称创建后不可修改。 |
| 添加数据 | 上传文件或导入网页作为知识库文档。 |
| 删除知识库 | 删除前需确认。删除后知识库及其全部数据不可恢复。 |

#### 添加知识数据

进入知识库后，有管理权限的用户可以添加知识数据。数据来源分为三类：

| 来源 | 支持格式 | 说明 |
| :- | :- | :- |
| 图片 | PNG、JPG、JPEG | 单个文件不超过 200 MB。 |
| 文档 | PDF、PPTX、DOCX、XLSX、TXT | 单个文件不超过 200 MB。 |
| 网页 | 公开网页 URL | Studio 服务端抓取网页并提取正文内容为 Markdown，预览确认后存入知识库。 |

<Warning>
  网页导入由 Studio 服务端执行，包含 SSRF 防护：校验目标地址和解析后的 IP 是否为内网或保留地址，限制重定向次数（至多 3 次）、HTML 大小（至多 5 MB）和提取后的 Markdown 大小（至多 2 MB），仅接受 `text/html` 和 `application/xhtml+xml` 内容类型。
</Warning>

<Note>
  导入网页时，Studio 先抓取页面并提取正文为 Markdown，在保存前展示渲染预览。确认后才会将预览的 Markdown 存入知识库；取消或预览失败不会创建任何数据。网页文档的名称自动取自页面标题，未获取到标题时使用域名作为名称。当主要提取方式无法获取正文时，Studio 尝试以备用方式提取页面可见文本；若页面依赖 JavaScript 动态渲染而无可见内容，会提示该页面可能无法导入。已导入的网页文档在知识库中预览时显示原始 Markdown 原文，而非分块后的检索结果。
</Note>

每条知识数据支持设置可选名称、类型和 Metadata（JSON 格式）。添加后可在知识库中预览已解析的内容，包括文本、表格、图片、PDF 等。数据解析需要时间，刚添加的数据可能暂时无法预览，可稍后刷新查看。

<Note>
  文件上传通过 Studio 的私有 TOS 存储中转后导入 AgentKit 知识库。已配置 Studio 持久化存储时自动复用对应存储桶。
</Note>

### 产物

产物标签页集中展示对话中生成的文档、图片和视频等产物。图片和视频产物会持久化保存到 Studio 持久化存储中，刷新页面或切换会话后仍然可用；文档类产物仅在对应的会话事件可用时展示。产物按会话来源分组，显示所属应用、会话和生成时间，支持按类型筛选和搜索。点击产物可预览图片或视频，文档类产物支持在线预览。

打开产物标签页时，Studio 会自动收集当前可见会话事件中的图片和视频产物并同步到持久化存储。已经保存过的产物不会重复写入；同步仅处理图片和视频类型的产物。

#### 管理产物

每条持久化产物支持以下操作：

| 操作 | 说明 |
| :- | :- |
| 预览 | 在页面中预览图片或视频内容。 |
| 下载 | 将产物文件下载到本地。 |
| 编辑信息 | 修改产物的名称、描述和标签。 |
| 删除 | 删除产物前需确认。删除后产物及其内容不可恢复。 |

编辑产物信息时，名称至多 180 个字符，描述至多 500 个字符，标签至多 10 个且单个标签不超过 32 个字符。

#### 依赖

产物持久化依赖 Studio 持久化存储。未配置持久化存储时，产物标签页无法同步和展示持久化产物，并提示「管理员未配置持久化存储」。持久化存储的配置方式见 [Studio 持久化存储](#studio-持久化存储)。

产物同步过程包含来源校验：仅接受来自受信任生成服务的 HTTPS 地址，并阻止解析到内网或保留地址的来源，防止从不可信地址写入内容。默认信任的来源域名后缀为 `volces.com`、`volccdn.com`、`byteplus.com` 和 `bytepluses.com`。单个产物的最大大小默认为 512 MB。

<Warning>
  产物内容保存在 Studio 配置的 TOS 存储桶中，按登录用户隔离。请勿在会话中生成或上传包含敏感信息的内容。
</Warning>

以下环境变量用于调整产物同步行为：

| 环境变量 | 默认值 | 说明 |
| :- | :- | :- |
| `VEADK_ARTIFACT_MAX_FILE_BYTES` | `536870912`（512 MB） | 单个产物允许保存的最大字节数。 |
| `VEADK_ARTIFACT_SOURCE_HOSTS` | `volces.com,volccdn.com,byteplus.com,bytepluses.com` | 逗号分隔的受信任来源域名后缀，留空时使用默认值。 |

## 定时任务

定时任务工作区在侧边栏以「定时任务」入口提供，按固定计划对一个已部署的 Runtime Agent 执行同一段文本提示词。每次触发都会为该 Runtime 创建一个独立的会话，任务始终跟随 Runtime 当前生效的版本。定时任务为 Beta 能力。

<Note>
  定时任务依赖 Studio 持久化存储保存任务定义、锁、执行历史与结果。未配置持久化存储时，定时任务工作区不可用并提示「管理员未配置持久化存储」。持久化存储的配置方式见 [Studio 持久化存储](#studio-持久化存储)。
</Note>

### 创建与编辑任务

在「定时任务」页面点击「创建任务」打开任务表单，编辑已有任务时使用同一表单。表单包含以下配置：

| 配置项 | 说明 |
| :- | :- |
| 任务名称 | 任务的显示名称，至多 80 个字符。 |
| Runtime Agent | 选择一个已部署的 Runtime Agent，任务始终使用其当前生效版本。无可用 Runtime 时无法创建任务。 |
| 执行文本 | 每次触发时发送给 Runtime Agent 的固定文本提示词，至多 20,000 个字符。 |
| 执行计划 | 计划类型与对应时间设置，见下表。 |
| 时区 | 计划时间所用的 IANA 时区，默认取浏览器时区。 |
| 创建后启用 | 开启时从下一个计划时间开始执行；关闭时仅创建任务，不自动触发。 |

执行计划支持以下类型：

| 类型 | 配置 | 说明 |
| :- | :- | :- |
| 一次性 | 执行时间 | 在指定时间触发一次。 |
| 每天 | 每天执行时间 | 每天在指定时间触发。 |
| 每周 | 星期、执行时间 | 在指定星期几的指定时间触发。 |
| Cron | Cron 表达式 | 使用五字段 Cron 表达式（依次为分钟、小时、日期、月份、星期）按计划触发。 |

### 管理任务

任务列表展示名称、所属 Runtime、执行计划、启用状态、下次执行时间和最近结果。每条任务支持以下操作：

| 操作 | 说明 |
| :- | :- |
| 立即执行 | 立即触发一次执行，无需等待计划时间。任务处于执行中或已暂停时不可用。 |
| 暂停 / 启用 | 暂停后任务不再按计划触发；重新启用后从下一个计划时间恢复执行。 |
| 编辑 | 修改任务名称、Runtime、执行文本、执行计划或时区。 |
| 删除 | 删除任务前需确认。存在执行中的运行时不可删除。 |

点击任务名称进入详情页，查看任务配置与执行历史。

### 执行历史

执行历史记录每次运行的状态、耗时、所用 Runtime 版本与会话标识，并保留最终回答和错误详情。运行状态包括已排队、准备中、执行中、自动重试中、成功、失败、已取消和已跳过。每次运行使用独立会话，结果与错误会永久保留。

处于排队或执行中状态的运行可以取消：排队中的运行可取消排队，执行中的运行可终止本次执行。失败的运行可重新执行。执行历史支持手动刷新。

<Note>
  手动触发的运行会以「已排队」状态写入下一个分钟的处理队列，通常在 60 秒内开始执行，避免当前分钟已被扫描时遗漏本次运行。
</Note>

### 执行机制

任务定义、运行锁、执行历史与结果保存在 Studio 私有 TOS 存储桶中。云端部署时，`veadk studio deploy` 会额外创建或更新两个无状态 VeFaaS 函数与对应的分钟触发器：扫描器每分钟将当前到期的任务复制到持久化执行队列并推进各任务计划，异步工作器从队列中取出任务、调用 Runtime 并写入最终结果。扫描器、工作器与 Studio 可独立重启而不丢失任务。

重复的计时器投递通过不可变运行 ID 与 TOS 条件写入去重；ETag 锁防止同一任务在多个实例间并发执行。工作器使用函数 IAM Role 读取 Runtime 当前的端点与版本，不存储用户令牌或 AK/SK 凭证。

本地使用 `veadk studio --vite` 启动时，Studio 后端会启动独立的本地扫描与执行循环，无需单独运行调度进程。

## `veadk studio` 参数

| 选项 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `--agents-dir` | `str` | `.` | 智能体应用的父目录；每个包含 `agent.py` 并暴露 `root_agent` 的子目录作为一个应用。 |
| `--frontend-dir` | `str \| None` | 包内置界面，回退到 `./frontend/dist` | 覆盖已构建的 Studio 界面目录。 |
| `--site-title` | `str \| None` | `VEADK_SITE_TITLE`，否则为 `AgentKit Studio` | 自定义系统名称，最多 16 个字符。 |
| `--site-logo` | `str \| None` | `VEADK_SITE_LOGO` | 自定义 Logo，支持本地图片路径或 HTTP(S) URL。 |
| `--host` | `str` | `127.0.0.1` | 监听地址。 |
| `--port` | `int` | `8000` | 监听端口。 |
| `--provider` | `volcengine` \| `byteplus` | `AGENTKIT_CLOUD_PROVIDER`/`CLOUD_PROVIDER`，然后 `volcengine` | 云服务商。未指定时依次读取 `AGENTKIT_CLOUD_PROVIDER` 与 `CLOUD_PROVIDER` 环境变量，均未设置时使用 `volcengine`；选择 `byteplus` 时使用 `BYTEPLUS_ACCESS_KEY`、`BYTEPLUS_SECRET_KEY` 和可选的 `BYTEPLUS_SESSION_TOKEN` 提供凭证。 |
| `--dev` | `bool` 标志 | `false` | 在选择器中加载本地智能体，而不是云端 AgentKit Runtime。 |
| `--vite` | `bool` 标志 | `false` | 只启动 API，并允许 `http://localhost:5173`（及回退端口 `http://localhost:5174`）的 Vite 开发服务器跨域访问。 |
| `--oauth2-user-pool` | `str \| None` | `None` | VeIdentity 用户池名称。与客户端名称或 UID 配合启用 SSO。 |
| `--oauth2-user-pool-client` | `str \| None` | `None` | VeIdentity 用户池客户端名称。 |
| `--oauth2-user-pool-uid` | `str \| None` | `OAUTH2_USER_POOL_ID` | 使用 UID 指定 VeIdentity 用户池。 |
| `--oauth2-user-pool-client-uid` | `str \| None` | `OAUTH2_USER_POOL_CLIENT_ID` | 使用 UID 指定 VeIdentity 用户池客户端。 |
| `--oauth2-redirect-uri` | `str \| None` | `OAUTH2_REDIRECT_URI`，否则为 `http://{host}:{port}/oauth2/callback` | OAuth2 回调地址。公网部署时必须使用外部可访问的地址。 |
| `--oauth2-provider` | `str \| None` | `OAUTH2_PROVIDER`；配置用户池时默认为 `veidentity` | SSO provider 标识。 |
| `--oauth2-provider-label` | `str \| None` | `OAUTH2_PROVIDER_LABEL` | 登录按钮文案。未设置时，使用 VeIdentity 登录的默认文案按云服务商区分：火山引擎为「火山引擎 Identity」，BytePlus 为「BytePlus Identity」。 |
| `--auth-mode` | `frontend \| gateway` | `frontend` | `frontend` 由 Studio 处理登录；`gateway` 信任上游网关转发的 JWT 身份。也可通过 `VEADK_FRONTEND_AUTH_MODE` 设置。 |
| `--admin` | `str \| None` | `None` | 逗号分隔的管理员名单（用户名或 OAuth 邮箱）。省略 `--admin` 与 `--developer` 时，所有登录用户都按 `admin` 处理。也可通过 `VEADK_STUDIO_ADMINS` 设置。 |
| `--developer` | `str \| None` | `None` | 逗号分隔的开发者名单（用户名或 OAuth 邮箱）。也可通过 `VEADK_STUDIO_DEVELOPERS` 设置。 |
| `--generated-agent-test-run-ttl` | `int` | `1800` | 生成智能体的临时测试进程保留秒数。 |
| `--open` / `--no-open` | `bool` | `--no-open` | 服务就绪后是否打开默认浏览器；`--vite` 模式下忽略。 |

## 部署到 VeFaaS

`veadk studio deploy` 将 Studio 部署为 VeFaaS 应用，并接入 VeIdentity 登录。部署命令会创建或复用 Serverless API Gateway；未指定 IAM Role 时，还会创建或复用 `VeADKFrontendServiceRole` 及 `VeADKFrontendPolicy`。未指定 `--user-pool-id` 与 `--allowed-client-id` 时，命令会在部署地域自动创建或复用同名的 VeIdentity 用户池与 Web 客户端。部署完成后，命令会把公网回调地址注册到用户池客户端并更新应用配置。

部署前，命令会检查 VeFaaS 服务角色 `ServerlessApplicationRole`：缺失时自动创建并绑定 `vefaas_full_access` 自定义策略及所需系统策略；角色已存在时，补齐缺失的自定义策略与系统策略，火山引擎与 BytePlus 均适用。该检查独立于 `--iam-role`，即使指定自定义角色也会执行。

<Warning>
  此操作会创建或修改 VeFaaS、API Gateway、IAM 和 VeIdentity 资源，可能产生费用并影响线上访问。默认 Role 具备用于创建和管理 AgentKit Runtime 及相关云资源的广泛权限。生产环境部署前应由管理员审查权限范围；需要收敛权限时，通过 `--iam-role` 使用预先配置的 Role。
</Warning>

准备符合权限要求的火山引擎凭证，然后执行：

```bash lines theme={null}
export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

veadk studio deploy \
  --vefaas-app-name "veadk-studio" \
  --region "cn-beijing" \
  --project "default" \
  --from-source
```

省略 `--user-pool-id` 与 `--allowed-client-id` 时，部署命令会在 `--region` 指定的地域自动创建或复用名为 `veadk-studio-{vefaas-app-name}` 的用户池和名为 `veadk-studio-{vefaas-app-name}-web` 的 Web 客户端，并在部署完成后回显它们的 ID。也可以同时传入这两个参数以使用已有的用户池和客户端；仅传入 `--user-pool-id` 时，命令会在该用户池中创建或复用 Web 客户端。单独传入 `--allowed-client-id` 而不指定 `--user-pool-id` 时会报错。

Preview 中的未发布 Studio 能力需要从 VeADK 源码目录执行部署，并使用 `--from-source` 将当前源码构建进 VeFaaS。省略该参数时，部署使用最新 PyPI 发布版本，不包含尚未发布的能力。

部署凭据按以下顺序解析：优先使用 `--volcengine-access-key` / `--volcengine-secret-key` 显式传入；未提供时读取当前进程的 `VOLCENGINE_ACCESS_KEY` / `VOLCENGINE_SECRET_KEY` 环境变量；两者均缺失时，读取 `~/.volc/credentials` 中的 `[default]` 配置。任一来源解析到完整的 Access Key 与 Secret Key 即可继续部署。STS 临时凭证的 Session Token 通过 `--volcengine-session-token` 显式传入，或依次读取 `VOLCENGINE_SESSION_TOKEN`、`VOLC_SESSIONTOKEN` 环境变量和 `~/.volc/credentials` 中 `[default]` 配置的 `session_token` 字段；未提供时留空，仅使用长期 AK/SK。

部署成功后，终端会输出公网 URL、VeFaaS 应用 ID，以及 Identity 地域、用户池 ID、用户池域名和客户端 ID。打开公网 URL 时，Studio 会先跳转到 VeIdentity 完成登录。

当部署过程中自动创建了 Identity 用户池、TOS 存储桶或沙箱 Tool 时（即未通过 `--user-pool-id` 与 `--allowed-client-id` 指定已有用户池、未通过 `VEADK_STUDIO_TOS_BUCKET` 指定已有存储桶、或未通过沙箱 Tool ID 参数指定已有 Tool），终端会额外输出已配置的云资源清单，包括每个沙箱 Tool 的类型与 ID、私有 TOS 存储地址、用户池 ID 和客户端 ID，并给出对应云服务商的 Identity 控制台链接。当 Studio 托管用户池（即未通过 `--user-pool-id` 指定已有用户池）时，部署默认将该用户池配置为仅 SSO 登录：关闭密码登录、无密码登录、注册、找回与未确认用户登录，邀请用户前需先在 Identity 控制台配置 SSO 身份提供者。传入 `--allow-dangerous-login` 可在 Studio 托管用户池上显式启用上述本地登录流程；该标志仅对 Studio 托管的用户池生效。通过 `--user-pool-id` 指定已有用户池时，部署保留该用户池的既有登录设置，不受此标志影响。

<Warning>
  `--allow-dangerous-login` 会启用用户池的本地账号登录流程，降低登录安全强度。仅在受控环境或测试用途下使用，生产环境应保留默认的仅 SSO 配置。
</Warning>

部署时还会创建或更新用于定时任务调度的两个无状态 VeFaaS 函数与对应的分钟触发器：扫描器每分钟将到期任务复制到持久化执行队列并推进计划，异步工作器从队列中取出任务调用 Runtime 并写入结果。部署完成后，终端会输出扫描器与工作器的函数 ID 和触发器 ID。

`--region` 指定 Studio 的部署地域，默认为 `cn-beijing`，也支持 `cn-shanghai`；VeFaaS Application、Function、API Gateway 和 AgentKit 资源均使用所选部署地域。同时传入 `--user-pool-id` 与 `--allowed-client-id` 时，命令会在所部署地域以及北京、上海两个地域之间查找已有的 VeIdentity 用户池与客户端：优先查询部署地域，未命中时跨地域查询另一个地域；跨地域命中时终端会输出 warning 并继续部署。省略这两个参数时，用户池与客户端在部署地域创建或复用，不进行跨地域查找。`--project` 指定 VeFaaS 函数所属项目，默认为 `default`。

部署者的长期 AK/SK 不会写入 VeFaaS 应用环境变量。已部署的 Studio 使用绑定 IAM Role 的临时凭证访问火山引擎服务。部署时自动生成或复用知识库签名密钥并写入 `VEADK_STUDIO_KNOWLEDGE_SIGNING_KEY` 环境变量，用于标识知识库归属。若已存在该环境变量则保留原值，否则根据部署密钥和部署标识生成确定性密钥，使同一部署在更新后仍能验证已创建的知识库。

未指定 `--sandbox-chat-codex-tool-id` 时，部署命令会在 `--region` 指定的地域创建内置智能体使用的 AgentKit CodeEnv Tool；同时还会额外创建一个 DevEnv Tool 用于开发沙箱。这些 Tool 创建的 Session 与 VeFaaS Function、API Gateway 保持同一地域。模型凭据只配置在各自 Tool 中，VeFaaS Function 只接收 Tool ID。若已有符合要求且地域一致的 Tool，可通过参数直接复用。

沙箱 Tool 使用的模型、接入地址和候选地域按云服务商区分：火山引擎使用 `doubao-seed-2-1-pro-260628` 模型与 `https://ark.cn-beijing.volces.com/api/v3`，候选地域为 `cn-beijing` 与 `cn-shanghai`；BytePlus 使用 `dola-seed-2-1-turbo-260628` 模型与 `https://ark.ap-southeast.bytepluses.com/api/v3`，候选地域为 `ap-southeast-1`。

<Note>
  部署和更新过程中创建沙箱 Tool 时，CLI 会自动对限流、网络错误和服务端临时故障进行重试，并在并发创建多个 Tool 时错开请求以避免触发限流。每次创建请求携带幂等令牌，确保重试不会产生重复 Tool。Tool 创建失败时，错误信息会包含 Tool ID 和云服务返回的错误码、状态码与请求 ID，便于排查。
</Note>

### IAM 权限预检

`veadk studio deploy` 在创建任何云资源前，自动执行只读 IAM 权限预检。预检读取当前调用者已绑定的 IAM 策略，逐一评估部署所需 IAM Action 是否满足。所需权限范围取决于部署配置：当未通过 `--user-pool-id` 与 `--allowed-client-id` 指定已有身份资源时，需要创建用户池相关权限；未指定 `--iam-role` 时需要角色管理权限；未通过 `VEADK_STUDIO_TOS_BUCKET` 指定已有存储桶时需要存储桶创建权限；未指定沙箱 Tool ID 时需要 Tool 创建权限；未指定 `--gateway-name` 时需要网关管理权限（包括开放 Studio API 所需 HTTP 方法的 `apig:UpdateRoute` 权限）；部署还需要创建和更新定时任务调度函数与分钟触发器的 VeFaaS 权限（`vefaas:ListFunctions`、`vefaas:GetFunction`、`vefaas:ListTriggers`、`vefaas:CreateTimer`、`vefaas:UpdateTimer`）；未启用 `--keep-failed-deploy` 时还需要清理失败资源的删除权限。

预检完成后，终端输出一张权限表格，列出每项 IAM Action 的作用及是否满足。若存在缺失权限，终端同时输出对应云服务商的 IAM 配置入口链接，便于前往补充权限。火山引擎入口为 `https://console.volcengine.com/iam/policymanage`，BytePlus 入口为 `https://console.byteplus.com/iam/policymanage`。

在正式部署中（未指定 `--precheck-only`），若存在缺失权限，命令会提示确认是否继续部署；默认为否，拒绝时部署终止，确认后继续创建云资源。使用 `--precheck-only` 时，缺失权限直接导致命令终止，不进入确认流程。

使用 `--precheck-only` 可仅执行权限预检而不创建任何云资源，用于在正式部署前确认凭证权限是否完备：

```bash lines theme={null}
veadk studio deploy \
  --vefaas-app-name "veadk-studio" \
  --region "cn-beijing" \
  --precheck-only
```

预检使用部署凭证以只读方式查询 IAM 策略，不修改任何资源。

### 应用内更新

Studio 从维护在北京地域的 TOS 发布源读取新版本，客户部署地域无需额外配置；部署完成后管理员可在导航栏中把前端与 Python 后端一起升级。默认发布源存储桶因云服务商而异：火山引擎部署使用 `veadk-studio`，BytePlus 部署使用 `veadk-studio-byteplus`。使用 `--studio-update-bucket` 与 `--studio-update-prefix`（或对应的 `VEADK_STUDIO_UPDATE_BUCKET`、`VEADK_STUDIO_UPDATE_PREFIX` 环境变量）可覆盖默认发布源，发布源地域始终为 `cn-beijing`。更新时根据部署环境中的 `CLOUD_PROVIDER`（或 `AGENTKIT_CLOUD_PROVIDER`）自动选择对应的云服务商入口，BytePlus 部署在更新过程中同步写入 `BYTEPLUS_REGION`。

Studio 每三分钟检查一次更新，列出可用版本及其变更说明。管理员确认升级后，Studio 会校验完整发布包，同时替换 Python 后端与前端资源并重新发布原 Application；Application 与 Function ID、访问 URL、SSO 客户端和服务端 Secret 保持不变。

在开始更新前，Studio 会先预检当前 VeFaaS Function 角色是否具备完成 OTA 更新所需的全部 IAM 权限（包括读取发布包、创建和更新调度函数、发布应用与函数、安装依赖及管理定时任务触发器等权限）。预检以只读方式查询已绑定的 IAM 策略，不修改任何资源。若存在缺失权限，更新在开始任何变更前即被中断，更新对话框列出缺失的权限项并提供对应云服务商的 IAM 控制台链接，管理员完成授权后可重新发起更新。更新进度面板会显示「预检 Studio 更新权限」阶段。

更新过程中，Studio 会检查当前 VeFaaS Function 缺失的云资源并自动补齐：若未配置持久化存储（`VEADK_STUDIO_TOS_BUCKET` 与 `VEADK_STUDIO_TOS_REGION`），则按部署地域创建或复用 TOS 存储桶；若缺少沙箱快照 Tool（`SANDBOX_CHAT_CODEX_SNAPSHOT`、`SANDBOX_CHAT_OPENCLAW_SNAPSHOT`、`SANDBOX_CHAT_HERMES_SNAPSHOT`），则按当前云服务商自动创建。补齐的资源以环境变量形式写入 Function 配置，使旧版本 Studio 在升级后也能使用新增的持久化存储和沙箱能力。更新进度面板会显示「检查并补齐 Studio 云资源」阶段。

应用内更新还会创建或更新定时任务调度函数与分钟触发器，更新进度面板会显示对应的阶段。

更新状态中的 VeFaaS Function 控制台链接按云服务商区分：火山引擎指向 `console.volcengine.com`，BytePlus 指向 `console.byteplus.com`。

<Note>
  应用内更新不会修改 Function 的 IAM 角色策略。如需更新 IAM 权限，请使用 `veadk studio update` 命令。
</Note>

更新过程中，部署进度面板实时展示 VeFaaS 部署日志。日志在服务端经过过滤，去除 curl 进度条、配置 JSON 导出、ANSI 转义序列和重复行，仅保留与部署相关的有效内容。当 Function 角色缺少 `vefaas:GetApplicationRevisionLog` 权限时，日志面板替换为权限提示，并显示对应云服务商的 IAM 控制台链接（火山引擎为 `console.volcengine.com/iam`，BytePlus 为 `console.byteplus.com/iam`），管理员可据此前往补充权限；更新不受影响，继续进行。更新完成后，Studio 会自动刷新页面以加载新版本；刷新前如有未关闭的更新对话框，也会在重新打开页面后自动恢复显示。

```bash lines theme={null}
veadk studio deploy \
  --vefaas-app-name "veadk-studio" \
  --studio-update-bucket "custom-studio-releases" \
  --studio-update-prefix "veadk/studio/main"
```

<Note>
  应用内更新仅对具备 `admin` 角色的登录用户开放，更新 Studio 自身的 VeFaaS Function，不影响已部署的 AgentKit Runtime。更新时补齐云资源使用部署者配置的火山引擎或 BytePlus 凭证。
</Note>

### 部署参数

| 选项 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `--user-pool-id` | `str \| None` | `None` | 已有的 VeIdentity 用户池 UID。省略时在部署地域自动创建或复用同名用户池。 |
| `--allowed-client-id` | `str \| None` | `None` | 已有的用户池客户端 UID。省略时在用户池中自动创建或复用同名 Web 客户端；传入时须同时指定 `--user-pool-id`。 |
| `--client-secret` | `str` | `""` | 无法通过客户端 UID 读取密钥时显式提供。直接传参可能进入 shell 历史，能够读取时应省略。 |
| `--allow-dangerous-login` | `bool` 标志 | `false` | 在 Studio 托管的 Identity 用户池上启用本地密码登录、无密码登录、注册、找回与未确认用户登录流程。仅当未通过 `--user-pool-id` 指定已有用户池时生效；指定已有用户池时部署保留其既有登录设置。 |
| `--vefaas-app-name` | `str` | 必填 | VeFaaS 应用名称，长度 4–64，只能包含字母、数字和连字符，不能包含下划线。 |
| `--provider` | `volcengine` \| `byteplus` | `AGENTKIT_CLOUD_PROVIDER`/`CLOUD_PROVIDER`，然后 `volcengine` | 部署使用的云服务商。未指定时依次读取 `AGENTKIT_CLOUD_PROVIDER` 与 `CLOUD_PROVIDER` 环境变量，均未设置时使用 `volcengine`；选择 `byteplus` 时使用 `BYTEPLUS_ACCESS_KEY`、`BYTEPLUS_SECRET_KEY` 和可选的 `BYTEPLUS_SESSION_TOKEN` 提供凭证，默认地域为 `ap-southeast-1`。 |
| `--region` | `cn-beijing` \| `cn-shanghai` \| `ap-southeast-1` | 由 `--provider` 推导 | Studio 部署地域，同时决定 VeFaaS、API Gateway 等资源所在区域。传入 `--user-pool-id` 与 `--allowed-client-id` 时跨北京、上海查找已有用户池。 |
| `--project` | `str` | `default` | VeFaaS 函数所属项目。 |
| `--iam-role` | `str \| None` | `None` | 绑定到函数的既有 IAM Role TRN；省略时创建或复用默认 Role。 |
| `--environment-cp-workspace` | `str \| None` | `None` | 环境镜像构建使用的已有 CodePipeline Workspace ID 或名称。省略时 Studio 创建或复用托管的 Workspace。该选项不从环境变量读取。 |
| `--environment-cr-repository` | `str \| None` | `None` | 环境镜像构建使用的已有 Container Registry 仓库，格式为 `registry/namespace/repository`。省略时 Studio 创建或复用托管的 CR 资源。该选项不从环境变量读取。 |
| `--vefaas-application-template-id` | `str \| None` | 内置模板 | 覆盖 VeFaaS Application Center 的内置模板 ID。也可通过 `VEFAAS_APPLICATION_TEMPLATE_ID` 设置。 |
| `--admin` | `str \| None` | `None` | 逗号分隔的管理员名单（用户名或 OAuth 邮箱）。省略 `--admin` 与 `--developer` 时，所有登录用户都按 `admin` 处理。也可通过 `VEADK_STUDIO_ADMINS` 设置。 |
| `--developer` | `str \| None` | `None` | 逗号分隔的开发者名单（用户名或 OAuth 邮箱）。也可通过 `VEADK_STUDIO_DEVELOPERS` 设置。 |
| `--site-title` | `str \| None` | `None` | 自定义 Studio 名称，最多 16 个字符。 |
| `--site-logo` | `str \| None` | `None` | 自定义 Studio Logo，支持本地图片路径或 HTTP(S) URL；部署时打包到 VeFaaS。 |
| `--gateway-name` | `str` | `""` | Serverless API Gateway 名称；省略时复用已有网关，没有可用网关时创建。 |
| `--gateway-service-name` | `str` | `""` | 指定网关服务名称；留空时自动配置。 |
| `--gateway-upstream-name` | `str` | `""` | 指定网关上游名称；留空时自动配置。 |
| `--volcengine-access-key` | `str \| None` | 自动解析 | 部署用 Access Key，依次读取命令参数、`VOLCENGINE_ACCESS_KEY` 环境变量与 `~/.volc/credentials` 的 `[default]` 配置。 |
| `--volcengine-secret-key` | `str \| None` | 自动解析 | 部署用 Secret Key，依次读取命令参数、`VOLCENGINE_SECRET_KEY` 环境变量与 `~/.volc/credentials` 的 `[default]` 配置。 |
| `--volcengine-session-token` | `str \| None` | 自动解析 | STS 临时凭证的 Session Token，依次读取命令参数、`VOLCENGINE_SESSION_TOKEN` / `VOLC_SESSIONTOKEN` 环境变量与 `~/.volc/credentials` 中 `[default]` 配置的 `session_token` 字段。 |
| `--byteplus-access-key` | `str \| None` | `BYTEPLUS_ACCESS_KEY` | BytePlus 部署凭证的 Access Key，仅在 `--provider byteplus` 时使用。 |
| `--byteplus-secret-key` | `str \| None` | `BYTEPLUS_SECRET_KEY` | BytePlus 部署凭证的 Secret Key，仅在 `--provider byteplus` 时使用。 |
| `--byteplus-session-token` | `str \| None` | `BYTEPLUS_SESSION_TOKEN` | BytePlus STS 临时凭证的 Session Token，仅在 `--provider byteplus` 时使用。 |
| `--veadk-version` | `str` | 最新发布版本 | 写入 VeFaaS 依赖的 `veadk-python` 版本；仅在需要固定或复现版本时设置。 |
| `--from-source` | `bool` 标志 | `false` | 从当前源码目录构建 wheel 后部署，包含未提交改动；用于验证未发布版本，不应与 `--veadk-version` 的发布版本工作流混用。 |
| `--keep-failed-deploy` | `bool` 标志 | `false` | 部署失败时保留已创建的 VeFaaS Application 与 Function 资源，便于在控制台查看发布日志。 |
| `--precheck-only` | `bool` 标志 | `false` | 仅执行只读 IAM 权限预检，不创建任何云资源。 |
| `--sandbox-chat-codex-tool-id` | `str \| None` | 自动创建 | 内置智能体使用的 AgentKit CodeEnv Tool ID；也可通过 `SANDBOX_CHAT_CODEX` 设置。 |
| `--sandbox-dev-tool-id` | `str \| None` | 自动创建 | 开发沙箱使用的 AgentKit DevEnv Tool ID；也可通过 `SANDBOX_DEV` 设置。 |
| `--studio-update-bucket` | `str \| None` | `veadk-studio`（火山引擎）/ `veadk-studio-byteplus`（BytePlus） | 存放 Studio 不可变发布包的 TOS Bucket；部署时写入函数环境变量 `VEADK_STUDIO_UPDATE_BUCKET`。也可通过 `VEADK_STUDIO_UPDATE_BUCKET` 设置。 |
| `--studio-update-prefix` | `str` | `veadk/studio/main` | Studio 主发布渠道的 TOS 对象前缀。也可通过 `VEADK_STUDIO_UPDATE_PREFIX` 设置。 |

## Studio BFF 动态工具

当连接的 AgentKit Runtime 通过 `enable_studio_tools=True` 启用了 Studio BFF 动态工具宿主时，Studio 智能体信息栏会在智能体静态工具下方显示「在此对话中添加 Studio 工具」。新会话默认禁用所有 Studio 工具，用户可按需勾选；选择状态在当前浏览器进程中跨轮次保留。浏览器在每次 Runtime 运行时发送选中的工具 ID 列表，空列表或省略时使用普通运行路径。工具代码和凭证保留在 Studio BFF 侧，不会下发到 Runtime 或浏览器。

<Note>
  该功能需要 Runtime 侧显式启用 `enable_studio_tools` 参数，详见[部署到 AgentKit](/productions/veadk/preview/zh/deploy/agentkit)。
</Note>

## 前端使用数据采集

Studio 前端的产品行为数据通过 TEA 上报，用于统计 Studio 实例访问量、登录使用情况，以及智能体部署、沙箱创建、智能体连接、对话发送、调试测试和源码下载的结果。运行 `veadk studio`（包括本地启动和 `veadk studio deploy` 部署的实例）时自动启用，无需任何配置；`veadk frontend` 不启用。上报失败时不影响 Studio 正常使用。页面加载后，Studio 会在用户登录前记录一次匿名的页面访问；用户身份确认后再关联用户信息，用于区分匿名访问与登录访问。

部署时 Studio 会自动通过 `/web/ui-config` 接口下发部署 ID、用户池 ID、应用 ID、函数 ID、部署地域、项目和云账号 ID 等上下文供前端关联事件，无需手动设置。云账号 ID 由 `veadk studio deploy` 和 `veadk studio update` 在部署或更新时自动解析并写入运行时环境，不涉及用户个人身份。解析失败时不中断部署或更新，解析错误经脱敏后作为 `account_id_resolution_error` 记录到埋点上下文。

<Note>
  埋点仅采集使用统计维度，包括部署 ID、云账号 ID、用户 ID、角色、地域、来源、创建方式、是否使用智能生成，以及智能体部署、沙箱创建、智能体连接、对话发送、调试测试和源码下载的成功或失败结果与失败阶段。匿名入口访问不包含用户 ID，仅在登录后关联。失败事件保留稳定的错误类别和错误码；智能体部署失败事件额外上报经过脱敏与长度限制的错误消息，构建阶段失败时优先取自构建日志文本。埋点不采集对话内容、提示词、生成代码、环境变量值或任何密钥。
</Note>

<Note>
  此变更仅影响 Studio 前端的产品行为埋点。VeADK 运行时的 APMPlus OpenTelemetry 链路观测和问题反馈中的 APMPlus 查询能力不受影响，继续保留。
</Note>

## 更新已部署的 Studio

`veadk studio update` 从本地 VeADK 源码重新构建 Studio，更新已有 VeFaaS Function 的代码并重新发布原 Application。运行前安装 Node.js 与 npm，并在 VeADK 源码目录执行：

```bash lines theme={null}
export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

veadk studio update --vefaas-app-name "veadk-studio"
```

省略 `--region` 和 `--project` 时，命令会在北京、上海及全部可见项目中查找同名 Application。若存在多个候选项，需要补充地域或项目缩小范围。更新保留 Application 与 Function ID、访问 URL、SSO、IAM、网关和已有环境变量；品牌和各 CodeEnv、DevEnv Tool ID 仅在显式传入相应参数时覆盖。更新时自动检查并补齐 `VEADK_STUDIO_KNOWLEDGE_SIGNING_KEY` 环境变量：若缺失则根据当前环境生成，确保更新后知识库管理功能可用。若函数使用默认 Studio IAM Role，更新时会同步刷新该角色的托管策略至最新版本；使用自定义 Role 时不做修改。更新还会向已绑定的 VeIdentity 用户池客户端注册当前 Studio 公网地址的 `/oauth2/callback` 回调并启用免确认，确保更新后 SSO 登录回调可用；注册失败时终端会输出 warning，并提示在用户池客户端的允许回调地址中手动添加该地址。查询已有部署与提交代码包更新时，命令会对限流、网络抖动等服务端临时故障自动重试；重试后仍失败时终端会提示云端发布可能仍在进行，可稍后重新执行同一更新命令。

更新还会创建或更新定时任务调度函数与对应的分钟触发器。

| 选项 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `--provider` | `volcengine` \| `byteplus` | `AGENTKIT_CLOUD_PROVIDER`/`CLOUD_PROVIDER`，然后 `volcengine` | 已部署 Studio 的云服务商。未指定时依次读取 `AGENTKIT_CLOUD_PROVIDER` 与 `CLOUD_PROVIDER` 环境变量，均未设置时使用 `volcengine`；选择 `byteplus` 时使用 `BYTEPLUS_ACCESS_KEY`、`BYTEPLUS_SECRET_KEY` 和可选的 `BYTEPLUS_SESSION_TOKEN` 提供凭证。 |
| `--vefaas-app-name` | `str` | 必填 | 要更新的 VeFaaS Application 名称。 |
| `--region` | `cn-beijing` \| `cn-shanghai` \| `ap-southeast-1` | 查询两个地域 | 将查找范围限制到一个地域。BytePlus 模式下默认查询 `ap-southeast-1`。 |
| `--project` | `str \| None` | 查询全部可见项目 | 将查找范围限制到一个项目。 |
| `--path` | `str` | `.` | 要构建的 VeADK 源码目录。 |
| `--site-title` | `str \| None` | 保留云上值 | 显式传入时替换 Studio 名称。 |
| `--site-logo` | `str \| None` | 保留云上值 | 显式传入时替换 Studio Logo。 |
| `--sandbox-chat-codex-tool-id` | `str \| None` | 保留云上值 | 显式传入时替换内置智能体使用的 Tool ID。 |
| `--sandbox-dev-tool-id` | `str \| None` | 保留云上值 | 显式传入时替换开发沙箱使用的 Tool ID。 |
| `--volcengine-access-key` | `str \| None` | `VOLCENGINE_ACCESS_KEY` | 更新操作使用的 Access Key。 |
| `--volcengine-secret-key` | `str \| None` | `VOLCENGINE_SECRET_KEY` | 更新操作使用的 Secret Key。 |
| `--volcengine-session-token` | `str \| None` | `VOLCENGINE_SESSION_TOKEN` | STS 临时凭证的 Session Token，火山引擎模式使用。 |
| `--byteplus-access-key` | `str \| None` | `BYTEPLUS_ACCESS_KEY` | BytePlus 更新凭证的 Access Key，仅在 `--provider byteplus` 时使用。 |
| `--byteplus-secret-key` | `str \| None` | `BYTEPLUS_SECRET_KEY` | BytePlus 更新凭证的 Secret Key，仅在 `--provider byteplus` 时使用。 |
| `--byteplus-session-token` | `str \| None` | `BYTEPLUS_SESSION_TOKEN` | BytePlus STS 临时凭证的 Session Token，仅在 `--provider byteplus` 时使用。 |

## Studio 角色与 Runtime 权限

`--admin` 和 `--developer` 各自接收逗号分隔的本地用户名或 OAuth 邮箱名单。空格会被忽略，身份匹配不区分大小写；同一身份同时出现在两个名单时，`admin` 优先。本地启动示例：

```bash lines theme={null}
veadk studio \
  --admin "admin,admin@example.com" \
  --developer "alice,alice@example.com,bob"
```

也可以分别通过 `VEADK_STUDIO_ADMINS` 和 `VEADK_STUDIO_DEVELOPERS` 环境变量设置这两个名单。部署 Studio 时使用相同参数：

```bash lines theme={null}
veadk studio deploy \
  --vefaas-app-name "veadk-studio" \
  --admin "admin@example.com" \
  --developer "alice@example.com,bob@example.com"
```

两项都不传时，所有登录用户都按 `admin` 处理，拥有全部 Studio 能力并可见全部 Runtime。只要传入任一名单就会启用角色权限；未命中名单的身份为普通用户。

| 功能 | admin | developer | 普通用户 |
| :- | :- | :- | :- |
| 添加、调试和部署智能体 | 允许 | 允许 | 不允许；「智能体」页面中的创建入口不可用 |
| 查看和连接 Runtime | 全部 Runtime | 仅自己创建的 Runtime | 仅自己创建的 Runtime |
| 管理或删除 Runtime | 全部 Studio 管理的 Runtime | 仅自己创建的 Runtime | 不允许 |

Studio 根据登录账号限制 Runtime 的可见范围；没有创建者记录的历史 Runtime 仅 `admin` 可见。

<Warning>
  本地用户名保存在浏览器中，可被用户修改或冒充，仅适用于本地开发与功能验证。生产环境必须使用 OAuth 或 gateway 认证，以经过验证的登录信息确定身份与权限。
</Warning>

### 本地会话归属

当 Studio 启用 OAuth 或 gateway 认证后，对本地 ADK 会话的读取、创建、更新与删除操作，以及智能体运行请求，均绑定到登录身份。用户只能访问属于自己身份标识的会话；身份匹配不区分大小写，可匹配登录令牌中的用户名、邮箱等标识。

未携带可信登录身份时，访问本地会话会返回 401。非管理员用户访问其他用户的会话会返回 403。

<Note>
  即使未配置 `--admin` 与 `--developer`（此时所有登录用户拥有全部 Studio 能力），跨用户会话访问仍要求显式出现在管理员名单中。该限制独立于角色权限，不会因「全部用户为管理员」的遗留模式而放开。
</Note>

列在 `--admin` 管理员名单中的身份可以访问其他用户的本地会话，用于排查与支持；此类访问会记录审计日志，包含操作者、目标用户、请求方法与路径。

## 查看系统信息

登录后，侧边栏底部的账号菜单提供「系统信息」入口，选择后在当前页面上方打开系统信息页面，展示 Studio 的版本、存储、沙箱信息和用户池。页面左上角的返回按钮可回到打开系统信息前所在的页面，当前页面保持不变。页面中的 TOS 存储桶、沙箱 Tool 和用户池均提供跳转到对应云服务商控制台的链接，点击后在新标签页打开。该页面仅对 `admin` 角色开放，所有资源标识均为只读；管理员可对需要修复的 Codex Sandbox Tool 执行模型环境变量回填（见[沙箱信息](#沙箱信息)）。

### 通用

显示 Studio 的「当前版本」。本地启动或从源码构建部署时，版本号取自已安装的 VeADK 版本。当 Studio 切换到云端 Frontend 发布版本时，显示对应的发布版本号；未取到版本信息时显示「—」。

### 存储

显示 Studio 持久化存储使用的 TOS 地址。配置了 `VEADK_STUDIO_TOS_BUCKET` 与 `VEADK_STUDIO_TOS_REGION` 时显示对应的存储桶访问地址，例如 `veadk-studio-<账号 ID>.tos-cn-beijing.volces.com`，点击地址可在云控制台中打开对应存储桶；未配置时显示「未配置」。

### 沙箱信息

列出 Studio 已配置的沙箱 Tool 及其 ID，包括 Codex Sandbox（`SANDBOX_CHAT_CODEX`）、DeepSeek Harness Sandbox（`SANDBOX_CHAT_CODEX`）、OpenClaw Sandbox（`SANDBOX_CHAT_OPENCLAW`）、Hermes Sandbox（`SANDBOX_CHAT_HERMES`）和 Dev Sandbox（`SANDBOX_DEV`），各项按固定顺序排列。其中 DeepSeek Harness Sandbox 与 Codex Sandbox 共用同一个 AgentKit CodeEnv Tool（`SANDBOX_CHAT_CODEX`），因此两者显示相同的 Tool ID。已配置的 Tool ID 提供跳转到云控制台对应 Tool 详情页的链接；未配置的 Tool 显示「未配置」。

#### Codex Sandbox 模型环境变量修复

对于 Codex Sandbox（`SANDBOX_CHAT_CODEX`）与 Codex Sandbox 快照版（`SANDBOX_CHAT_CODEX_SNAPSHOT`），系统信息页面还会检测其 Tool 环境变量中是否已配置 `MODEL_AGENT_API_KEY` 与 `MODEL_AGENT_BASE_URL`。当检测到缺失其中任一变量、且 Tool 中同时存在 `CODEX_API_KEY` 与 `CODEX_BASE_URL` 时，该 Tool 的 ID 旁会显示更新按钮。

管理员点击更新按钮后，Studio 服务端使用自身配置的火山引擎或 BytePlus 凭证从 Tool 当前环境变量中读取 `CODEX_API_KEY` 与 `CODEX_BASE_URL`，回填缺失的 `MODEL_AGENT_API_KEY` 与 `MODEL_AGENT_BASE_URL`，完成后在 Tool ID 旁显示更新结果。整个过程中密钥不会下发到浏览器。

<Note>
  若 Tool 缺少 `CODEX_API_KEY` 或 `CODEX_BASE_URL`，更新按钮不会出现，Tool ID 旁会显示缺少哪些变量的错误提示。此时需先在云控制台为该 Tool 补充对应的环境变量，再刷新系统信息页面重新检测。
</Note>

<Warning>
  该操作仅回填缺失的 `MODEL_AGENT_API_KEY` 与 `MODEL_AGENT_BASE_URL`，不会覆盖已存在的值，也不会修改 Tool 的其他环境变量。执行前请确认 Tool 中的 `CODEX_API_KEY` 与 `CODEX_BASE_URL` 指向预期的模型凭证。
</Warning>

### 用户池

列出当前 Studio 所在的 VeIdentity 用户池，显示名称、ID、域名和地域，每个用户池的名称提供跳转到云控制台对应用户池页面的链接。本地启动且未配置火山引擎凭证时不显示用户池。