文档中心

火山方舟

自托管环境

配置并运行自托管环境

本文介绍如何从零配置自托管环境（Self-hosted Environment），选择 Go、Python 或 Java SDK 启动 Worker，并完成一次完整的 Session 工具执行。

你将完成什么

在控制台创建 self_hosted 类型的环境

为每个 Worker 配置独立的实例 ID

为 Worker 配置并安全保存 API Key

选择 Go、Python 或 Java SDK，在企业主机启动 Worker

创建绑定自托管环境的 Session

发送用户消息，让主 Agent 在企业主机执行 Bash 和文件工具

验证工具执行结果、Session 终态和 Worker 状态

核心概念

概念	说明
Environment	Agent 运行时配置，type 为 self_hosted 时表示自托管环境
Worker	企业部署的进程，轮询 Work Queue，并在企业 Sandbox 中执行主 Agent 的 bash、read、write、edit、glob 和 grep
Work Item	方舟为需要工具执行的 Session 生成的任务项，Work ID 与 Session ID 一致
Worker 实例 ID	标识认领和执行 Work 的 Worker 实例。Ack 与 Heartbeat 使用同一个非空 ID 时，原 Worker 可以恢复因心跳租约到期而停止的 Work
API Key	Worker 和业务应用调用方舟接口时使用的鉴权凭证。Worker 使用的 API Key 权限取决于所属账号、项目和凭证策略，不会自动限制为只能访问某个 Environment

工作流程

以下是自托管环境端到端的工作流程：

企业管理员创建自托管 Environment，并为 Worker 准备 API Key。

企业运维人员在企业主机启动 Worker，Worker 开始轮询 Work Queue。

业务应用使用业务 API Key 创建 Session，建立事件流后发送用户消息。

方舟控制面生成 Work Item，Worker 领取并 Ack。

主 Agent 调用 bash、read、write、edit、glob 或 grep 时，Worker 在企业 Sandbox 中执行并回传结果。

主 Agent 调用 Web、MCP 或多模态工具时，方舟完成执行；Agent 调用自定义工具时，业务应用完成执行。

工具结果驱动下一轮推理。

重复步骤 5-7，直到 Session 进入 idle 或终态。

Worker 完成 Work Item，继续轮询。

注意

自托管 Environment 不会把所有工具迁移到 Worker。企业 Sandbox 的文件和网络策略只约束 Worker 执行的六个工具，不约束方舟侧执行的 Web、MCP 和多模态工具。

前置条件

开始前，请确认以下条件已满足：

已开通 Managed Agents 服务，并已创建 Agent（参见快速入门）

准备一台企业管理的 Linux 主机或隔离容器，具备以下条件：

/bin/bash 可用

已选择一种 Ark Runtime SDK，并按对应仓库 README 准备运行环境：Go 、 Python 或 Java

Worker 主机能够通过出站 HTTPS 访问方舟 API（https://ark.cn-beijing.volces.com/api/v3），无需开放入站端口

业务应用所在主机已安装 curl 7.76 或更高版本，并已安装 jq

准备业务 API Key（用于创建 Session，由业务应用持有）

准备 Worker 使用的方舟 API Key，由 Worker 主机持有

注意

当前没有仅能访问指定 Environment 的独立 Worker 凭证。Worker 使用标准方舟 API Key 访问 Work Queue，实际权限取决于该 API Key 所属账号、项目和凭证策略。不要把 MA_ENVIRONMENT_ID 误认为鉴权范围限制。

建议为业务应用和 Worker 分配不同的 API Key，并分别保存在 Secret Manager 中。Worker API Key 的权限不会自动限制为单个 Environment。独立凭证便于单独轮换和吊销，但不能替代账号和项目级权限控制。

第 1 步：创建自托管环境

在控制台的 Environments 页面或使用 API 创建自托管环境。

使用 API 创建环境：

说明

自托管环境的 config 必须将 type 设为 self_hosted。依赖包（packages）、环境变量（env）、启动脚本（setup_script）和网络策略（networking）由企业自行管理，不在 Environment 配置中定义。

响应示例：

命令会从响应中读取 id，确认它以 env- 开头，再写入 ENVIRONMENT_ID。如果请求返回 HTTP 4xx/5xx、响应不是合法 JSON，或响应中没有有效 ID，后续命令不会执行。

第 2 步：配置 Worker API Key

为 Worker 准备一个可访问当前账号和项目中 Managed Agents 资源的方舟 API Key。API Key 的创建方法，详情请参见 API Key 管理。

注意

Worker 使用的是标准方舟 API Key，不是 Environment 专用凭证。不要假设该 Key 只能 Poll 或 Ack 当前 Environment 的 Work Item。应通过独立项目、独立 API Key、Secret Manager 和 Worker 侧网络策略限制风险范围。

在 Worker 主机上，把步骤 1 得到的 ENVIRONMENT_ID 写入 MA_ENVIRONMENT_ID，再配置 Worker API Key：

将 ARK_API_KEY 设置为 Worker 使用的方舟 API Key。SDK 会使用 MA_ENVIRONMENT_ID 定位 Work Queue，并在 Ack 和 Heartbeat 请求中使用 MA_WORKER_ID 标识当前 Worker。为每个 Worker 实例设置独立且稳定的非空 ID，不要让多个实例共享同一个 ID。

当 Work 因心跳租约到期进入 stopped 后，只有认领该 Work 的原 Worker 能携带相同的 MA_WORKER_ID 通过 Heartbeat 将其直接恢复为 active。该过程不会将 Work 重新排队，也不会转交其他 Worker。未设置 Worker ID，或 Work 因其他原因停止时，不能通过 Heartbeat 恢复。

第 3 步：准备 Worker 主机

在企业 Linux 主机上创建工作目录，并选择一种 SDK 安装。各 SDK 的运行环境和安装方式以官方仓库 README 为准：

Ark Runtime Go SDK

Ark Runtime Python SDK

Ark Runtime Java SDK

该固定输入用于步骤 5 的首次工具调用。test 返回状态码 0，表示文件已创建且内容非空。

Python

Java

按照 Go SDK 仓库 README 安装：

说明

Self-hosted Worker 从 Ark Runtime Go SDK v0.5.0 开始提供。如果提示 arkruntime/lib/environments 包不存在，请升级到最新稳定版。

检查以下条件：

/bin/bash 可用且 Worker 进程有执行权限

出站 HTTPS 可达 https://ark.cn-beijing.volces.com/api/v3

准备 Agent 需要访问的企业文件或内部服务

第 4 步：启动常驻 Worker

使用 SDK 启动 EnvironmentWorker。以下示例会持续 Poll Work Queue，领取 Work Item 后在 MA_WORKDIR 下为每个 Session 创建独立工作目录。

Python

Java

创建 main.go：

启动 Worker：

Python

Java

期望日志输出：

EnvironmentWorker 会持续 Poll Work Queue，队列为空时保持等待，不产生 Session。回到控制台 Environment 详情页，Worker 连接状态应显示为"在线"。

注意

如果 Worker 仍显示"未连接"，优先检查：

MA_ENVIRONMENT_ID 是否正确

Worker 主机上的 ARK_API_KEY 是否为当前账号和项目下有效的方舟 API Key

如设置了 ARK_BASE_URL，确认地址与当前方舟地域一致

Worker 主机系统时间是否准确（偏差过大导致签名失败）

出站 HTTPS 是否可达 https://ark.cn-beijing.volces.com/api/v3

第 5 步：创建 Session，建立事件流并发送任务

5.1 创建 Session

回到步骤 1 使用的业务应用终端，用业务 API Key 创建 Session。不要在生产环境复用 Worker API Key：

将 <AGENT_ID> 替换为已创建的 Agent ID。命令直接使用步骤 1 保存的 ENVIRONMENT_ID，并把 Session ID 写入 SESSION_ID。请求失败或响应中没有有效 ID 时，后续命令不会执行。

响应示例：

5.2 订阅 Session 事件流

在另一个终端中，通过流式获取会话事件建立 SSE 连接：

等待服务端返回 : ready 后，再发送用户消息。SSE 只推送连接建立后产生的事件；如果先发送消息，业务应用会遗漏已产生的事件。

5.3 发送首个事件启动 Agent

仅创建 Session 不会触发任务。通过发送会话事件提交第一条 user.message 事件后，方舟才会生成 Work Item 并将其写入自托管 Environment 的 Work Queue：

说明

发送消息后，Session 从 idle 进入 running，方舟为本轮执行生成 Work Item 并写入 Environment 的 Work Queue。业务应用不直接创建 Work Item，也不调用 Work API。

第 6 步：验证执行结果

6.1 Worker 侧

Worker 日志中应看到以下关键事件：

确认 /workspace/output.md 已生成，内容符合预期。

6.2 业务应用侧

在步骤 5.2 建立的 SSE 连接中，确认收到以下事件：

6.3 控制台侧

在 Environment 详情页确认：

页面	预期结果
概览	Worker 在线，执行期间 running 数量增加，结束后回落
Work Items	可按 Session ID 找到本轮 Work Item。正常完成时，状态依次变为 queued、starting、active 和 stopped；原 Worker 恢复因租约到期而停止的 Work 时，状态从 stopped 直接变为 active

生产部署方式

常驻 Worker

适用于 VM、独立容器或已有隔离节点直接执行。EnvironmentWorker.run() / EnvironmentWorker.Run() 管理完整生命周期：Poll、Ack、Heartbeat、企业侧工具执行、结果回传和 Work Complete。

需要扩容时，优先启动多个 Worker 进程或 Pod，并为每个实例设置独立的 MA_WORKER_ID。不要让多个 Worker 共享同一个 Session 工作目录。

每 Session 独立 Sandbox

适用于 Kubernetes 每 Session 一个 Pod。Poller 负责领取 Work Item 并创建 Pod，Pod 内调用 SDK 的 HandleItem / handle_item 负责该 Work Item 的完整生命周期。

Poller 在创建 Pod 前从 Work Item 中读取 Work ID，生成 MA_WORKER_ID，并随 MA_WORK_ID、MA_ENVIRONMENT_ID 和 MA_SESSION_ID 一起注入 Pod。Pod 进程启动时必须校验 MA_WORKER_ID 非空，并把它传给 EnvironmentWorker。同一个 Work 的 Pod 进程重启或 Pod 重建时，继续使用原来的 MA_WORKER_ID；只有新的 Work 才生成新的 Worker ID。这样 Ack、Heartbeat 和租约恢复会落在同一个 Worker 身份上。

注意

Worker 使用的 API Key 应通过 Kubernetes Secret、Secret Manager 或等价机制挂载，不能明文写入 Pod Spec、镜像、工作目录或日志。Worker 在执行 bash 等 Agent 工具前，应清除包含凭证的环境变量。

运行与排障

现象	检查项	处理方式
Worker 未连接	API Key、Environment ID、网络	检查 Worker 主机上的 ARK_API_KEY 是否有效且能访问当前账号和项目，确认出站 HTTPS 可达
Work 长时间排队	Worker 在线状态、Worker 实例数量	确认 Worker 在线，必要时增加 Worker 实例
Heartbeat 返回 412	MA_WORKER_ID、expected_last_heartbeat、Work 最新状态	确认 Ack 与 Heartbeat 使用同一个 Worker ID，并使用上一次响应中的 last_heartbeat 继续续租
Work 因租约到期停止	stop_reason、MA_WORKER_ID、lease_extended	原 Worker 使用相同 ID 恢复心跳；响应为 active 且 lease_extended=true 时继续执行，否则停止当前任务并释放资源
工具重复执行	Worker 执行账本、工作目录是否持久化	检查相同 Tool Call ID 是否直接复用已有结果。服务端对 Tool Result 的幂等处理只作用于结果回传，不能阻止 Worker 再次执行本地工具。执行状态无法确认时，不要自动重试有副作用的操作
Session 无结果	Work 与 Session Events 分别检查	确认 Work 已被领取且处于 active，同时检查 Events 是否有错误事件

清理资源

确认产物已转存后，按依赖顺序清理：

警告

只删除本次创建、且记录了精确 ID 的资源。切勿按名称模糊匹配批量删除：企业账号下资源可能被多人共享，误删不可恢复。

最近更新时间：2026.10.28 19:53:17

这个页面对您有帮助吗？

有用

无用