部署到 AgentKit

VeADK 可以把本地智能体部署为 AgentKit Runtime，并通过统一的 AgentKit 应用组件提供对话接口、健康检查、智能体拓扑、内置 Web UI、短期会话默认配置和可选的飞书生命周期。

前置条件

已安装 veadk-python；
已配置目标云服务商的访问凭据和模型凭据；
项目包含可导入的 root_agent；
不要把 .env、API Key 或访问凭据提交到代码仓库。

部署会创建或更新云端 Runtime、构建和镜像资源，并可能产生费用。发布前确认云账号、地域、访问鉴权和会话存储。默认内存会话会随进程退出丢失；多实例部署应配置持久化会话

创建应用

Studio 生成的项目会调用 create_agentkit_app。手动创建项目时也可以使用相同入口：

app.py

from veadk import Agent
from veadk.integrations.agentkit import create_agentkit_app, run_agentkit_app

root_agent = Agent(name="customer_support", instruction="Answer support questions clearly.")
app = create_agentkit_app(root_agent, {root_agent.name: "Customer support"})

if __name__ == "__main__":
    run_agentkit_app(app, host="127.0.0.1", port=8000)

应用会提供 AgentKit 对话接口以及以下公共端点：

端点	作用
`/ping`	健康检查。
`/web/agent-info/{app_name}`	查询智能体的名称、描述、模型、系统提示词、子智能体、工具、技能与已挂载组件。
`/web/agent-graph`	查询智能体拓扑；每个节点包含技能、组件、路径与是否可在对话中选择。
`/`	访问内置 Web UI。

保存为 app.py，运行 python app.py，另开终端执行 curl --fail http://127.0.0.1:8000/ping，应得到 {"status":"ok"}。这是应用健康检查，不证明模型、工具和持久化服务均已连通；部署前还需发送一次实际请求。后续示例为同一文件的替代配置，复用上面定义的 root_agent

Runtime 身份绑定

create_agentkit_app 接受可选的 identity 参数，用于将 AgentKit Runtime 身份边界传递给应用。传入后，AgentKit 会在 VeADK 智能体或工具代码执行前，验证并绑定入站用户身份。不传入 identity 时，应用行为与此前一致。

使用 identity 参数需要 agentkit-sdk-python>=0.8.2。安装版本较低时，传入 identity 会报错，请先升级 AgentKit SDK。

VeADK 将 /ping 健康检查端点排除在身份绑定之外，该端点始终返回 {"status": "ok"}；其余业务和内省端点均纳入身份验证范围。

app.py

from agentkit.identity import RuntimeIdentity
from veadk import Agent

root_agent = Agent(name="customer_support", instruction="Answer support questions clearly.")
from veadk.integrations.agentkit import create_agentkit_app

app = create_agentkit_app(
    root_agent,
    {root_agent.name: "客户支持"},
    identity=RuntimeIdentity(),
)

动态 A2A 运行接口

create_agentkit_app 构建的应用覆盖标准 AgentKit 运行接口（/run、/run_sse、/invoke），使其支持动态 A2A 智能体发现。当智能体通过 REGISTRY_SPACE_ID 等环境变量配置了 AgentKit 智能体中心后，运行接口会根据用户输入从中心动态发现匹配的远程智能体，并在当前轮次中将其作为可调用工具使用。未配置智能体中心时，运行接口行为与标准 AgentKit 运行接口一致。

运行接口在指定会话不存在时会自动创建会话，不再返回 404。

Studio BFF 动态工具

Studio 可以将本地或内网工具通过反向通道暴露给兼容的 AgentKit Runtime，而无需将 BFF 的公网地址暴露给 Runtime。工具目录与执行器始终保留在 Studio BFF 侧，Runtime 不接触执行器实现或凭证。在 Runtime 侧通过 create_agentkit_app(..., enable_studio_tools=True) 挂载一个通用的 StudioExternalToolset。该 Toolset 不包含任何具体执行器，且对智能体内省不可见。在 Studio-channel 运行期间，仅提供该次运行明确选中的工具；普通 /run_sse 请求看到空快照。未启用该选项（默认）时，Runtime 对外声明 enabled=false，不挂载 Toolset 或工具通道执行端点。

当根智能体为工作流智能体（SequentialAgent、ParallelAgent 或 LoopAgent）时，即使传入 enable_studio_tools=True，该选项也会被自动关闭。工作流根智能体不执行工具调用，因此无需挂载 Studio BFF 动态工具宿主。

此前版本的会话级能力叠加接口（/harness/capabilities/tools、/harness/apps/{app_name}/users/{user_id}/sessions/{session_id}/capabilities 和 /harness/run_sse）已移除，由 Studio BFF 动态工具机制替代。

何时使用

需要在不重新部署 Runtime 的前提下，为单个 Studio 会话临时启用额外工具。
需要将工具代码和凭证保留在 Studio BFF 侧，不暴露给 Runtime。

工作机制

Studio BFF 为每次远程 run_sse 请求首先尝试通过出站 WSS 连接到 /harness/studio-channel/v1。如果公共网关不支持 WebSocket Upgrade，则自动回退到 HTTP/SSE 下行流加上 HTTP 工具结果回传。BFF 发布当前工具目录，在本地执行 tool.call 消息，并返回 tool.result，不暴露 BFF 端点。Runtime 看到的是普通工具，但既不接收执行器实现，也不接收其凭证。在 Studio 界面中，兼容的远程 Runtime 的智能体信息栏会在智能体静态工具下方显示「在此对话中添加 Studio 工具」。新会话默认禁用所有 Studio 工具；浏览器在每次 Runtime 运行时发送显式的 platform_tools 列表，空列表或省略时使用普通 /run_sse 路径。BFF 验证提交的工具 ID，并为该次运行冻结一个不可变的目录与执行器快照，因此同时使用的不同用户和会话无法互相添加工具。 Studio 提供内置工具目录，并在每次运行中使用当前会话选择的工具。工具生成的文件通过 Studio 的媒体或产物存储提供下载；访问和保留策略由 Studio 配置决定。添加或修改工具后，需要确保运行该工具的 Studio 服务已加载对应配置

使用示例

app.py

from veadk import Agent

root_agent = Agent(name="customer_support", instruction="Answer support questions clearly.")
from veadk.integrations.agentkit import create_agentkit_app

app = create_agentkit_app(
    root_agent,
    {root_agent.name: "客户支持"},
    enable_studio_tools=True,
)

参数

参数	类型	默认值	说明
`enable_studio_tools`	`bool`	`False`	是否在 Runtime 侧挂载 Studio BFF 动态工具的通用宿主。启用后挂载 `StudioExternalToolset`，在 Studio-channel 运行期间通过反向通道接收工具目录并执行工具调用。根智能体为工作流智能体（`SequentialAgent`、`ParallelAgent`、`LoopAgent`）时自动关闭，工作流根智能体不执行工具调用。

限制

HTTP/SSE 回退模式目前要求 Runtime 仅有一个实例，使下行流和结果回传到达同一进程。
工具执行器和凭证始终保留在 Studio BFF 侧，不会下发到 Runtime 或浏览器。

Studio BFF 动态路由

兼容的 Runtime 还可以在不加载 Python 处理器的情况下暴露 Studio 专属的 HTTP 路由。在 Runtime 侧通过 create_agentkit_app(..., enable_studio_routes=True) 启用，并在 Studio 侧设置环境变量 VEADK_STUDIO_ROUTE_CHANNEL=skill-catalog（demo 仍作为兼容别名）。启用后，Studio BFF 维护一条独立的持久反向路由通道，并发布以下 Studio 专属只读路由：

端点	方法	作用
`/harness/skills/findskill`	`GET`	搜索公域 Skill Hub 中的技能。
`/harness/skills/spaces`	`GET`	列出当前账号可见的 AgentKit Skill 中心。
`/harness/skills/spaces/{space_id}/skills`	`GET`	列出指定 Skill 中心内的技能。

未启用动态路由的 Runtime 保留其原生技能目录处理器。启用的 Runtime 将这三个只读查询处理器交给 Studio BFF 通过反向通道执行：请求仍经由 Runtime URL 进入，其动态分发器发出 route.call，本地 BFF 执行处理器后返回 route.result 作为 Runtime HTTP 响应。

使用示例

app.py

from veadk import Agent

root_agent = Agent(name="customer_support", instruction="Answer support questions clearly.")
from veadk.integrations.agentkit import create_agentkit_app

app = create_agentkit_app(
    root_agent,
    {root_agent.name: "客户支持"},
    enable_studio_routes=True,
)

参数

参数	类型	默认值	说明
`enable_studio_routes`	`bool`	`False`	是否在 Runtime 侧挂载 Studio BFF 动态 HTTP 路由的通用宿主。启用后，三个只读技能目录路由由 Studio BFF 通过反向通道处理。

环境变量	默认值	说明
`VEADK_STUDIO_ROUTE_CHANNEL`	—	Studio 反向路由通道模式。设为 `skill-catalog` 或 `demo` 启用技能目录路由。未设置时 Studio 不建立反向路由通道。

限制

WSS 连接优先；不支持的网关自动使用长连接 HTTP/SSE 下行流加 HTTP 结果回传。
当前实现为单实例：持久流和任意路由请求必须到达同一 Runtime 进程。
BFF 断开连接时，已知的 Studio 专属路由返回 HTTP 503；智能体运行不受影响。

初始化与部署

在项目目录中运行：

veadk agentkit init
veadk agentkit config
veadk agentkit launch

部署完成后检查状态并调用 Runtime：

veadk agentkit status
veadk agentkit invoke "介绍你的能力"

veadk agentkit 调用随 Python AgentKit SDK 安装的命令，其参数和项目配置随 SDK 版本变化；它不等同于独立安装的 Node.js AgentKit CLI。执行前分别检查 veadk agentkit --help 与对应子命令的 --help。使用独立 CLI 时遵循 AgentKit CLI 工作流，不要在同一项目中混用两套配置假设

销毁 Runtime 会删除云端运行资源。执行 veadk agentkit destroy 前，应确认项目、地域与 Runtime 标识无误，并保留需要的日志和数据。

应用参数

参数	类型	默认值	说明
`root_agent`	`BaseAgent`	`None`	与 app 二选一，指定根智能体
`display_names`	`Mapping[str, str]`	`None`	智能体技术名称到展示名称的映射
`app`	`App`	`None`	ADK 应用；保留应用插件
`agent_draft`	`Mapping`	`None`	用于只读编辑信息的脱敏草稿，不放置凭据
`enable_feishu`	`bool`	`False`	启动飞书渠道生命周期，使用 FEISHU_APP_ID 与 FEISHU_APP_SECRET
`enable_studio_tools`	`bool`	`False`	启用 Studio 会话动态工具；工作流根智能体自动关闭
`enable_studio_routes`	`bool`	`False`	将技能目录查询交由 Studio 处理
`identity`	`RuntimeIdentity`	`None`	可选请求身份绑定，需要兼容版本的 SDK
`harness_extension`	`HarnessExtension`	`None`	挂载已准备的扩展状态并在关闭应用时释放

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

前置条件

创建应用

Runtime 身份绑定

动态 A2A 运行接口

Studio BFF 动态工具

何时使用

工作机制

使用示例

参数

限制

Studio BFF 动态路由

使用示例

参数

限制

初始化与部署

应用参数

​前置条件

​创建应用

​Runtime 身份绑定

​动态 A2A 运行接口

​Studio BFF 动态工具

​何时使用

​工作机制

​使用示例

​参数

​限制

​Studio BFF 动态路由

​使用示例

​参数

​限制

​初始化与部署

​应用参数

前置条件

创建应用

Runtime 身份绑定

动态 A2A 运行接口

Studio BFF 动态工具

何时使用

工作机制

使用示例

参数

限制

Studio BFF 动态路由

使用示例

参数

限制

初始化与部署

应用参数