在本地启动
从智能体目录的上一级目录运行:--open 会在服务就绪后打开 http://127.0.0.1:8000。未传入该选项时,Studio 只启动服务,不自动打开浏览器。
火山引擎凭证用于工作台中的模型、云资源查询和 AgentKit 部署。生产环境应通过环境变量或密钥管理服务提供凭证,不要把凭证写入项目文件。
自定义品牌
使用--site-title 设置最多 6 个字符的系统名称,使用 --site-logo 指定本地图片或 HTTP(S) 图片 URL。Logo 会用于侧边栏、登录页和浏览器 favicon,系统名称也会作为浏览器页面标题;省略 --site-title 时使用默认名称 VeADK Studio。
VEADK_SITE_TITLE 与 VEADK_SITE_LOGO 环境变量配置。部署到 VeFaaS 时可使用相同参数;网络图片会在部署时下载并打包,部署后的站点不依赖原图片 URL。
创建智能体
- 在「添加智能体」中选择自定义;智能模式、模板和工作流入口暂不可用。
- 配置模型、系统提示词、工具、记忆和知识库,并从 Skill Hub、本地上传或 AgentKit SkillSpace 添加技能。多智能体项目还可以配置顺序、并行、循环或 A2A 节点。
- 检查生成的项目文件,并在受限的临时进程中测试运行;需要离线使用时下载 ZIP。
- 选择部署到 AgentKit,观察构建镜像、部署和发布进度。
添加远程智能体
远程智能体通过 AgentKit 智能体中心发现并调用,适合把已经发布到中心的专业能力接入多智能体项目。远程智能体只能作为子智能体,不能作为根智能体;根智能体需要使用 LLM、顺序、并行或循环类型。 使用该能力前,应满足以下条件:- Studio 已配置可访问 AgentKit 的火山引擎凭证;部署到 VeFaaS 时,所绑定的 IAM Role 需要具备相应权限。
- 已获取包含可调用远程智能体的 AgentKit 智能体中心 ID,且当前凭证有权访问该中心。
- 启用 Studio 角色权限时,当前用户具有
developer或admin角色。
1
配置根智能体
创建 LLM 或编排型根智能体,并完成模型、描述和系统提示词等必要配置。
2
添加远程智能体节点
在左侧智能体结构中为根智能体或其他本地智能体添加子智能体,然后将类型设为「远程智能体」。根节点上的远程智能体类型不可选择。
3
配置智能体中心
填写 AgentKit 智能体中心 ID。中心不在北京地域时,在「更多选项」中设置其所在地域。
4
配置发现范围
按需设置召回数量和 OpenAPI 地址。远程智能体的名称、描述和能力来自中心返回的 Agent Card,无需单独填写名称或 A2A 地址。
5
测试调用
生成项目并启动临时测试,输入一个需要目标中心专业能力的问题。响应能够使用中心内匹配智能体返回的信息,即表示发现和调用链路可用。
例如,创建名为
support_router 的 LLM 根智能体,为其添加一个远程智能体子节点,填写「售后服务」智能体中心 ID,并保留召回数量 3 与北京地域。测试时输入「查询订单配送异常并给出处理建议」;如果中心中存在匹配能力,根智能体会调用相应的远程智能体完成任务。
排查远程智能体问题
测试运行进程默认保留 1800 秒,可通过
--generated-agent-test-run-ttl 调整。测试代码可能调用外部服务或访问运行环境中的数据,只应测试可信项目,并为 Studio 使用权限受限的凭证。
使用智能搜索
智能搜索提供会话、网络、知识库和长期记忆四种检索源:- 会话:在当前智能体的历史消息中执行全文检索。
- 网络:调用当前智能体挂载的
web_search工具实时检索。 - 知识库:使用当前智能体挂载的知识库执行语义检索。
- 长期记忆:使用当前智能体挂载的长期记忆后端执行语义检索。
部署网络模式
在部署页可为 AgentKit Runtime 选择网络模式,决定 Runtime 的公网暴露方式:
选择 VPC 或公网 + VPC 模式时,需要填写 VPC ID 和子网 ID。
VPC 私有 Runtime 部署完成后不返回公网数据面地址,Studio 通过服务端运行时代理访问该 Runtime,数据面 API Key 始终保留在服务端,不会下发到浏览器。该连接方式与「选择云端 Runtime」中所述的服务端运行时代理一致。
管理智能体
「管理智能体」列出当前登录用户通过该工作台部署的 AgentKit Runtime。列表默认展示北京区域的 Runtime,也可以切换到上海。列表按部署时记录的用户标识过滤,可以查看:- Runtime 名称、ID、状态、区域和创建时间;
- 模型、描述、项目、版本、资源规格和更新时间;
- 绑定的 Memory、Tool、Knowledge 与 MCP Toolset 标识;
- Runtime 环境变量和主智能体信息。
- 智能体拓扑、远端调用链路与全局部署任务状态。
选择云端 Runtime
在云端模式下,对话页面侧边的智能体选择器会列出当前登录用户通过该工作台部署的 AgentKit Runtime,并按区域分页浏览。每条 Runtime 提供两个独立操作:- 连接:将该 Runtime 设为当前对话使用的智能体,选择器随即关闭并切换到该 Runtime。
- 信息:展开一个分标签信息面板,无需连接或持久化即可预览该 Runtime 的能力。
- 智能体信息:读取 Runtime 提供的名称、模型、描述、子智能体、工具、技能、可用检索源,以及已挂载组件及其后端类型。该信息不包含系统提示词、凭据或环境变量值。
- Runtime 详情:展示 Studio 可读取的模型、描述、状态、区域、资源规格、版本和环境变量。
「Runtime 详情」标签可能展示 Runtime 的环境变量值。仅向经过授权的用户开放 Studio,并优先使用平台支持的密钥管理能力。
- 权限不足:当前账号无权访问该 Runtime,可刷新列表或重新登录后重试。
- Agent Server 不可连接:Runtime 的 Agent Server 未提供连接接口,通常是 Runtime 尚未就绪或版本不兼容,需确认 Runtime 状态与版本。
- 鉴权失败:Runtime 服务拒绝了连接请求,需检查 Runtime 的鉴权配置。
使用临时会话和 Skill 创建
新会话支持三种模式:- 智能体对话:与当前选中的智能体进行普通多轮对话。
- 临时会话:在独立的 AgentKit CodeEnv Session 中进行多轮对话;退出后删除云端 Session,内容不写入普通历史会话。
- Skill 创建:并行生成两个 Skill 候选方案,完成后可对比、预览、下载 ZIP 或添加到 AgentKit。
developer 和 admin 开放。每个候选使用独立 Session,生成结果在打包前会检查 SKILL.md、文件数量、大小和路径安全。候选 Session 的有效期为 30 分钟;重新创建或离开任务时会立即清理。创建或凭据准备失败时,Studio 会展示不包含凭据的错误信息,便于定位 Tool 状态、区域或模型凭据问题。
普通对话在同一会话中发送后续消息时会继续使用已有消息历史;只有新建会话才会从空上下文开始。若 Runtime 无法连接,Studio 会区分权限不足、Agent Server 不可达和鉴权失败,并显示对应的排查方向。
本地配置
本地使用临时会话和 Skill 创建前,分别准备两个处于Ready 状态的 AgentKit CodeEnv Tool,并配置其 ID:
veadk studio 参数
部署到 VeFaaS
veadk studio deploy 将 Studio 部署为 VeFaaS 应用,并接入 VeIdentity 登录。部署命令会创建或复用 Serverless API Gateway;未指定 IAM Role 时,还会创建或复用 VeADKFrontendServiceRole 及 VeADKFrontendPolicy。部署完成后,命令会把公网回调地址注册到用户池客户端并更新应用配置。
准备用户池 UID、用户池客户端 UID 和符合权限要求的火山引擎凭证,然后执行:
--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,可通过参数直接复用。
部署参数
更新已部署的 Studio
veadk studio update 从本地 VeADK 源码重新构建 Studio,更新已有 VeFaaS Function 的代码并重新发布原 Application。运行前安装 Node.js 与 npm,并在 VeADK 源码目录执行:
--region 和 --project 时,命令会在北京、上海及全部可见项目中查找同名 Application。若存在多个候选项,需要补充地域或项目缩小范围。更新保留 Application 与 Function ID、访问 URL、SSO、IAM、网关和已有环境变量;品牌和两个 CodeEnv Tool ID 仅在显式传入相应参数时覆盖。
Studio 角色与 Runtime 权限
--admin 和 --developer 各自接收逗号分隔的本地用户名或 OAuth 邮箱名单。空格会被忽略,身份匹配不区分大小写;同一身份同时出现在两个名单时,admin 优先。本地启动示例:
VEADK_STUDIO_ADMINS 和 VEADK_STUDIO_DEVELOPERS 环境变量设置这两个名单。部署 Studio 时使用相同参数:
admin 处理,拥有全部 Studio 能力并可见全部 Runtime。只要传入任一名单就会启用角色权限;未命中名单的身份为普通用户。
Studio 根据登录账号限制 Runtime 的可见范围;没有创建者记录的历史 Runtime 仅
admin 可见。