> ## 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 1.0.5 使用与 VeADK Frontend 相同的服务和完整界面。它启用对话、搜索、历史会话、技能中心，以及智能体创建、测试、部署和管理功能，启动后默认进入对话页面。

Studio 1.0.5 当前支持通过自定义配置创建项目；智能模式、模板和工作流入口显示为「敬请期待」，暂不可用。你可以预览和编辑生成的文件，安全地启动临时测试进程，将项目下载为 ZIP，或者部署到 AgentKit。该版本还支持选择云端 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 部署。生产环境应通过环境变量或密钥管理服务提供凭证，不要把凭证写入项目文件。

## 创建智能体

1. 在「添加智能体」中选择自定义；智能模式、模板和工作流入口暂不可用。
2. 配置模型、系统提示词、工具、记忆和知识库，并从 Skill Hub、本地上传或 AgentKit SkillSpace 添加技能。多智能体项目还可以配置顺序、并行、循环或 A2A 节点。
3. 检查生成的项目文件，并在受限的临时进程中测试运行；需要离线使用时下载 ZIP。
4. 选择部署到 AgentKit，观察构建镜像、部署和发布进度。

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

## 管理智能体

「管理智能体」列出当前登录用户通过该工作台部署的 AgentKit Runtime。列表按部署时记录的用户标识过滤，可以查看：

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

数据面 API Key 不会保存在浏览器中，因此管理页只显示控制面可读取的主智能体信息，不会通过数据面凭证加载完整子智能体树。

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

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

## `veadk studio` 参数

| 选项 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `--agents-dir` | `str` | `.` | 智能体应用的父目录；每个包含 `agent.py` 并暴露 `root_agent` 的子目录作为一个应用。 |
| `--frontend-dir` | `str \| None` | 包内置界面，回退到 `./frontend/dist` | 覆盖已构建的 Studio 界面目录。 |
| `--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` 设置。 |
| `--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`。部署完成后，命令会把公网回调地址注册到用户池客户端并更新应用配置。

使用默认 Role 时，部署命令会为其补充访问模型、日志、追踪、知识库、记忆与身份资源所需的系统策略。通过 `--iam-role` 显式指定的 Role 不会被修改，需提前配置完整权限。

<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" \
  --veadk-version "1.0.5"
```

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

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

### 部署参数

| 选项 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `--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` | `str` | `cn-beijing` | VeFaaS、API Gateway 和相关资源所在区域。 |
| `--iam-role` | `str \| None` | `None` | 绑定到函数的既有 IAM Role TRN；省略时创建或复用默认 Role。 |
| `--gateway-name` | `str` | `""` | Serverless API Gateway 名称；省略时复用已有网关，没有可用网关时创建。 |
| `--gateway-service-name` | `str` | `""` | 指定网关服务名称；留空时自动配置。 |
| `--gateway-upstream-name` | `str` | `""` | 指定网关上游名称；留空时自动配置。 |
| `--volcengine-access-key` | `str \| None` | `VOLCENGINE_ACCESS_KEY` | 部署用 Access Key。推荐通过环境变量提供。 |
| `--volcengine-secret-key` | `str \| None` | `VOLCENGINE_SECRET_KEY` | 部署用 Secret Key。推荐通过环境变量提供。 |
| `--veadk-version` | `str` | 最新发布版本 | 写入 VeFaaS 依赖的 `veadk-python` 版本。重现本页行为时显式设为 `1.0.5`。 |
| `--from-source` | `bool` 标志 | `false` | 从当前源码目录构建 wheel 后部署，包含未提交改动；用于验证未发布版本，不应与 `--veadk-version` 的发布版本工作流混用。 |