本文介绍方舟 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。
核心对象#
| 对象 | 说明 |
|---|---|
| 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 | 是 | 可保留 |
| 企业文件内容 | 默认不上传 | 是 |
| 命令执行进程 | 否 | 是 |
| 网络请求 | 取决于工具实现 | 企业控制 |
支持的 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。
下一步#
- 配置并运行自托管环境：选择 Go、Python 或 Java SDK 启动 Worker，并完成一次 Session 工具执行
- 自托管环境安全说明：了解信任边界、凭证管理和 Sandbox 隔离