本文介绍如何在火山方舟（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 模板，完成沙箱实例调度、任务转发和结果回传。

整体调用链路如下：

使用限制

本文操作仅面向火山方舟 Ark / Claude Platform 中的 Managed Agent 场景。

Self-hosted Environment 只在方舟侧创建 Environment 与 Work Queue，镜像、依赖、环境变量、网络访问策略和实例运行由用户侧或企业侧环境承载。

Secure Skill 和真实 Skill 必须保持语义一致。方舟侧 Agent 识别到的是 Secure Skill，实际执行发生在 AgentKit Sandbox 内的真实 Skill。

前提条件

已开通火山方舟 Managed Agent，该服务开通后可用，若未开通请前访问开通管理页面，切换到 Managed Agents 页签开通服务。

已开通 AgentKit 服务。若未开通，请登录 AgentKit控制台，根据系统引导开通产品。

已准备可用的火山方舟 API Key、AgentKit 访问凭证和 AgentKit Skill Space。

准备工作

安装 AgentKit CLI

执行以下命令安装 AgentKit CLI：

安装完成后，执行以下命令确认版本，建议使用 0.52.9 或更高版本。

准备认证信息

上传真实 Skill 到 AgentKit 前，配置火山引擎访问凭证。

export VOLCENGINE_ACCESS_KEY="<ak>"
export VOLCENGINE_SECRET_KEY="<sk>"

上传 Secure Skill 到方舟 Managed Agent 前，需要准备方舟 API Key。

export ARK_API_KEY="<ark-api-key>"

操作步骤

步骤一：生成并上传 Skills

生成 Secure Skill。

如果 Skill 位于本地目录，请执行如下命令。

agentkit skills secure <skills-dir>

示例：

agentkit skills secure /Users/bytedance/work/wm_project/agentkit/wm_test_08****/veadk-skills

命令执行完成后，会在原 Skill 目录旁生成对应的 *-secure 目录。该目录中包含可上传到方舟 Managed Agent 的 Secure Skill。

如果 Skill 位于 GitHub 仓库，执行如下命令。

agentkit skills secure <skills-github-url>

示例：

agentkit skills secure https://github.com/anbeime/skill/tree/main/skills/antinet-doc-parse

执行以下命令将上传 Secure Skill 到方舟 Managed Agent。

agentkit skills upload <skills-dir-secure> \
--source ark_ma \
--api-key "$ARK_API_KEY"

示例：

agentkit skills upload /Users/my-skills-secure \
--source ark_ma \
--api-key "$ARK_API_KEY"

上传完成后，可在方舟控制台的 Managed Agent Skills 页面查看该 Secure Skill。

执行以下命令将真实 Skill 上传到 AgentKit Skill Space。

agentkit skills upload <skills-dir> \
--source agentkit \
--skill-space-id <skill-space-id> \
--region cn-beijing

示例：

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 仓库，也可以直接上传仓库地址：

agentkit skills upload https://github.com/anbeime/skill/tree/main/skills/antinet-doc-parse \
--source agentkit \
--skill-space-id <skill-space-id> \
--region cn-beijing

步骤二：在方舟创建 Self-hosted Environment

登录火山方舟控制台，在左侧导航单击进入 Managed Agents。

在 Managed Agents 左侧单击“Environments”，单击“创建 Environment”按钮。

配置参数，将“运行方式”设置为 Self-hosted，返回记录创建完成后的 Environment ID，后续配置 Runtime 时需要使用。

步骤三：创建关联 Secure Skill 的 Agent

在 Managed Agents 左侧选择 Agents，创建或编辑 Agent。

在 Agent 能力扩展的 Skills 区域，选择已上传的 Secure Skill，然后保存 Agent 配置。

Agent 创建完成后，记录 Agent ID。后续创建 Session 时，需要选择该 Agent 以及对应的 Self-hosted Environment。

步骤四：创建 AgentKit Sandbox 模板

前往 AgentKit 控制台，创建自定义 Sandbox 模板，用于承载真实 Skill 执行环境。

参考下表配置必要参数，其他参数按需配置。

配置项	推荐值	说明
基础配置
类型	自定义	使用自定义容器镜像。
镜像	使用自定义镜像，自定义镜像地址：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

配置完成后，记录 Sandbox 模板 ID。后续创建 AgentKit Runtime 时，需要通过该 ID 指定 Runtime 使用的 Sandbox 模板。

步骤五：创建 AgentKit Runtime

在 AgentKit 控制台，创建智能体。AgentKit Runtime 负责监听方舟 Self-hosted Environment 的任务，并调度 AgentKit Sandbox 执行真实 Skill。

参考下表配置沙箱模板必要参数，其他参数按需配置。

配置项	推荐值	说明
基础配置
镜像	使用自定义镜像，自定义镜像地址：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。

创建 Runtime 后，确认实例处于运行状态，并确认日志中没有认证、网络或沙箱模板加载错误。

步骤六：创建 Session 并调用 Skill

返回火山方舟控制台 Managed Agents 平台，进入 Sessions 页面，单击“创建 Session”按钮。

选择已关联 Secure Skill 的 Agent、已配置 Runtime 监听的 Self-hosted Environment，并在 Session 中输入需要调用 Skill 的用户请求。

执行过程中，方舟 Managed Agent 会触发 Secure Skill。Secure Skill 使用 A2A 调用将任务提交到 AgentKit Sandbox，并周期性轮询任务状态。

Secure Skill 的典型执行逻辑如下：

python /home/gem/veadk_skills/scripts/invoke.py \
--prompt "<用户请求>" \
--source "<skill-name>"

提交成功后会返回任务 ID：

{
"ok": true,
"id": "task-xxx"
}

随后 Secure Skill 轮询任务状态：

python /home/gem/veadk_skills/scripts/poll.py \
--id "task-xxx"

状态处理规则如下：

状态	处理方式
working	读取 progress 字段，并将当前进展返回给用户。
completed	读取 result 字段，并将最终结果返回给用户。
failed	读取错误信息，并将失败原因返回给用户。

验证结果

常规验证

完成配置后，建议按以下顺序验证：

在方舟控制台确认 Secure Skill 已上传并可被 Agent 选择。

在 AgentKit 控制台确认真实 Skill 已上传到目标 Skill Space。

在 AgentKit Sandbox 模板中确认镜像、启动命令、端口和 SKILL_SPACE_ID 配置正确。

在 AgentKit Runtime 中确认实例运行正常，且环境变量完整。

在方舟 Session 中发起一次真实 Skill 调用，确认可以看到任务提交、进度轮询和最终结果。

在 AgentKit Sandbox 实例管理或日志页面确认真实 Skill 被实际执行。

Skill 可见性验证

可以执行真实 skill 调用，但尝试打印出 skill 原文时，会提示无权访问。

常见问题

方舟 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 模板中的容器镜像、启动命令和监听端口。推荐配置如下：

Skill 调用一直处于执行中

请检查 Sandbox 内 A2A Agent 是否正常返回任务状态，并查看 poll.py 返回内容。若任务仍在执行，Secure Skill 应持续读取 progress 字段并向用户反馈当前进展；若任务失败，应返回 failed 状态和错误信息。