本文介绍如何在火山方舟（Ark）中接入 **AgentKit Self\-hosted Skills Sandbox**，实现在方舟 Managed Agent 中调用 Secure Skill，由 AgentKit Runtime 调度自托管沙箱执行真实 Skill，并将执行进度和结果返回给方舟会话。 ## 背景信息 AgentKit Self\-hosted Skills Sandbox 适用于需要在企业自有运行环境中执行 Skill 的场景。该方案将“方舟侧可见的 Skill 描述与调用入口”和“企业侧真实 Skill 执行环境”解耦： * 方舟 Managed Agent 只关联 Secure Skill。Secure Skill 是轻量级 Skill Wrapper，负责提交任务和轮询结果，不包含真实业务执行逻辑。 * AgentKit Skill Sandbox 加载并执行真实 Skill。真实 Skill 可以包含完整的 SKILL.md、references/、scripts/、依赖和运行时资源。 * AgentKit Runtime 负责连接方舟 Environment 与 AgentKit Sandbox 模板，完成沙箱实例调度、任务转发和结果回传。整体调用链路如下： ```Plain Text 用户 / 业务应用 -> 火山方舟 Managed Agent -> Secure Skill -> 方舟 Self-hosted Environment -> AgentKit Runtime -> AgentKit Skills Sandbox -> Real Skill 执行并返回结果 ``` ## 使用限制 * 本文操作仅面向火山方舟 Ark / Claude Platform 中的 Managed Agent 场景。 * Self\-hosted Environment 只在方舟侧创建 Environment 与 Work Queue，镜像、依赖、环境变量、网络访问策略和实例运行由用户侧或企业侧环境承载。 * Secure Skill 和真实 Skill 必须保持语义一致。方舟侧 Agent 识别到的是 Secure Skill，实际执行发生在 AgentKit Sandbox 内的真实 Skill。 ## 前提条件 * 已开通火山方舟 Managed Agent，该服务开通后可用，若未开通请前访问 [开通管理页面](https://console.volcengine.com/ark/region:cn-beijing/openManagement)，切换到 **Managed Agents** 页签开通服务。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0163aaf142b89af369ac9fb1130a0c9c.png) * 已开通 AgentKit 服务。若未开通，请登录 [AgentKit控制台](https://console.volcengine.com/AgentKit)，根据系统引导开通产品。 * 已准备可用的火山方舟 API Key、AgentKit 访问凭证和 AgentKit Skill Space。 ## 准备工作 ### 安装 AgentKit CLI 执行以下命令安装 AgentKit CLI： ```Bash wget -qO- https://agentkit-cli.tos-cn-beijing.volces.com/install.sh | sh ``` 安装完成后，执行以下命令确认版本，建议使用 **0.52.9** 或更高版本。 ```Bash agentkit -v ``` ### 准备认证信息 * 上传真实 Skill 到 AgentKit 前，配置火山引擎访问凭证。 ```Bash export VOLCENGINE_ACCESS_KEY="" export VOLCENGINE_SECRET_KEY="" ``` * 上传 Secure Skill 到方舟 Managed Agent 前，需要准备方舟 API Key。 ```Bash export ARK_API_KEY="" ``` ## 操作步骤 ### 步骤一：生成并上传 Skills 1. 生成 Secure Skill。 * 如果 Skill 位于本地目录，请执行如下命令。 ```Bash agentkit skills secure ``` 示例： ```Bash agentkit skills secure /Users/bytedance/work/wm_project/agentkit/wm_test_08****/veadk-skills ``` 命令执行完成后，会在原 Skill 目录旁生成对应的 \*\-secure 目录。该目录中包含可上传到方舟 Managed Agent 的 Secure Skill。 * 如果 Skill 位于 GitHub 仓库，执行如下命令。 ```Bash agentkit skills secure ``` 示例： ```Bash agentkit skills secure https://github.com/anbeime/skill/tree/main/skills/antinet-doc-parse ``` 2. 执行以下命令将上传 Secure Skill 到方舟 Managed Agent。 ```Bash agentkit skills upload \ --source ark_ma \ --api-key "$ARK_API_KEY" ``` 示例： ```Bash agentkit skills upload /Users/my-skills-secure \ --source ark_ma \ --api-key "$ARK_API_KEY" ``` 上传完成后，可在方舟控制台的 Managed Agent Skills 页面查看该 Secure Skill。 3. 执行以下命令将真实 Skill 上传到 AgentKit Skill Space。 ```Bash agentkit skills upload \ --source agentkit \ --skill-space-id \ --region cn-beijing ``` 示例： ```Bash agentkit skills upload /Users/bytedance/work/wm_project/agentkit/wm_test_0831/veadk-skills \ --source agentkit \ --skill-space-id ss-yeu1bfxnggzhxa5qbrv7 \ --region cn-beijing ``` 如果真实 Skill 位于 GitHub 仓库，也可以直接上传仓库地址： ```Bash agentkit skills upload https://github.com/anbeime/skill/tree/main/skills/antinet-doc-parse \ --source agentkit \ --skill-space-id \ --region cn-beijing ``` ### 步骤二：在方舟创建 Self\-hosted Environment 1. 登录[火山方舟控制台](https://console.volcengine.com/ark)，在左侧导航单击进入 Managed Agents。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ebdc9c59d9272c80f77f99b182dd2f94.png) 2. 在 Managed Agents 左侧单击“Environments”，单击“创建 Environment”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_59d009a7c24375cdb58c39740bc3f92f.png) 3. 配置参数，将“运行方式”设置为 Self\-hosted，返回记录创建完成后的 Environment ID，后续配置 Runtime 时需要使用。 > **说明** > Self\-hosted Environment 创建后，火山方舟会创建对应的 Environment 与 Work Queue。您需要在 AgentKit Runtime 中配置该 Environment ID，使 Runtime 能够监听并处理来自方舟的任务。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2efa79b46091aaa8444f0444eb72c1fb.png) ### 步骤三：创建关联 Secure Skill 的 Agent 1. 在 Managed Agents 左侧选择 Agents，创建或编辑 Agent。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a23fb7c4c272b61938d0fd792f6c842c.png) 2. 在 Agent 能力扩展的 Skills 区域，选择已上传的 Secure Skill，然后保存 Agent 配置。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_21e04b1971fe90f6deb3b41ecc6d536f.png) 3. Agent 创建完成后，记录 Agent ID。后续创建 Session 时，需要选择该 Agent 以及对应的 Self\-hosted Environment。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_296b80ea596a645f5fa4d29617c9c399.png) ### 步骤四：创建 AgentKit Sandbox 模板 1. 前往 [AgentKit 控制台](https://console.volcengine.com/agentkit)，创建自定义 Sandbox 模板，用于承载真实 Skill 执行环境。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ec89e1dbe43f5c27255378eb21f6339f.png) 2. 参考下表配置必要参数，其他参数按需配置。 |**配置项** |**推荐值** |**说明** | |---|---|---| |**基础配置** ||| |类型 |自定义 |使用自定义容器镜像。 | |镜像 |使用自定义镜像，自定义镜像地址：enterprise\-public\-cn\-beijing.cr.volces.com/vefaas\-public/agentkit\-selfhostsandbox:tool\-ark\-skills\-0.0.2 |Skills Sandbox 镜像。 | |启动命令 |/opt/gem/run.sh |沙箱启动入口。 | |监听端口 |8080 |Sandbox 服务端口。 | |**高级配置** ||| |环境变量 |SKILL_SPACE_ID |用于存放真实 Skill 的 AgentKit Skill Space ID | ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1ea85554eb85aba618a9e8cac4d0ce6b.png) 3. 配置完成后，记录 Sandbox 模板 ID。后续创建 AgentKit Runtime 时，需要通过该 ID 指定 Runtime 使用的 Sandbox 模板。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_03af4f7bf0f5cee49cca216eca91175e.png) ### 步骤五：创建 AgentKit Runtime 1. 在 [AgentKit 控制台](https://console.volcengine.com/agentkit)，创建智能体。AgentKit Runtime 负责监听方舟 Self\-hosted Environment 的任务，并调度 AgentKit Sandbox 执行真实 Skill。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_7936d55b38f0d56cb4522868da9a408b.png) 2. 参考下表配置沙箱模板必要参数，其他参数按需配置。 |**配置项** |**推荐值** |**说明** | |---|---|---| |**基础配置** ||| |镜像 |使用自定义镜像，自定义镜像地址：enterprise\-public\-cn\-beijing.cr.volces.com/vefaas\-public/agentkit\-selfhostsandbox:runtime\-ark\-skills\-0.0.2 |创建 Runtime 使用的镜像。 | |监听端口 |8000 |Runtime 服务端口。 | |网络配置 |按企业网络要求配置 |Runtime 需要访问方舟 API 与 AgentKit Sandbox。 | |**高级配置** ||| |环境变量 |ARK_API_KEY |火山方舟 API Key。 | ||ARK_BASE_URL |方舟 API Base URL，例如 https://ark.cn\-beijing.volces.com/api/v3。 | ||MA_ENVIRONMENT_ID |方舟 Self\-hosted Environment ID。 | ||AGENTKIT_TOOL_ID |AgentKit Sandbox 模板 ID。 | 3. 创建 Runtime 后，确认实例处于运行状态，并确认日志中没有认证、网络或沙箱模板加载错误。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d92c107767d3d6330fbb11026f8f0997.png) ### 步骤六：创建 Session 并调用 Skill 1. 返回[火山方舟控制台](https://console.volcengine.com/ark) Managed Agents 平台，进入 Sessions 页面，单击“创建 Session”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_104acaa1aed5d4b24c780c9db5aa7979.png) 2. 选择已关联 Secure Skill 的 Agent、已配置 Runtime 监听的 Self\-hosted Environment，并在 Session 中输入需要调用 Skill 的用户请求。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_5d9f4da03e063aa2cf8913eb6857ee6a.png) 执行过程中，方舟 Managed Agent 会触发 Secure Skill。Secure Skill 使用 A2A 调用将任务提交到 AgentKit Sandbox，并周期性轮询任务状态。 Secure Skill 的典型执行逻辑如下： ```Bash python /home/gem/veadk_skills/scripts/invoke.py \ --prompt "<用户请求>" \ --source "" ``` 提交成功后会返回任务 ID： ```JSON { "ok": true, "id": "task-xxx" } ``` 随后 Secure Skill 轮询任务状态： ```Bash python /home/gem/veadk_skills/scripts/poll.py \ --id "task-xxx" ``` 状态处理规则如下： |**状态** |**处理方式** | |---|---| |working |读取 progress 字段，并将当前进展返回给用户。 | |completed |读取 result 字段，并将最终结果返回给用户。 | |failed |读取错误信息，并将失败原因返回给用户。 | ## 验证结果 ### 常规验证完成配置后，建议按以下顺序验证： 1. 在方舟控制台确认 Secure Skill 已上传并可被 Agent 选择。 2. 在 AgentKit 控制台确认真实 Skill 已上传到目标 Skill Space。 3. 在 AgentKit Sandbox 模板中确认镜像、启动命令、端口和 SKILL_SPACE_ID 配置正确。 4. 在 AgentKit Runtime 中确认实例运行正常，且环境变量完整。 5. 在方舟 Session 中发起一次真实 Skill 调用，确认可以看到任务提交、进度轮询和最终结果。 6. 在 AgentKit Sandbox 实例管理或日志页面确认真实 Skill 被实际执行。 ### Skill 可见性验证可以执行真实 skill 调用，但尝试打印出 skill 原文时，会提示无权访问。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c19848bee55ae312be51bc4a7b8af715.png) ## 常见问题 ### 方舟 Agent 能看到 Skill，但调用后没有真实执行通常是 Secure Skill 已上传到方舟，但真实 Skill 未上传到 AgentKit Skill Space，或 Sandbox 模板中的 SKILL_SPACE_ID 配置错误。 ### Runtime 没有处理方舟 Session 中的任务请检查 MA_ENVIRONMENT_ID 是否填写为方舟 Self\-hosted Environment ID，并确认 Runtime 可以访问方舟 API。还需要确认 ARK_API_KEY 与 ARK_BASE_URL 配置正确。 ### Sandbox 实例启动失败请检查 Sandbox 模板中的容器镜像、启动命令和监听端口。推荐配置如下： ```Plain Text 镜像：enterprise-public-cn-beijing.cr.volces.com/vefaas-public/agentkit-selfhostsandbox:tool-ark-skills-0.0.2 启动命令：/opt/gem/run.sh 监听端口：8080 ``` ### Skill 调用一直处于执行中请检查 Sandbox 内 A2A Agent 是否正常返回任务状态，并查看 poll.py 返回内容。若任务仍在执行，Secure Skill 应持续读取 progress 字段并向用户反馈当前进展；若任务失败，应返回 failed 状态和错误信息。