Studio 智能体工作台

​

在本地启动

export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

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

​

Studio 持久化存储

​

云端部署

​

本地启动

​

自定义品牌

veadk studio \
  --site-title "火山助手" \
  --site-logo "./logo.png"

​

界面语言

​

创建智能体

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

​

模型选择

​

模型回退配置

• 同提供商回退：仅指定模型名称，自动复用主模型的提供商、API 地址和 API Key。生成的项目代码通过 model_name 列表实现回退。
• 跨提供商回退：为每个回退端点单独指定模型提供方、API 地址和 API Key。生成的项目代码使用 ModelFallbackEndpoint 对象，通过 model_fallbacks 参数传入。

​

配置部署参数

​

配置构建资源

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

​

配置智能体优化

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

​

配置云上环境

​

工作区

​

管理运行环境

​

创建运行环境

​

自定义配置

​

基础环境类型

​

上传 Dockerfile

​

从 Git 仓库构建

​

绑定已有 CR 镜像

​

构建环境镜像

​

环境构建资源

veadk studio deploy \
  --vefaas-app-name <app-name> \
  --environment-cp-workspace <workspace-id-or-name> \
  --environment-cr-repository <registry/namespace/repository>

​

环境分享码

​

导出分享码

​

导入分享码

​

智能模式

​

使用流程

​

部署已验证源码

​

会话管理

​

项目版本库

版本比较

​

从代码包添加和部署

​

从存量项目迁移

​

迁移效果评测

​

启用评测

​

配置评测用例

​

评测维度

​

评测流程

1. 准备评测环境：校验迁移产物和评测用例。
2. 补充环境变量（仅在需要时）：如果迁移产物声明了必需或可选的环境变量，Studio 会暂停评测并提示填写。提交后评测继续。
3. 部署临时 Runtime：使用迁移产物部署一个临时 Runtime，用于执行评测用例。
4. 执行用例：逐条向临时 Runtime 发送评测用例，记录输出和 Runtime 原始数据。
5. 执行评测分析：在同一个可恢复的 Codex 线程中，按维度对每个用例的迁移前后行为进行评分，生成证据和差距说明。
6. 生成评测报告：汇总各维度评分、证据覆盖率和执行结果，生成 HTML 报告。

​

评测报告

​

评测状态

​

添加技能

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

​

智能生成智能体配置

​

生成结果的结构

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

​

未决项

​

使用步骤

​

权限与失败处理

​

添加远程智能体

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

​

排查远程智能体问题

​

配置记忆

​

配置知识库

​

添加代码执行工具

​

查看子智能体移交

​

对话调用链路与问题反馈

​

查看调用链路

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

​

问题反馈

​

导出会话

​

使用智能搜索

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

​

部署网络模式

​

管理智能体

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

​

管理草稿

​

端云接力到云端继续执行

codex plugin marketplace add volcengine/veadk-python \
  --sparse .agents/plugins \
  --sparse plugins/agentkit-studio \
  && codex plugin add agentkit-studio@veadk-python

​

端云接力环境变量

​

更新已部署的智能体

​

更新模式

​

旧版 Runtime 恢复

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

​

更新安全校验

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

​

通过 GitHub 交付智能体

​

交付模式

​

配置 GitHub 交付

​

部署时挂载持续交付

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

​

版本管理与回退

​

使用命令行同步源码

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

​

查看接入方式

​

支持的协议

​

鉴权方式与 API Key

​

调用示例

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"))

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())

​

浏览智能体

​

选择云端 Runtime

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

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

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

​

新会话工作区

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

​

智能体对话与内置智能体

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

​

查看运行时实例日志

​

本地配置

export SANDBOX_CHAT_CODEX="your-chat-code-env-tool-id"

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

​

Codex 会话控件

​

快捷命令

​

模型与 Skill

​

工作空间

​

权限

​

操作审批

​

终端与浏览器

​

状态与历史

​

技能定制

​

技能生成

​

技能优化

​

视频创作

​

使用方式

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

​

视频任务模式

​

生成参数

​

生成流程

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

​

参考素材与持久化存储

​

管理会话能力

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

​

自动评测与优化反馈

​

评测集创建

​

自动评测

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

​

优化建议

​

标注回复为 Bad Case

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

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

​

查看评测案例

​

自动化集成

​

配置 Coding Agents

​

模板项目导入

​

AgentKit Runtime 持续交付

​

PR 自动评审

​

管理员配置

​

使用流程

1. 管理员完成上述配置后，Studio 的「PR 自动评审」页面显示 GitHub App 的安装链接。
2. 点击「安装 GitHub App」，将 App 安装到目标 GitHub 仓库。安装后 Studio 自动加载已安装的仓库列表。
3. 在仓库列表中为需要自动评审的仓库开启评审开关。仅开启评审的仓库会响应 GitHub webhook 自动触发评审。
4. 后续目标仓库中创建或更新的非草稿 PR 会自动触发 Sandbox 评审任务，评审完成后结果发布为对应 PR 的 GitHub Review。
5. 也可以在「立刻评审」区域输入已启用仓库的 PR URL，手动发起一次评审。

​

评审记录

​

飞书机器人

​

网站集成

​

使用前提

• 已部署至少一个 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 名称、智能体名称和创建时间。

​

嵌入聊天窗口

<script async src="https://your-studio-url/website-integration.js" data-token="wsi_xxx"></script>

​

工作方式

​

删除网站集成

​

资源库

​

技能库

​

前提条件

​

技能发布存储

​

管理技能空间

​

管理技能

​

通过 Dev Sandbox 生成技能

生成方案

生成流程

优化已有技能

​

技能审核工作流

​

自动技能评测

​

审核中心

​

智能体公开审核

​

知识库

​

创建知识库

​

管理知识库

​

添加知识数据

​

产物

​

管理产物

​

依赖

​

定时任务

​

创建与编辑任务

​

管理任务

​

执行历史

​

执行机制

​

veadk studio 参数

​

部署到 VeFaaS

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

​

IAM 权限预检

veadk studio deploy \
  --vefaas-app-name "veadk-studio" \
  --region "cn-beijing" \
  --precheck-only

​

应用内更新

veadk studio deploy \
  --vefaas-app-name "veadk-studio" \
  --studio-update-bucket "custom-studio-releases" \
  --studio-update-prefix "veadk/studio/main"

​

部署参数

​

部署到 VeStack

​

何时使用

• 部署环境为 VeStack 或私有云，不支持公有云 VeFaaS Application 接口。
• 需要 Studio 使用 IAM Role 绑定的临时凭证（STS）访问混合云 AgentKit OpenAPI，而不在镜像或函数环境中保存长期 AK/SK。
• 需要为每个沙箱会话创建独立的 AgentKit Tool，以实现磁盘持久化和会话隔离。

​

构建镜像

docker build --platform linux/amd64 \
  -f docker/Dockerfile.vestack \
  --build-arg PYTHON_IMAGE=<reachable-python-3.12-image> \
  -t <vestack-registry>/<namespace>/veadk-studio:<tag> .

python -m pip download --no-deps \
  'openviking-sdk>=0.1.3' 'fastmcp==3.4.7' 'fastmcp-slim==3.4.7' \
  -d docker/vendor

​

部署命令

export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

veadk studio deploy \
  --deploy-target vestack \
  --provider volcengine \
  --vefaas-app-name "veadk-studio" \
  --region "cn-beijing" \
  --project "default" \
  --image "<vestack-registry>/<namespace>/veadk-studio:<tag>" \
  --public-domain "studio.example.com" \
  --vestack-openapi-url "https://openapi.example.com" \
  --vestack-agentkit-region "e70" \
  --vestack-apig-cluster-id "<cluster-id>" \
  --super-admin "admin@example.com"

1. 验证 --deploy-target 为 vestack 时 --provider 必须为 volcengine。
2. 解析 --vestack-openapi-url 并设置 VeFaaS、APIG、IAM 和 Identity 的 OpenAPI Host 与 Scheme 环境变量，使 SDK 请求指向 VeStack 控制面。
3. 创建或复用 VeIdentity 用户池与 Web 客户端（除非通过 --user-pool-id 与 --allowed-client-id 指定已有资源）。
4. 创建或复用 Studio 专用 IAM Role 和自定义 Policy；未指定 --iam-role 时自动创建。VeStack 环境中部分公有云系统 Policy 可能不可用，此时跳过缺失的系统 Policy 并继续使用已校验的自定义 Policy。
5. 创建或更新 VeFaaS 镜像函数，设置镜像地址、启动命令、端口和 Role，并传入非敏感环境变量。
6. 发布函数并等待发布完成。
7. 创建或复用 APIG Gateway、Service、Upstream 和 Host Route，将独立域名转发到函数。
8. 向 VeIdentity 用户池客户端注册回调地址。
9. 输出访问端点、函数 ID、网关 ID、服务 ID、上游 ID、路由 ID 和 IAM Role。

✅ VeStack Studio Function deployed: http://studio.example.com:<port>
   function id: <function-id>
   gateway id: <gateway-id>
   service id: <service-id>
   upstream id: <upstream-id>
   route id: <route-id>
   IAM role: <role-trn>

​

每会话独立 Tool

​

OpenAPI 端点覆盖

​

VeStack 部署参数

​

Studio BFF 动态工具

​

会话沙箱环境

​

分支对比

​

AgentKit CLI 终端

​

Studio Sandbox 代码项目

​

创建与打开项目

​

持久化与恢复

​

开发环境

• 独立的 VeADK Python 环境，包含 veadk-python 和 agentkit 命令
• code-server（VS Code 浏览器版本）与 Jupyter
• Python 语法高亮、BasedPyright 代码补全、Ruff 格式化
• 每个项目自动创建 Bash 和 Codex 两个集成终端，工作目录为当前项目
• Dark Modern 主题，代码和终端使用 Maple Mono 字体

​

项目模板

​

开发者资源

• 相关链接：VeADK 文档、AgentKit CLI 文档、AgentKit 平台文档与 AgentKit 控制台的快捷入口。
• 最佳实践：使用 VeADK 和 AgentKit CLI 开发并部署智能体的参考文章。
• Showcases：基于 VeADK 构建的应用案例，涵盖多智能体研究助手、多模态内容分析、智能客服工作台、联网搜索智能体和 A2UI 交互应用。