文档中心

火山方舟

自托管环境

自托管环境概述

本文介绍方舟 Managed Agents 自托管环境（Self-hosted Environment）的适用场景、工作原理和能力边界，帮助你判断是否应该选择自托管环境。

什么是自托管环境

自托管环境将 Agent 的工具执行、文件系统和网络放在企业自己的基础设施，而方舟继续托管模型推理、Agent 编排、Session 管理与事件流。

方舟负责：

模型推理与 Agent 编排

Session 生命周期管理

事件流持久化与实时推送

Work Queue 的生成与调度

企业负责：

部署 Worker 进程，轮询并执行 Work Item

提供 Sandbox 执行环境（容器、VM 或物理机）

管理文件系统、网络策略和内部工具访问

控制镜像、计算资源和审计

自托管环境继续使用方舟托管的 Agent 编排、Session 生命周期和事件协议，但执行面能力与云环境不同。自托管 Session 不支持通过 resources 挂载 Files、Memory Store 或 TOS 对象，也不能通过 Environment 配置依赖包、环境变量、网络策略和产物存储。相关输入、运行时配置与产物转存需要由企业在 Worker 与 Sandbox 中自行准备和管理。

适用场景

以下场景适合使用自托管环境：

敏感代码或文件不能进入平台云沙箱：数据合规要求企业代码、密钥或内部文件不离开企业控制范围。

Agent 需要访问企业内网 API、数据库或代码仓库：工具调用需要访问仅在企业内网可达的服务，无法通过公网暴露。

企业需要控制镜像、网络策略和计算资源：对 Agent 执行环境有定制化要求，需要指定操作系统、预装工具或网络白名单。

企业已有容器、Kubernetes 或 MicroVM 基础设施：希望复用现有集群调度、监控和日志体系。

不适用场景

以下场景不建议使用自托管环境：

希望零运维、按需自动拉起 Sandbox：云环境由方舟全托管，无需企业部署和维护 Worker。

不具备安全隔离工具执行的能力：自托管环境要求企业自行实现 Sandbox 隔离，否则 Agent 可能越权访问主机资源。

仅需调用少量外部业务函数：如果工具只是调用企业已有的 HTTP API，优先考虑 Custom Tool 或 MCP，无需部署 Worker。

与云环境的区别

维度	云环境	自托管环境
执行位置	方舟云沙箱	企业基础设施
Sandbox 生命周期	方舟管理	企业管理
文件与网络	方舟环境策略	企业策略
依赖包与环境变量	通过 Environment 配置	企业自行管理
Session 资源	可以通过 resources 挂载 Files、Memory Store 或 TOS 对象	不支持通过 resources 挂载；输入文件由企业执行面准备
产物存储	可以通过 config.tos 配置	不支持通过 config.tos 配置；产物持久化与转存由企业执行面负责
Worker	不需要	需要部署
工具调用结果	进入方舟控制面	进入方舟控制面
运维责任	方舟为主	企业负责执行面

工作原理

方舟控制面与企业执行面的协作流程如下：

业务应用通过 Session API 创建 Session 并发送用户消息。

方舟控制面完成模型推理，生成 Tool Call 并写入 Work Queue。

企业 Worker 轮询 Environment 的 Work Queue，领取 Work Item。

Worker 在企业 Sandbox 中执行工具调用（Bash、文件读写、自定义工具）。

Tool Result 通过 Session Events API 回传方舟控制面，驱动下一轮推理。

任务结束后，Worker 清理执行环境，继续轮询下一个 Work Item。

说明

Tool Call 和 Tool Result 会经过方舟控制面，Agent 编排和模型推理仍在方舟侧完成。自托管改变的是工具执行位置，不是数据流向。详细的数据边界见自托管环境安全说明。

核心对象

对象	说明
Environment	Agent 运行时配置，type 为 self_hosted 时表示自托管环境。定义执行位置，不包含依赖包、环境变量和网络策略配置
Worker	企业部署的进程，负责轮询 Work Queue、维持心跳、执行工具调用并回传结果
Work Item	方舟为每个需要工具执行的 Session 生成的任务项，包含 Session 执行所需信息
Session	在 Environment 中运行的 Agent 实例，用于执行具体任务。Work ID 与 Session ID 一致
Events	应用与 Agent 之间交换的原子消息，涵盖用户消息、工具调用、工具结果与状态更新

一次任务如何运行

以下是一次完整自托管任务的执行流程：

业务应用创建绑定自托管 Environment 的 Session。

业务应用发送 user.message 事件。

方舟控制面为本次执行生成 Work Item，写入 Environment 的 Work Queue。

Worker 通过长轮询（Poll）领取 Work Item 并 Ack 确认。

Worker 维持心跳（Heartbeat），保持租约有效。

Worker 订阅 Session Events，消费 Tool Call 并在企业 Sandbox 中执行。

Worker 将 Tool Result 回传方舟，驱动下一轮推理。

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

Worker 完成 Work Item，清理执行环境。

数据与责任边界

自托管环境改变了工具执行位置，但模型推理和事件处理仍在方舟控制面。以下是关键数据流向：

数据	是否进入方舟控制面	是否留在企业环境
用户消息	是	可选保留
Tool Call 参数	是	Worker 接收
Tool Result	是	可保留
企业文件内容	默认不上传	是
命令执行进程	否	是
网络请求	取决于工具实现	企业控制

注意

自托管不等于"所有业务数据均不出域"。Tool Call 和 Tool Result 作为 Agent 推理的必要输入，会经过方舟控制面。如果你需要确保特定数据不进入方舟，应在工具实现中过滤敏感信息，或在 Worker 侧对 Tool Result 进行脱敏处理。详细安全说明见自托管环境安全说明。

支持的 Worker 能力

Ark Runtime SDK（Go、Python、Java），支持出站长轮询（Poll）领取 Work Item

常驻 Worker 模式（EnvironmentWorker），适用于长期运行的 Worker 主机

每 Session 独立 Sandbox 模式（HandleItem），适用于 Kubernetes 每 Session 一个 Pod

心跳续租（Heartbeat），默认 TTL 300 秒

未认领 Work 回收（Reclaim）：reclaim_older_than_ms 是认领超时阈值，单位为毫秒。Worker 拉取 Work 后超过该时间仍未认领时，其他 Worker 可再次获取该 Work。

注意

该参数只用于设置未认领 Work 的认领超时阈值。Work 被认领后，不受该参数影响。Worker 心跳中断时，服务端会在租约到期并经过 60 秒宽限期后将 Work 状态更新为 stopped，当前不会将该 Work 自动分配给其他 Worker。

下一步

配置并运行自托管环境：选择 Go、Python 或 Java SDK 启动 Worker，并完成一次 Session 工具执行

自托管环境安全说明：了解信任边界、凭证管理和 Sandbox 隔离

最近更新时间：2026.10.12 22:18:35

这个页面对您有帮助吗？

有用

无用