> ## 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、多来源技能、多模态会话、自动化集成，以及集中查看和重试部署任务。 ## 在本地启动 从智能体目录的上一级目录运行： ```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` 时，本地 CLI 始终使用火山引擎。 ## 自定义品牌 使用 `--site-title` 设置最多 6 个字符的系统名称，使用 `--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. 在「添加智能体」中选择自定义；智能模式、模板、工作流以及从存量项目迁移的入口暂不可用。 2. 配置模型、系统提示词、工具、记忆和知识库，并从 Skill Hub、本地上传或 AgentKit SkillSpace 添加技能。多智能体项目还可以配置顺序、并行、循环或 A2A 节点，并在画布中查看和编排智能体拓扑。 3. 检查生成的项目文件，并在受限的临时进程中测试运行；需要离线使用时下载 ZIP。 4. 选择部署到 AgentKit，在工作台中观察构建镜像、部署和发布进度。部署完成后，智能体以已发布状态出现在工作台，后续可在同一 Runtime 上更新。 自定义创建中的资源选择器（如智能体中心、知识库集合）支持按关键词本地筛选：在下拉框中输入文字即可过滤当前已加载的选项。筛选只作用于已经加载的列表，不会改变地域、项目范围或刷新逻辑。 部署进入构建镜像阶段时，Studio 会在部署进度卡片中实时展示构建日志。日志在服务端完成凭据脱敏与篇幅截断后下发到浏览器，面板显示同步状态（同步中、已同步或读取失败）与行数，可展开、收起并复制内容；构建失败时失败原因会追加到日志末尾。日志同步依赖部署所用的火山引擎凭证，无法读取时面板显示失败状态，不影响部署继续进行。自定义创建和代码包部署均支持该能力。 部署到 AgentKit 时，根智能体的描述会自动整理为符合 Runtime 规范的单行描述（至多 255 字节，去除换行、控制字符与不安全符号）；完整描述保留在项目中，仅用于生成 Runtime 描述。若整理后的描述被 Runtime 拒绝，Studio 会去掉描述后重试创建，不影响其他配置。 ### 配置部署参数 在部署配置区选择发布区域和网络模式，并按需设置 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 时，访问鉴权默认为 API Key；如需改用用户身份验证，可在部署配置区选择 VeIdentity 用户池。Studio 服务端使用自身配置的火山引擎凭证加载当前账号可见的用户池列表，浏览器不接触凭证。列表中会标记当前 Studio 登录所用的用户池：选择该用户池时，Studio 会把登录后验证的 JWT 转发给 Runtime，调用方无需另行获取令牌；选择其他用户池时，调用方需使用该用户池签发的 JWT 访问 Runtime。用户池所在地域通过 `VEIDENTITY_REGION` 环境变量确定，默认为 `cn-beijing`。 ### 从代码包添加和部署 代码包部署是一种独立的创建方式：在「添加智能体」中选择「从代码包添加和部署」，上传一个已有的智能体项目压缩包，即可在 Studio 中查看或编辑其文件并直接部署到 AgentKit，无需逐项配置模型、工具和技能。适合把在外部编写好的 VeADK 项目快速上线，或对已有项目做少量调整后重新部署。 在「添加智能体」菜单中选择「从代码包添加和部署」，点击上传区域或拖拽文件即可选择 `.zip` 压缩包。压缩包最大 50 MB，解压后文件数不能超过 800 个，根目录必须包含 `app.py` 作为 AgentKit 启动入口。 上传成功后，Studio 会列出已识别的文件数量，并按压缩包文件名生成项目名称（符合 Google ADK 命名规则：以英文字母或下划线开头，仅含英文字母、数字和下划线，不使用保留名 `user`，长度不超过 64 个字符）。点击「查看文件」可在代码浏览器中预览或编辑文件内容；需要替换内容时重新上传压缩包即可。 在部署配置区选择发布区域和网络模式，与自定义创建的部署页一致。代码包部署不显示智能体拓扑和飞书渠道开关。 选择「部署」后，Studio 按四个阶段展示进度：上传代码包、镜像打包、创建 Runtime 和发布服务。每个阶段完成或失败时会在部署进度区显示对应状态。 Studio 会对压缩包做安全处理：自动忽略 `__MACOSX` 目录与 `.DS_Store` 文件；当全部文件位于同一个顶层目录时，会去掉这层包裹目录后再校验入口。包含绝对路径、空段、`.`、`..` 段或空字节的条目会被拒绝；重复文件路径也会报错。`app.py` 必须位于去除包裹目录后的根目录。 代码包中的 `app.py` 会在部署后的 AgentKit Runtime 中执行，可能访问外部服务或运行环境中的数据。只部署可信来源的项目，并为 Studio 使用权限受限的凭证。 | 校验项 | 限制 | 说明 | | :- | :- | :- | | 压缩包大小 | 50 MB | 单个上传压缩包的最大体积。 | | 文件数量 | 800 个 | 解压后保留文件数的上限。 | | 解压后总大小 | 50 MB | 解压后内容总大小上限。 | | 启动入口 | `app.py` | 去除包裹目录后的根目录必须包含该文件。 | | 路径安全 | — | 拒绝绝对路径、`.` / `..` 段、空字节；忽略 `__MACOSX` 与 `.DS_Store`。 | | 包裹目录 | 单层 | 全部文件同属一个顶层目录时自动去除该层。 | | 项目名称 | 64 个字符 | 由压缩包文件名生成，符合 ADK 命名规则。 | ### 添加技能 创建智能体时可从以下来源添加技能，添加后技能文件写入生成项目的 `skills/` 目录： * **Skill Hub**：在火山引擎公开技能仓库中按关键词检索技能并添加。 * **本地上传**：拖入文件夹或选择 ZIP 包。每个技能目录需包含 `SKILL.md`；Studio 检查文件是否存在、文件数量、大小和路径安全，完整的 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 登录状态、网络连通性和凭证权限，然后使用刷新按钮重试。 | 本地上传不再在导入阶段强制校验 `SKILL.md` 的 `name` 与 `description` 格式，也不要求目录名与 `name` 一致。如果技能在运行时报错，检查 `SKILL.md` frontmatter 是否符合 ADK 技能要求。 从 AgentKit SkillSpace 添加技能时，若云端版本提供完整文件包，Studio 会下载其中的 `SKILL.md`、脚本、参考文档和资源；未提供完整包时仅使用 `SKILL.md`。单个智能体可添加的技能数量没有固定上限。 ### 智能生成智能体配置 自定义创建的构建画布上方提供「智能生成」入口。在输入框中用一句自然语言描述目标，例如「创建一个短视频生产智能体，依次完成趋势调研、脚本编写、素材生产、视频生成和质量复核」，点击「智能生成」即可。 Studio 调用 `doubao-seed-2-0-lite-260428` 模型，根据需求生成一份经过校验的完整智能体配置草稿并填入画布，生成过程会消耗 Token。 生成结果会替换当前画布与属性配置。如果画布存在未保存的修改，Studio 会先要求确认是否继续。 #### 生成结果的结构 生成的配置遵循以下规则： * 优先使用 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` | 在代码沙箱中执行代码。 | 生成配置不会为 LLM 智能体分配企业知识库搜索工具。记忆、知识库与链路观测需在生成后于画布中按需启用，各后端的完整参数见对应组件页面。 使用 BytePlus 作为云服务商时，`web_search` 和 `parallel_web_search` 不出现在自定义创建和智能生成的内置工具列表中；火山引擎模式下不受影响。 #### 未决项 生成结果会列出尚未确定的资源或标识（如实例 ID、URL、凭证、MCP 服务或技能 ID），Studio 不会虚构这些信息。生成后需在画布中按需补充实际资源。 #### 使用步骤 在构建画布上方的输入框中用自然语言描述目标，输入长度上限为 8000 字符。 点击「智能生成」。生成期间输入框置灰，完成后画布填入新的配置草稿，并显示一条摘要说明。 查看生成结果中的未决项提示，按需在画布中补充实际资源或标识。 像自定义创建一样检查、编辑配置，然后生成项目并启动临时测试，或下载 ZIP、部署到 AgentKit。 生成完成后可点击「重新生成」再次基于同一需求生成新配置。 #### 权限与失败处理 启用角色访问控制时，智能生成仅对 `developer` 和 `admin` 开放。 生成失败时 Studio 会弹窗提示。常见情况包括： | 现象 | 检查方法 | | :- | :- | | 生成超时 | 服务端生成限时 180 秒，超时后返回超时提示，可缩短需求后重试。 | | 模型调用失败 | 检查火山引擎凭证与模型访问权限；错误信息已做凭据脱敏处理。 | | 提示无权限 | 确认当前账号具有 `developer` 或 `admin` 角色。 | ### 添加远程智能体 远程智能体通过 AgentKit 智能体中心发现并调用，适合把已经发布到中心的专业能力接入多智能体项目。远程智能体只能作为子智能体，不能作为根智能体；根智能体需要使用 LLM、顺序、并行或循环类型。 使用该能力前，应满足以下条件： * Studio 已配置可访问 AgentKit 的火山引擎凭证；部署到 VeFaaS 时，所绑定的 IAM Role 需要具备相应权限。 * 目标地域的 `default` 项目中至少存在一个当前账号可见的 AgentKit 智能体中心，且中心内已有可调用的远程智能体。 * 启用 Studio 角色权限时，当前用户具有 `developer` 或 `admin` 角色。 创建 LLM 或编排型根智能体，并完成模型、描述和系统提示词等必要配置。 在左侧智能体结构中为根智能体或其他本地智能体添加子智能体，然后将类型设为「远程智能体」。根节点上的远程智能体类型不可选择。 默认加载北京地域 `default` 项目下当前账号可见的智能体中心。使用其他地域时，先在「更多选项」中修改地域，再从下拉框选择中心；需要重新获取列表时使用刷新按钮。 按需设置召回数量和 OpenAPI 地址。远程智能体的名称、描述和能力来自中心返回的 Agent Card，无需单独填写名称或 A2A 地址。 生成项目并启动临时测试，输入一个需要目标中心专业能力的问题。响应能够使用中心内匹配智能体返回的信息，即表示发现和调用链路可用。 每轮任务中，父智能体会根据用户请求从所选中心发现匹配的远程智能体，并将其作为可调用能力使用。 | 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` 调整。每位登录用户最多同时运行 3 个生成智能体测试进程；超出上限时返回 429，需关闭不再使用的调试页面后重试。刷新页面后遗留的测试进程会被自动清理，单次测试运行最多接受 300 个项目文件。测试代码可能调用外部服务或访问运行环境中的数据，只应测试可信项目，并为 Studio 使用权限受限的凭证。 测试运行会自动规范化生成智能体中配置的 HTTP MCP 工具端点：URL 未以 `/mcp` 结尾时会自动补全 `/mcp`，并通过 Streamable HTTP 验证工具发现。若无法连接 MCP 服务完成工具发现，测试会返回错误，提示确认 URL 是否指向实际 MCP endpoint（通常以 `/mcp` 结尾）并检查 Token；画布中保存的原始 URL 不会被修改。 ### 配置记忆 为智能体启用长期记忆后，可在 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。各后端的完整参数、默认值和限制见对应组件页面。 选择 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)为准。 | OpenViking 的记忆归属 ID（`DATABASE_OPENVIKING_USER_ID`）与运行时用户标识（`Runner.user_id`）是不同的概念：前者隔离不同应用或租户的记忆，后者作为 OpenViking 的 peer ID 隔离终端用户记忆。详见[使用 OpenViking 存储](/productions/veadk/preview/zh/components/memory/openviking)。 启用 OpenViking 长期记忆会把会话写入外部 OpenViking 服务。使用前应确认数据处理、访问控制和保留策略符合业务要求。 ### 配置知识库 为智能体启用知识库后，可在 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 服务完成检索。 | 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 的临时凭证。凭证只在服务端使用，不会下发到浏览器。 | 现象 | 检查方法 | | :- | :- | | 知识库列表为空 | 确认北京地域 `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 的地域。 | 这两个值会同时用于本地调试运行和部署后的运行时，生成的 `.env.example` 也会包含这两个变量。沙箱 ID 与地域只在 Studio 服务端使用，不会下发到浏览器。 关于 `run_code` 的完整参数、Shell 执行和凭证要求，参见[代码沙箱](/productions/veadk/preview/zh/components/tools/code-sandbox)。 ## 查看子智能体移交 在多智能体项目中，根智能体可以把任务移交给子智能体执行。当发生移交时，Studio 会在对话中为子智能体的回复单独显示一张标注「智能体移交」的卡片，并展示该子智能体的名称和描述；子智能体的输出不再与根智能体的回复混在同一个消息气泡中。 子智能体的名称和描述来自项目结构中的智能体配置。如果子智能体未配置描述，卡片会显示默认说明。子智能体完成输出后，后续回复继续显示为根智能体的消息。 该展示适用于本地子智能体和远程智能体。远程智能体只能作为子智能体，不能作为根智能体。 ## 对话调用链路与问题反馈 在对话页面，每条助手回复旁提供调用链路查看和问题反馈入口，便于排查单轮执行问题。这些入口仅在普通智能体对话中可用，内置 Codex 智能体对话不提供。 ### 查看调用链路 每条助手回复旁的「Tracing 火焰图」按钮打开调用链路观测面板，以 span 树和详情面板展示该会话的执行轨迹，并在打开时以该轮回复的结束时间作为查询截止点。 * 本地调试会话直接读取 ADK 调试链路。 * 连接云端 Runtime 时，Studio 服务端使用自身配置的火山引擎凭证向 APMPlus 查询该会话的链路，浏览器不接触凭证。 云端 Runtime 的链路观测需在火山引擎控制台为对应智能体开启 APMPlus 链路观测。通过 Studio 部署的 Runtime 默认启用 APMPlus 链路观测；未开启链路观测的 Runtime 打开链路面板时会提示「该 Agent 暂未开启链路观测，请到控制台打开后使用」，链路查询失败时会提示稍后重试。 ### 问题反馈 每条助手回复旁的「问题反馈」按钮可针对该轮回复上报问题。在对话框中选择问题类型并补充描述后提交，提交内容会一并携带该轮的输入、输出、工具调用记录和链路信息，便于排查，并在上报前做凭据脱敏处理。可选问题类型如下： | 问题类型 | 说明 | | :- | :- | | 执行速度慢 | 回复生成或工具调用耗时过长。 | | 运行崩溃 | 智能体执行中断或报错。 | | 结果不准确 | 回复内容与预期不符或存在错误。 | | 工具调用失败 | 工具执行失败或返回异常。 | | 其他问题 | 不属于以上类别的问题。 | 侧边栏底部的「问题反馈」入口（标记为 Beta）用于反馈 Studio 整体使用问题：选择所属模块、问题类型并填写描述后提交。所属模块与当前所在页面对应，可在对话、智能体、自动化、搜索或其他之间选择；平台问题类型包括页面加载慢、功能无法使用、页面显示异常、操作无响应和其他问题。 问题反馈数据会上报到 AgentKit 团队用于改进产品，提交成功后会显示确认信息。请在描述中避免填写密钥、Token 等敏感信息；当前会话不可用时反馈可能失败，可关闭后重试。 ## 使用智能搜索 智能搜索提供会话、网络、知识库和长期记忆四种检索源： * **会话**：在当前智能体的历史消息中执行全文检索。 * **网络**：调用当前智能体挂载的 `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」中所述的服务端运行时代理一致。 部署完成后，Studio 会自动连接新创建的 Runtime。若 Runtime 已部署成功但 Studio 暂时无法连接（网关域名可能仍在生效，或当前网络/DNS 无法访问该 Runtime），部署任务会标记为「部署完成，暂未连接」并保留进度卡片与提示信息，可在「管理智能体」中重试连接。 ## 管理智能体 「管理智能体」列出当前用户可见的 AgentKit Runtime，可见范围由登录账号的角色决定：`admin` 可见全部 Runtime，`developer` 和普通用户仅可见自己创建的 Runtime。列表默认展示北京区域的 Runtime，也可以切换到上海。当可见范围包含全部 Runtime 时，当前用户创建的 Runtime 会标注「我创建的」。可以查看： * Runtime 名称、ID、状态、区域和创建时间； * 模型、描述、项目、版本、资源规格和更新时间； * 绑定的 Memory、Tool、Knowledge 与 MCP Toolset 标识； * Runtime 环境变量和主智能体信息。 * 智能体拓扑、远端调用链路与全局部署任务状态。 Studio 不会在浏览器中保存 Runtime API Key，因此管理页只显示 Runtime 返回的主智能体摘要，不加载完整子智能体树。 删除操作会永久删除对应的 AgentKit Runtime。确认该 Runtime 不再承载业务流量，并完成必要的数据和配置备份后再操作。 删除前 Studio 会弹出确认对话框，列出即将删除的智能体或草稿；确认后才会执行删除。删除过程中，被删除的智能体会从列表中暂时隐藏。若当前对话正在使用被删除的智能体，Studio 会清除当前选择并返回智能体管理页。 管理页可能展示 Runtime 的环境变量值。仅应向经过授权的用户开放 Studio，并避免把明文密钥放入普通环境变量；优先使用平台支持的密钥管理能力。 智能体工作台将已部署 Runtime 与本地草稿统一管理。每个已部署智能体显示当前版本号，并标注部署状态：部署中、待更新、尚未发布、失败或已取消。已部署的智能体可直接在工作台中重新编辑并更新到同一 Runtime，无需新建部署。 构建或部署阶段失败时，Studio 会在工作台展示服务端返回的完整错误信息，默认展开且可复制，便于直接定位问题；部署与更新失败时还可在错误面板中重新发起。 ### 管理草稿 在自定义创建过程中，Studio 会将未发布的智能体草稿保存在当前浏览器中，并按登录用户隔离。草稿与已部署 Runtime 一并出现在「管理智能体」列表，每条草稿显示更新时间与「草稿」标识；正在部署的草稿显示「部署中」标识，可在该草稿上查看部署进度。草稿支持编辑与删除，删除前会弹出确认对话框。 草稿仅保存在当前浏览器，不会同步到服务器或其他设备。清除浏览器存储、使用隐私模式或更换浏览器后草稿会丢失。 MCP 工具的鉴权 Token 会转换为环境变量引用保存：生成源码仅保留 `${ENV_NAME}` 引用，Token 值写入部署环境变量；YAML 导出与浏览器草稿均保留对应的环境变量值。更新已部署的 Runtime 时会重新加载已有环境变量值，在部署表单中输入新的 Token 会覆盖原有值。 草稿保存使用浏览器本地存储空间。存储空间不足或被浏览器拒绝写入时，Studio 会提示对应原因，可删除不再需要的草稿或清理站点存储后重试。 ## 更新已部署的智能体 已部署到 AgentKit 的智能体可以在 Studio 中重新编辑并更新到同一 Runtime，而不必每次创建新部署。更新会基于该 Runtime 的当前版本生成递增的镜像版本，并在原 Runtime 上发布新版本。 在智能体工作台中选择一个已部署的智能体。Studio 从该 Runtime 读取智能体的名称、描述、模型、系统提示词、工具与子智能体结构，并加载到可编辑草稿中。 在画布或配置面板中调整模型、系统提示词、工具、技能或子智能体结构，与创建智能体时使用相同的编辑能力。 选择「更新并发布」。Studio 按准备、构建镜像、部署服务、发布的阶段展示进度；部署服务阶段会复用原 Runtime 标识并发布递增版本。 更新完成后，工作台中该智能体的版本号递增，部署状态恢复为已发布。可在对话页面连接该 Runtime 验证新配置是否生效。 在更新过程中取消部署任务不会销毁已有 Runtime，原版本仍保持可用。仅创建全新部署时，取消任务才会清理未完成的 Runtime 资源。 更新操作仍然受 Studio 角色权限约束：`admin` 可更新全部 Studio 管理的 Runtime，`developer` 只能更新自己创建的 Runtime，普通用户无权更新。 更新 Runtime 时，Studio 会从该 Runtime 加载已有环境变量并保留；在部署表单中显式填写的值覆盖原有值。选择 Runtime 目标进行调试测试时，该 Runtime 的环境变量会注入测试进程。 ## 查看接入方式 在「管理智能体」中选择一个已部署的智能体后，详情页提供「接入方法」标签。该标签探测当前 Runtime 实际暴露的公开接入协议与端点，并给出可直接参考的调用示例，方便在不查阅控制台的情况下从外部调用该智能体。 接入方式由 Studio 在打开标签时向 Runtime 发起只读探测确认，仅展示已确认的协议与地址。Runtime 未暴露的协议显示为不可用，Studio 不会虚构未确认的端点。 ### 支持的协议 | 协议 | 发现方式 | 调用地址 | | :- | :- | :- | | API Server | 探测 Runtime 的 `/list-apps` 接口 | `/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。 显示的 API Key 会出现在浏览器中。仅向经过授权的用户开放 Studio，并在使用后及时关闭显示；如需在程序中调用，应通过密钥管理服务或环境变量获取凭证，不要从 Studio 页面复制明文密钥长期保存。 ### 调用示例 标签根据探测到的协议和鉴权方式，生成对应的 Python 请求示例。示例中的端点和应用名称来自探测结果，凭证使用占位符。 API Server 协议的示例通过 `requests` 创建会话并调用 `/run_sse` 流式接口： ```python lines theme={null} import uuid import requests BASE_URL = "" APP_NAME = "<应用名称>" USER_ID = "demo-user" SESSION_ID = str(uuid.uuid4()) 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 = "" 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()) ``` 示例仅用于说明调用方式。实际端点、应用名称和鉴权方式以标签中探测到的结果为准；未启用鉴权时无需传入 `Authorization` 头。 ## 浏览智能体 侧边栏的「智能体」入口打开智能体目录，用于浏览、连接和查看当前账号下的 AgentKit Runtime。对话页面顶部导航栏的智能体选择器也提供进入该目录的入口。 智能体目录通过顶部的类型标签切换，默认显示「通用智能体」： | 类型 | 说明 | | :- | :- | | 通用智能体 | 列出当前登录用户创建的全部 AgentKit Runtime。 | | Codex 智能体 | 跳转到 Codex 临时会话创建入口。 | | OpenClaw 智能体 | 暂未开放。 | | Hermes 智能体 | 暂未开放。 | 通用智能体列表跨全部地域加载当前用户自己的 Runtime，并在滚动到列表底部时自动加载下一页，加载完成后提示「已加载全部智能体」。使用顶部的搜索框可按名称过滤已加载的智能体。 每张智能体卡片显示 Runtime 名称和创建时间。点击卡片进入该 Runtime 的详情视图，卡片上的「连接」按钮将该 Runtime 设为当前对话使用的智能体并切换到对话页面；已连接的智能体会置顶显示。列表加载失败时显示错误信息并提供「重新加载」按钮，列表为空时显示对应的空状态提示。连接失败时的排查方式与[选择云端 Runtime](#选择云端-runtime)一致。 智能体目录仅列出当前登录用户创建的 Runtime，不按地域筛选。需要浏览其他用户或全部 Runtime 时，使用导航栏的智能体选择器或管理页面，可见范围取决于角色权限。 ## 选择云端 Runtime 在云端模式下，对话页面顶部的智能体选择器会列出当前用户可见的 AgentKit Runtime，可见范围与「管理智能体」一致，由登录账号的角色决定，并按区域分页浏览。每条 Runtime 提供两个独立操作： * **连接**：将该 Runtime 设为当前对话使用的智能体，选择器随即关闭并切换到该 Runtime。 * **信息**：展开一个分标签信息面板，无需连接或持久化即可预览该 Runtime 的能力。 信息面板包含两个标签： * **智能体信息**：读取 Runtime 提供的名称、模型、描述、子智能体、工具、技能、可用检索源，以及已挂载组件及其后端类型。该信息不包含系统提示词、凭据或环境变量值。 * **Runtime 详情**：展示 Studio 可读取的模型、描述、状态、区域、资源规格、版本和环境变量。 「Runtime 详情」标签可能展示 Runtime 的环境变量值。仅向经过授权的用户开放 Studio，并优先使用平台支持的密钥管理能力。 连接 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 就绪状态，还是调整网络部署模式。 ## 使用内置智能体和 Skill 创建 新会话支持三种模式，模式选择器对所有用户可见： * **智能体对话**：与当前选中的智能体进行普通多轮对话。空输入时显示快捷提示，可点击快速填入常用提问。 * **内置智能体**：使用平台提供的智能体进行对话。当前可选 Codex 智能体，在独立的 AgentKit CodeEnv Session 中进行多轮对话；退出后删除云端 Session，内容不写入普通历史会话。 * **Skill 创建**：并行生成两个 Skill 候选方案，完成后可对比、预览、下载 ZIP 或添加到 AgentKit。 Skill 创建仅对 `developer` 和 `admin` 开放。每个候选使用独立 Session，生成结果在打包前会检查 `SKILL.md`、文件数量、大小和路径安全。候选 Session 的有效期为 30 分钟；重新创建或离开任务时会立即清理。创建或凭据准备失败时，Studio 会展示不包含凭据的错误信息，便于定位 Tool 状态、区域或模型凭据问题。 普通对话在同一会话中发送后续消息时会继续使用已有消息历史；只有新建会话才会从空上下文开始。若 Runtime 无法连接，Studio 会区分权限不足、Agent Server 不可达、私网 Runtime 不可达和鉴权失败，并显示对应的排查方向。 在云端模式下，Studio 不会自动选择第一个可用智能体。开始新会话前需在对话页面顶部的智能体选择器中手动连接一个 Runtime；未选择智能体时开始新会话会提示先选择智能体，并打开智能体管理页。 ### 本地配置 本地使用内置智能体和 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；本地使用该模式时必填。 | | `AGENTKIT_SANDBOX_REGION` | `cn-beijing` | 内置智能体和 Skill 创建在创建 Session、查找 Tool 时优先使用的地域，支持 `cn-beijing` 与 `cn-shanghai`。 | | `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 时使用的项目名称。 | 创建内置智能体或 Skill 的 Session、查找对应 Tool 时，Studio 会优先使用 `AGENTKIT_SANDBOX_REGION` 指定的地域（默认 `cn-beijing`）；若该地域返回资源不存在，会自动回退到另一个支持地域（北京 ↔ 上海）继续操作，其他错误不会触发回退。部署到 VeFaaS 时该地域与 `--region` 一致。 ### 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 会话后才能重新选择。 #### 权限 点击输入框左侧的权限按钮可打开「Codex 权限」对话框。设置保存到当前 Sandbox Session，并同步到其中的所有 Thread。 | 设置 | 可选值 | 说明 | | :- | :- | :- | | 沙箱模式 | 只读 / 工作区写入 / 完全访问 | 控制文件系统隔离范围。选择「完全访问」时会关闭文件系统与网络隔离，并自动启用网络访问。 | | 审批策略 | 仅不可信命令 / 按需审批 / 不审批 | 决定 Codex 何时暂停并请求人工确认命令或文件修改。 | | 审批方式 | 由我审批 / 自动审查 | 选择审批请求由你在 Studio 中处理，还是交由 Codex 自动审查流程处理。 | | 允许网络访问 | 开 / 关 | 控制「工作区写入」与「只读」模式中的外部网络访问。「完全访问」时固定为开且不可关闭。 | 「完全访问」会关闭文件系统与网络隔离，仅应在任务可信且需要完整主机权限时使用。 #### 操作审批 当审批策略需要人工确认且 Codex 请求执行命令或修改文件时，Studio 会弹出审批对话框，展示待审批的命令、文件变更和执行目录。可选择「拒绝」「仅本次允许」或「本会话允许」。审批结果会以活动记录的形式显示在对话中。 #### 终端与浏览器 在「添加」菜单中选择「进入终端」或「查看浏览器」，可在当前 AgentKit Session 中打开交互式终端或浏览器视图。连接过程中显示加载状态，打开失败时可重试。还可以从该菜单上传图片、文档或 PDF 以及视频到当前对话；上传的图片会在对话中显示预览，点击后通过共享图片查看器打开。 #### 状态与历史 `/status` 会以活动记录形式展示当前 Thread、工作空间、模型、运行状态、累计 Token 与上下文窗口。每轮助手回复后会显示该轮的 Token 用量。输入 `/resume` 可打开「恢复 Codex 对话」对话框，选择最近更新的 Thread 恢复。 沙箱会话列表中的「创建者」显示当前登录用户的显示名称（OAuth 邮箱或本地用户名），便于在多用户部署中区分会话归属；未获取到显示名称时回退为内部用户标识。 ## 管理会话能力 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` 两个评测集。创建过程在「创建评测集」阶段执行，完成后部署流程进入结束阶段。 评测集创建失败不影响已部署的 Runtime。失败时部署结果中会显示警告信息，已成功部署的智能体仍可正常使用。 ### 自动评测 用户在 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 评测集，并在案例列表中标记来源为「自动回流」，同时展示评分和评分理由。 如果用户在同一会话中发送新消息，静默计时会被重置，确保只在对话暂停后才执行评测。 ### 优化建议 当自动评测积累了足够的案例后，Studio 基于该智能体已有的评测案例生成优化建议。优化建议按优先级和模块分组展示在工作台的「优化项」标签中： | 字段 | 说明 | | :- | :- | | 修复优先级 | 按高、中、低标注每组的修复紧迫程度。 | | 建议优化模块 | 标注建议改进的模块，包括智能体结构、提示词、工具、知识库、记忆、工作流等。 | | 优化建议和理由 | 每条建议包含具体的改进描述和对应的评分依据。 | 优化建议由 `doubao-seed-2-0-lite-260428` 模型根据累计评测案例和智能体配置生成，仅供参考。评测模型可通过环境变量 `VEADK_STUDIO_EVALUATION_MODEL` 覆盖。 ### 查看评测案例 工作台的「评测集」标签展示该智能体的所有评测案例，支持按 Good Case / Bad Case 和自动回流 / 手动回流筛选。自动回流案例显示评分（0–100 分制）和评分理由；手动回流案例（用户通过赞/踩创建）的评分列显示为「—」。两种来源的案例均可删除。 ## 自动化集成 Studio 侧边栏的「自动化」页面提供研发工具和消息渠道的自动化集成。自动化按分类组织，当前包括「研发」和「消息渠道」两个分类。Coding Agents 集成在本地检测并配置已安装的编程智能体客户端；GitHub 自动化通过浏览器直接调用 GitHub API 创建分支、文件和 Pull Request；飞书自动化在 Studio 中生成基础智能体并直接部署到 AgentKit Runtime。 ### 配置 Coding Agents 将 VeADK 与 AgentKit 内置 Skills 全局安装到本机已安装的编程智能体客户端，使其在开发 VeADK 应用时具备构建、调试、部署与平台操作能力。该集成标记为「本地」，仅在启动 Studio 的本机执行检测与安装，不访问云资源。 打开「自动化」页面中的「配置 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 以独立子目录写入，包含 `SKILL.md` 及其附带的脚本、参考文档和资源。 浏览器只能从固定的客户端与 Skill 标识中选择，不接受任意的 Shell 命令、文件系统路径或 Skill 内容；Skills 来源于 Studio 内置资源，不来自浏览器上传。安装前可预览每个 Skill 包含的文件。 安装采用原子替换：Studio 先将 Skill 文件写入临时目录，校验通过后再替换目标目录；目标目录已存在同名 Skill 时会先备份再替换，安装失败时自动回滚到原内容。 安装会写入启动 Studio 的用户主目录下的全局 Skills 路径。请确认运行 Studio 的用户身份与编程智能体客户端所属用户一致，避免 Skills 安装到错误的用户目录。 启用角色权限控制时，配置 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 | 是 | — | 需要对目标仓库的写入权限；仅用于当前请求，不持久化。 | 持续交付和模板导入工作流均需要在仓库中配置 `VOLCENGINE_ACCESS_KEY` 和 `VOLCENGINE_SECRET_KEY` GitHub Secrets；使用临时凭据时还需配置 `VOLCENGINE_SESSION_TOKEN`。这些 Secrets 在 GitHub 中管理，不经过 Studio。 ### PR 自动评审 在目标仓库中添加 GitHub Actions 工作流，在隔离的 AgentKit Sandbox 中评审同仓库的非草稿 PR，并将评审结果发布为 GitHub Review。 PR 评审工作流仅评审与目标仓库相同的非草稿 PR，不评审 fork 仓库的 PR，不会读取 fork PR 的仓库 Secrets。 | 参数 | 必填 | 默认值 | 说明 | | :- | :- | :- | :- | | 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` | 使用临时凭据时必填。 | ### 飞书机器人 飞书机器人自动化当前标记为 Beta。 在 Studio 中直接创建一个由 AgentKit Runtime 驱动的飞书智能体。填写已发布飞书应用的凭据后，Studio 生成基础智能体、创建独立 Runtime，并启用飞书消息长连接。部署按生成智能体、构建镜像、创建 Runtime 和发布服务四个阶段展示进度。部署完成后可在页面中打开 Runtime 控制台。 | 参数 | 必填 | 默认值 | 说明 | | :- | :- | :- | :- | | 智能体名称 | 是 | `feishu_assistant` | 将作为新 Runtime 中的根智能体名称。 | | 部署地域 | 是 | `cn-beijing` | Runtime 与构建产物创建的地域，可选 `cn-beijing` 或 `cn-shanghai`。 | | 飞书 App ID | 是 | — | 来自飞书开放平台的应用凭证。 | | 飞书 App Secret | 是 | — | 仅用于本次部署，不会写入生成源码或浏览器存储。 | 飞书机器人的 App Secret 仅用于本次部署，不写入生成源码、工作流或日志。部署期间可取消部署，取消将停止任务并清理已创建的 Runtime。 ## `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` | 自定义系统名称，最多 6 个字符。 | | `--site-logo` | `str \| None` | `VEADK_SITE_LOGO` | 自定义 Logo，支持本地图片路径或 HTTP(S) URL。 | | `--host` | `str` | `127.0.0.1` | 监听地址。 | | `--port` | `int` | `8000` | 监听端口。 | | `--provider` | `volcengine` \| `byteplus` | `volcengine` | 选择 AgentKit 服务的云服务商。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` | 登录按钮文案。 | | `--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`。部署完成后，命令会把公网回调地址注册到用户池客户端并更新应用配置。 此操作会创建或修改 VeFaaS、API Gateway、IAM 和 VeIdentity 资源，可能产生费用并影响线上访问。默认 Role 具备用于创建和管理 AgentKit Runtime 及相关云资源的广泛权限。生产环境部署前应由管理员审查权限范围；需要收敛权限时，通过 `--iam-role` 使用预先配置的 Role。 准备用户池 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 即可继续部署。STS 临时凭证的 Session Token 通过 `--volcengine-session-token` 显式传入，或依次读取 `VOLCENGINE_SESSION_TOKEN`、`VOLC_SESSIONTOKEN` 环境变量和 `~/.volc/credentials` 中 `[default]` 配置的 `session_token` 字段；未提供时留空，仅使用长期 AK/SK。 部署成功后，终端会输出公网 URL 和 VeFaaS 应用 ID。打开公网 URL 时，Studio 会先跳转到 VeIdentity 完成登录。 `--region` 指定 Studio 的部署地域，默认为 `cn-beijing`，也支持 `cn-shanghai`；VeFaaS Application、Function、API Gateway 和 AgentKit 资源均使用所选部署地域。部署时还会自动在所部署地域以及北京、上海两个地域之间查找 VeIdentity 用户池与客户端：优先查询部署地域，未命中时跨地域查询另一个地域；跨地域命中时终端会输出 warning 并继续部署。`--project` 指定 VeFaaS 函数所属项目，默认为 `default`。 部署者的长期 AK/SK 不会写入 VeFaaS 应用环境变量。已部署的 Studio 使用绑定 IAM Role 的临时凭证访问火山引擎服务。 未指定 `--sandbox-chat-codex-tool-id` 与 `--sandbox-skill-creator-tool-id` 时，部署命令会在 `--region` 指定的地域创建所需的 AgentKit Tool，分别用于内置智能体和 Skill 创建；火山引擎部署还会额外创建一个 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 使用 `seed-2-0-lite-260228` 模型与 `https://ark.ap-southeast.bytepluses.com/api/v3`，候选地域为 `ap-southeast-1`。`--sandbox-dev-tool-id` 仅支持火山引擎部署，在 BytePlus 部署中传入会报错。 ### 应用内更新 Studio 固定从维护在北京地域的 `veadk-studio` TOS 发布源读取新版本，客户部署地域无需额外配置；部署完成后管理员可在导航栏中把前端与 Python 后端一起升级。使用 `--studio-update-bucket` 与 `--studio-update-prefix`（或对应的 `VEADK_STUDIO_UPDATE_BUCKET`、`VEADK_STUDIO_UPDATE_PREFIX` 环境变量）可覆盖默认发布源，发布源地域始终为 `cn-beijing`。 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-prefix "veadk/studio/main" ``` 应用内更新仅对具备 `admin` 角色的登录用户开放，更新 Studio 自身的 VeFaaS Function，不影响已部署的 AgentKit Runtime。 ### 部署参数 | 选项 | 类型 | 默认值 | 说明 | | :- | :- | :- | :- | | `--user-pool-id` | `str` | 必填 | 用于 Studio 登录的 VeIdentity 用户池 UID。 | | `--allowed-client-id` | `str` | 必填 | 用于登录的用户池客户端 UID。 | | `--client-secret` | `str` | `""` | 无法通过客户端 UID 读取密钥时显式提供。直接传参可能进入 shell 历史，能够读取时应省略。 | | `--vefaas-app-name` | `str` | 必填 | VeFaaS 应用名称，长度 4–64，只能包含字母、数字和连字符，不能包含下划线。 | | `--provider` | `volcengine` \| `byteplus` | `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 等资源所在区域。部署时会跨北京、上海查找 VeIdentity 用户池。 | | `--project` | `str` | `default` | VeFaaS 函数所属项目。 | | `--iam-role` | `str \| None` | `None` | 绑定到函数的既有 IAM Role TRN；省略时创建或复用默认 Role。 | | `--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 名称，最多 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]` 配置。 | | `--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 资源，便于在控制台查看发布日志。 | | `--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` 设置。 | | `--sandbox-dev-tool-id` | `str \| None` | 自动创建 | 开发沙箱使用的 AgentKit DevEnv Tool ID；仅支持火山引擎部署，也可通过 `SANDBOX_DEV` 设置。 | | `--studio-update-bucket` | `str` | `veadk-studio` | 存放 Studio 不可变发布包的 TOS Bucket；部署时写入函数环境变量 `VEADK_STUDIO_UPDATE_BUCKET`。也可通过 `VEADK_STUDIO_UPDATE_BUCKET` 设置。 | | `--studio-update-prefix` | `str` | `veadk/studio/main` | Studio 主发布渠道的 TOS 对象前缀。也可通过 `VEADK_STUDIO_UPDATE_PREFIX` 设置。 | | `--apmplus-aid` | `str` | `""` | APMPlus Client aid，用于 Studio 前端埋点。也可通过 `VEADK_STUDIO_APMPLUS_AID` 设置。 | | `--apmplus-token` | `str` | `""` | APMPlus Client token，用于 Studio 前端埋点。也可通过 `VEADK_STUDIO_APMPLUS_TOKEN` 设置。 | | `--apmplus-domain` | `str` | `apmplus.volces.com` | APMPlus 数据上报域名。也可通过 `VEADK_STUDIO_APMPLUS_DOMAIN` 设置。 | | `--apmplus-env` | `str` | `production` | APMPlus 环境名称。也可通过 `VEADK_STUDIO_APMPLUS_ENV` 设置。 | ## 前端使用数据采集 部署 Studio 时可通过 APMPlus 前端埋点统计 Studio 实例访问量、登录使用情况，以及智能体部署、沙箱创建、智能体连接、对话发送、调试测试和源码下载的结果。埋点默认关闭，仅当同时配置 APMPlus Client 的 aid 与 token 后才启用；未配置或上报失败时不影响 Studio 正常使用。 `veadk studio deploy` 通过 `--apmplus-aid`、`--apmplus-token`、`--apmplus-domain` 与 `--apmplus-env` 配置埋点；部署时会自动注入部署 ID、用户池 ID、部署地域和项目等元信息供前端关联，无需手动设置。配置任一 APMPlus 选项时，`--apmplus-aid` 与 `--apmplus-token` 必须同时提供，否则部署会报错。 ```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" \ --apmplus-aid "123456" \ --apmplus-token "your-apmplus-client-token" ``` 也可以通过环境变量 `VEADK_STUDIO_APMPLUS_AID` 与 `VEADK_STUDIO_APMPLUS_TOKEN` 提供配置；`VEADK_STUDIO_APMPLUS_DOMAIN` 与 `VEADK_STUDIO_APMPLUS_ENV` 分别覆盖上报域名（默认 `apmplus.volces.com`）和环境名称（默认 `production`）。本地启动 `veadk studio` 时同样可设置这些环境变量启用埋点。 埋点仅采集使用统计维度，包括部署 ID、用户 ID、角色、地域、来源、创建方式、是否使用智能生成，以及智能体部署、沙箱创建、智能体连接、对话发送、调试测试和源码下载的成功或失败结果与失败阶段。失败事件附带错误摘要时会自动脱敏密钥、令牌和密码，截取前 300 个字符后上报。埋点不采集对话内容、提示词、生成代码、环境变量值或任何密钥。应用内更新 Studio 时会保留已配置的 APMPlus 环境变量。 ## 更新已部署的 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 仅在显式传入相应参数时覆盖。 | 选项 | 类型 | 默认值 | 说明 | | :- | :- | :- | :- | | `--provider` | `volcengine` \| `byteplus` | `volcengine` | 已部署 Studio 的云服务商。选择 `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-skill-creator-tool-id`、`--skill-creator-tool-id` | `str \| None` | 保留云上值 | 显式传入时替换 Skill 创建使用的 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 \ --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` 可见。 本地用户名保存在浏览器中，可被用户修改或冒充，仅适用于本地开发与功能验证。生产环境必须使用 OAuth 或 gateway 认证，以经过验证的登录信息确定身份与权限。 ## 查看系统版本 登录后，侧边栏底部的账号菜单提供「系统信息」入口，选择后弹出对话框展示 Studio 的「当前版本」。 本地启动或从源码构建部署时，版本号取自已安装的 VeADK 版本。当 Studio 切换到云端 Frontend 发布版本时，显示对应的发布版本号；未取到版本信息时显示「—」。