> ## 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 智能体工作台

VeADK Studio 使用与 VeADK Frontend 相同的服务和完整界面，提供对话、搜索、历史会话、技能中心，以及智能体创建、测试、部署和管理功能，启动后默认进入对话页面。

当前可通过自定义配置创建项目；智能模式、模板和工作流入口显示为「敬请期待」，暂不可用。你可以预览和编辑生成的文件，启动临时测试进程，将项目下载为 ZIP，或者部署到 AgentKit。Studio 还支持选择云端 Runtime、多来源技能、多模态会话，以及集中查看和重试部署任务。

## 在本地启动

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

```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 部署。生产环境应通过环境变量或密钥管理服务提供凭证，不要把凭证写入项目文件。

## 自定义品牌

使用 `--site-title` 设置最多 6 个字符的系统名称，使用 `--site-logo` 指定本地图片或 HTTP(S) 图片 URL。Logo 会用于侧边栏、登录页和浏览器 favicon，系统名称也会作为浏览器页面标题；省略 `--site-title` 时使用默认名称 `VeADK 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. 在「添加智能体」中选择自定义；智能模式、模板和工作流入口暂不可用。
2. 配置模型、系统提示词、工具、记忆和知识库，并从 Skill Hub、本地上传或 AgentKit SkillSpace 添加技能。多智能体项目还可以配置顺序、并行、循环或 A2A 节点。
3. 检查生成的项目文件，并在受限的临时进程中测试运行；需要离线使用时下载 ZIP。
4. 选择部署到 AgentKit，观察构建镜像、部署和发布进度。

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

### 添加远程智能体

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

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

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

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

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

  <Step title="选择智能体中心">
    默认加载北京地域 `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` | 智能体中心所在地域；修改后会按新地域重新加载下拉列表。 |
| AgentKit 智能体中心 OpenAPI 地址 | `REGISTRY_ENDPOINT` | `URL` | 否 | `https://open.volcengineapi.com/` | 生成项目调用智能体中心时使用的 OpenAPI 地址；仅在需要使用其他公开入口时修改。 |

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

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

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

测试运行进程默认保留 1800 秒，可通过 `--generated-agent-test-run-ttl` 调整。测试代码可能调用外部服务或访问运行环境中的数据，只应测试可信项目，并为 Studio 使用权限受限的凭证。

### 配置知识库

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

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

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

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

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

| 现象 | 检查方法 |
| :- | :- |
| 知识库列表为空 | 确认北京地域 `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 的地域。 |

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

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

## 使用智能搜索

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

* **会话**：在当前智能体的历史消息中执行全文检索。
* **网络**：调用当前智能体挂载的 `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」中所述的服务端运行时代理一致。

## 管理智能体

「管理智能体」列出当前登录用户通过该工作台部署的 AgentKit Runtime。列表默认展示北京区域的 Runtime，也可以切换到上海。列表按部署时记录的用户标识过滤，可以查看：

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

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

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

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

## 选择云端 Runtime

在云端模式下，对话页面侧边的智能体选择器会列出当前登录用户通过该工作台部署的 AgentKit Runtime，并按区域分页浏览。每条 Runtime 提供两个独立操作：

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

信息面板包含两个标签：

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

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

连接 Runtime 时若无法建立连接，Studio 会区分失败原因并给出对应提示，便于直接定位问题：

* **权限不足**：当前账号无权访问该 Runtime，可刷新列表或重新登录后重试。
* **Agent Server 不可连接**：Runtime 的 Agent Server 未提供连接接口，通常是 Runtime 尚未就绪或版本不兼容，需确认 Runtime 状态与版本。
* **鉴权失败**：Runtime 服务拒绝了连接请求，需检查 Runtime 的鉴权配置。

这样无需查看日志即可判断应刷新、重新登录，还是检查 Runtime 就绪状态与鉴权配置。

## 使用临时会话和 Skill 创建

新会话支持三种模式：

* **智能体对话**：与当前选中的智能体进行普通多轮对话。
* **临时会话**：在独立的 AgentKit CodeEnv Session 中进行多轮对话；退出后删除云端 Session，内容不写入普通历史会话。
* **Skill 创建**：并行生成两个 Skill 候选方案，完成后可对比、预览、下载 ZIP 或添加到 AgentKit。

Skill 创建仅对 `developer` 和 `admin` 开放。每个候选使用独立 Session，生成结果在打包前会检查 `SKILL.md`、文件数量、大小和路径安全。候选 Session 的有效期为 30 分钟；重新创建或离开任务时会立即清理。创建或凭据准备失败时，Studio 会展示不包含凭据的错误信息，便于定位 Tool 状态、区域或模型凭据问题。

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

### 本地配置

本地使用临时会话和 Skill 创建前，分别准备两个处于 `Ready` 状态的 AgentKit CodeEnv Tool，并配置其 ID：

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

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

| 环境变量 | 默认值 | 说明 |
| :- | :- | :- |
| `SANDBOX_CHAT_CODEX` | — | 临时会话使用的 AgentKit CodeEnv Tool ID；本地使用该模式时必填。 |
| `SANDBOX_SKILL_CREATOR` | — | Skill 创建使用的 AgentKit CodeEnv Tool ID；本地使用该模式时必填。 |
| `VEADK_SKILL_CREATOR_TOS_BUCKET` | AgentKit 账户默认 Bucket | 发布 Skill 产物使用的 TOS Bucket。 |
| `VEADK_SKILL_CREATOR_TOS_PREFIX` | `agentkit/skills` | 发布产物的 TOS 对象 Key 前缀。 |
| `VEADK_SKILL_CREATOR_PROJECT_NAME` | — | 创建 Skill 时使用的项目名称。 |

## 管理会话能力

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

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

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

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

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

## `veadk studio` 参数

| 选项 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `--agents-dir` | `str` | `.` | 智能体应用的父目录；每个包含 `agent.py` 并暴露 `root_agent` 的子目录作为一个应用。 |
| `--frontend-dir` | `str \| None` | 包内置界面，回退到 `./frontend/dist` | 覆盖已构建的 Studio 界面目录。 |
| `--site-title` | `str \| None` | `VEADK_SITE_TITLE`，否则为 `VeADK Studio` | 自定义系统名称，最多 6 个字符。 |
| `--site-logo` | `str \| None` | `VEADK_SITE_LOGO` | 自定义 Logo，支持本地图片路径或 HTTP(S) URL。 |
| `--host` | `str` | `127.0.0.1` | 监听地址。 |
| `--port` | `int` | `8000` | 监听端口。 |
| `--dev` | `bool` 标志 | `false` | 在选择器中加载本地智能体，而不是云端 AgentKit Runtime。 |
| `--vite` | `bool` 标志 | `false` | 只启动 API，并允许 `http://localhost:5173` 的 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` | 登录按钮文案。 |
| `--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`。部署完成后，命令会把公网回调地址注册到用户池客户端并更新应用配置。

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

准备用户池 UID、用户池客户端 UID 和符合权限要求的火山引擎凭证，然后执行：

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

veadk studio deploy \
  --user-pool-id "your-user-pool-id" \
  --allowed-client-id "your-user-pool-client-id" \
  --vefaas-app-name "veadk-studio" \
  --region "cn-beijing" \
  --project "default" \
  --from-source
```

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 即可继续部署。

部署成功后，终端会输出公网 URL 和 VeFaaS 应用 ID。打开公网 URL 时，Studio 会先跳转到 VeIdentity 完成登录。

`--region` 指定 Studio 的部署地域，默认为 `cn-beijing`，也支持 `cn-shanghai`；VeFaaS、API Gateway 等资源均创建在该地域。部署时还会自动在所部署地域以及北京、上海两个地域之间查找 VeIdentity 用户池与客户端：优先查询部署地域，未命中时跨地域查询另一个地域；跨地域命中时终端会输出 warning 并继续部署。`--project` 指定 VeFaaS 函数所属项目，默认为 `default`。

部署者的长期 AK/SK 不会写入 VeFaaS 应用环境变量。已部署的 Studio 使用绑定 IAM Role 的临时凭证访问火山引擎服务。

未指定 `--sandbox-chat-codex-tool-id` 与 `--sandbox-skill-creator-tool-id` 时，部署命令会在 `--region` 指定的地域创建两个独立的 AgentKit CodeEnv Tool，分别用于临时会话和 Skill 创建；这些 Tool 创建的 Session 与 VeFaaS Function、API Gateway 保持同一地域。模型凭据只配置在各自 Tool 中，VeFaaS Function 只接收 Tool ID。若已有符合要求且地域一致的 Tool，可通过参数直接复用。

### 应用内更新

`veadk studio deploy` 默认使用部署地域的 `veadk-studio` TOS Bucket 作为不可变发布渠道，部署完成后管理员可在导航栏中把前端与 Python 后端一起升级，无需额外参数。使用 `--studio-update-bucket`、`--studio-update-region` 与 `--studio-update-prefix`（或对应的 `VEADK_STUDIO_UPDATE_BUCKET`、`VEADK_STUDIO_UPDATE_REGION`、`VEADK_STUDIO_UPDATE_PREFIX` 环境变量）可覆盖默认发布渠道。

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

```bash lines theme={null}
veadk studio deploy \
  --user-pool-id "your-user-pool-id" \
  --allowed-client-id "your-user-pool-client-id" \
  --vefaas-app-name "veadk-studio" \
  --studio-update-bucket "custom-studio-releases" \
  --studio-update-region "cn-shanghai" \
  --studio-update-prefix "veadk/studio/main"
```

<Note>
  应用内更新仅对具备 `admin` 角色的登录用户开放，更新 Studio 自身的 VeFaaS Function，不影响已部署的 AgentKit Runtime。
</Note>

### 部署参数

| 选项 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `--user-pool-id` | `str` | 必填 | 用于 Studio 登录的 VeIdentity 用户池 UID。 |
| `--allowed-client-id` | `str` | 必填 | 用于登录的用户池客户端 UID。 |
| `--client-secret` | `str` | `""` | 无法通过客户端 UID 读取密钥时显式提供。直接传参可能进入 shell 历史，能够读取时应省略。 |
| `--vefaas-app-name` | `str` | 必填 | VeFaaS 应用名称，长度 4–64，只能包含字母、数字和连字符，不能包含下划线。 |
| `--region` | `cn-beijing \| cn-shanghai` | `cn-beijing` | Studio 部署地域，同时决定 VeFaaS、API Gateway 等资源所在区域。部署时会跨北京、上海查找 VeIdentity 用户池。 |
| `--project` | `str` | `default` | VeFaaS 函数所属项目。 |
| `--iam-role` | `str \| None` | `None` | 绑定到函数的既有 IAM Role TRN；省略时创建或复用默认 Role。 |
| `--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 名称，最多 6 个字符。 |
| `--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]` 配置。 |
| `--veadk-version` | `str` | 最新发布版本 | 写入 VeFaaS 依赖的 `veadk-python` 版本；仅在需要固定或复现版本时设置。 |
| `--from-source` | `bool` 标志 | `false` | 从当前源码目录构建 wheel 后部署，包含未提交改动；用于验证未发布版本，不应与 `--veadk-version` 的发布版本工作流混用。 |
| `--sandbox-chat-codex-tool-id` | `str \| None` | 自动创建 | 临时会话使用的 AgentKit CodeEnv Tool ID；也可通过 `SANDBOX_CHAT_CODEX` 设置。 |
| `--sandbox-skill-creator-tool-id`、`--skill-creator-tool-id` | `str \| None` | 自动创建 | Skill 创建使用的 AgentKit CodeEnv Tool ID；也可通过 `SANDBOX_SKILL_CREATOR` 设置。 |
| `--studio-update-bucket` | `str` | `veadk-studio` | 存放 Studio 不可变发布包的 TOS Bucket；部署时写入函数环境变量 `VEADK_STUDIO_UPDATE_BUCKET`。也可通过 `VEADK_STUDIO_UPDATE_BUCKET` 设置。 |
| `--studio-update-region` | `str \| None` | 部署地域 | Studio 发布 Bundle 的 TOS 地域；省略时与 `--region` 一致。也可通过 `VEADK_STUDIO_UPDATE_REGION` 设置。 |
| `--studio-update-prefix` | `str` | `veadk/studio/main` | Studio 主发布渠道的 TOS 对象前缀。也可通过 `VEADK_STUDIO_UPDATE_PREFIX` 设置。 |

## 更新已部署的 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 Tool ID 仅在显式传入相应参数时覆盖。

| 选项 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `--vefaas-app-name` | `str` | 必填 | 要更新的 VeFaaS Application 名称。 |
| `--region` | `cn-beijing \| cn-shanghai` | 查询两个地域 | 将查找范围限制到一个地域。 |
| `--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-skill-creator-tool-id`、`--skill-creator-tool-id` | `str \| None` | 保留云上值 | 显式传入时替换 Skill 创建使用的 Tool ID。 |
| `--volcengine-access-key` | `str \| None` | `VOLCENGINE_ACCESS_KEY` | 更新操作使用的 Access Key。 |
| `--volcengine-secret-key` | `str \| None` | `VOLCENGINE_SECRET_KEY` | 更新操作使用的 Secret Key。 |

## 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 \
  --user-pool-id "your-user-pool-id" \
  --allowed-client-id "your-user-pool-client-id" \
  --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 的「当前版本」。

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