方舟 Managed Agents 是火山方舟提供的 预构建、可配置的智能体框架，运行在方舟托管的基础设施之上，最适合承载 长时间运行、多轮工具调用、有状态的异步任务。
基于模型 API 构建一个可用的 Agent，需要自行实现 AgentLoop、工具调用、上下文管理、沙箱调度、断点续跑与权限隔离等通用组件。建设周期通常需要 4 至 8 周，且需随模型迭代持续适配。方舟 Managed Agents 提供 Agent 层的完整基础设施，你只需定义 Agent 行为、发送用户事件并订阅结果流。
方舟目前提供两种基于豆包大模型的构建方式：需对 Agent 循环进行细粒度控制时，选用 模型 API；需将完整 Agent 交由平台托管、聚焦业务逻辑时，选用 Managed Agents。两者的详细差异参见下文 与模型 API 对比。
基本概念#
方舟 Managed Agents 围绕以下四个概念构建：
| 概念 | 描述 |
|---|---|
| Agent | 可版本化、可复用的智能体配置资产，定义了一个智能体的角色、能力、行为边界和运行规则，是所有任务运行的模板和基准。创建一次，通过 agent_id 在多个 Session 中复用 |
| Environment | Session 运行的环境配置，包含网络、预装依赖包、环境变量与产物存储。通过 environment_id 引用 |
| Session | 在 Environment 中运行的 Agent 实例，用于执行一次具体任务。上下文、文件、状态相互隔离，同一 Agent 可发起多个并行 Session |
| Events | 应用与 Agent 之间交换的原子消息，涵盖用户消息、思考、工具调用、工具结果与状态更新。以只增不删的方式在服务端持久化，支持实时订阅或事后回放 |
核心优势#
与模型 API 对比#
模型 API 是访问模型能力的最原子接口——需自行实现循环、解析工具调用、维护上下文，适用于需要 细粒度控制 的场景。方舟 Managed Agents 则是访问 Agent 能力的封装接口——将 Agent 层原本需自建的通用能力统一收敛至平台内部。
不再需要自行实现的部分#
| 之前（模型 API + 自建循环） | 之后（方舟 Managed Agents） |
|---|---|
| 维护对话历史数组，每一轮将完整历史传回模型 | Session 由服务端持久化历史，仅需发送 / 订阅事件 |
手动循环调用：模型返回 → 解析 tool_use → 执行工具 → 追加 tool_result → 再次调用模型 |
平台内置 AgentLoop 自动驱动整个循环；Agent 结束时发出 session.status_idle |
| 自建沙箱以执行 Agent 生成的代码，机器、容器、扩缩容与清理均需自行管理 | Session 自带沙箱，代码执行、文件读写、Bash 命令由平台代为承载，任务结束即释放 |
| 自研上下文压缩策略以避免超出上下文窗口 | 上下文自动压缩，Event API 全量留存，不丢失内容 |
| 自研长程任务的状态保存与恢复机制 | 自动保存沙箱状态，长程任务原生支持断点续跑 |
| 自研 IAM、密钥注入与执行环境隔离 | 基于火山 IAM + 零信任凭证隔离，密钥不会进入沙箱进程 |
仍由你掌控的部分#
- 模型与系统提示词：字段保持不变，仅位置调整至 Agent 定义中。
- 自定义工具：仍以 JSON Schema 声明
input_schema；执行方式调整为——由用户客户端订阅agent.custom_tool_use事件后自行执行。 - 上下文注入：仍可通过系统提示词、Skills、上传文件等方式注入。
- 中断与引导：可随时向 Session 发送额外用户事件以调整方向，或直接中断本轮执行。
何时仍应选择模型 API#
若目标 恰在于自定义 Agent 循环本身——例如探索新的推理策略、构建自研 Agent 框架、或需对每一步 tool_use 进行特殊改写——则模型 API 更为合适。Managed Agents 面向的是「直接获取可运行的 Agent」，而非「构建 Agent 引擎」。
与开源 Agent 对比#
主流开源 Agent Runtime（LangChain、OpenCode 等）解决了「能够运行」的问题，但要实现「稳定、高效、具备业务价值」的运行仍需大量投入。方舟并非「在开源框架之上叠加一层豆包适配」，而是 自底向上自研 AgentLoop 调度内核，并与豆包大模型的原生能力进行深度双向优化——相当于为模型配备一套量身定制的操作系统，而非在通用硬件上粗放运行。
| 对比维度 | 方舟 Managed Agents（原生 AgentLoop） | 开源 Agent Runtime |
|---|---|---|
| 模型适配方式 | 与豆包全系列原生双向优化 | 通用 prompt 模板适配所有模型 |
| 推理完成率 | 思维链原生拆解、断点续跑、上下文自动压缩 | 长任务易偏离预期、中断后无法续跑、上下文丢失 |
| 工具调用 | 协议级对齐，自动校验 / 重试 / 并行 | 通用 JSON 解析 |
| 长程任务 | 原生支持长程任务运行，自动生成快照、按需拉起 | 固定模板适配所有场景，需自建沙箱调度 |
| 接入成本 | 开箱即用，零适配成本 | 需 4–8 周自研适配，踩坑周期较长 |
适用场景#
方舟 Managed Agents 最适合具备以下特征的工作负载：
- 长时间运行：单次任务需运行数分钟至数小时，涉及多次工具调用与迭代思考。
- 有状态：跨多轮交互持久保存文件系统、对话历史与执行状态，支持断点续跑。
- 异步执行：任务发起后由 Agent 自主推进，客户端仅需订阅事件流即可获取结果。
- 最少的基础设施：无需自建 Agent 循环、沙箱与工具执行层。
- 弹性调用：调用量波峰波谷显著，期望按用量计费而非常驻资源。
在上述特征之上，以下为已验证 PMF 的典型业务场景：
| 场景 | 重复度 | 风险 | 说明 |
|---|---|---|---|
| IT 工单处理 | 高 | 低 | 结构化强、模板化程度高，Agent 处理准确率高 |
| 报表自动生成 | 高 | 低 | 数据抓取与汇总逻辑固定，易于 Agent 化 |
| 供应商邮件处理 | 中 | 低 | 分类与回复流程明确，适合规则化自动化 |
| 代码 Review 与文档 | 高 | 低 | 研发团队收益直观，ROI 显著 |
| 销售线索初筛 | 中 | 低 | CRM 录入自动化，释放销售人力 |
| 视觉内容创作 | 中 | 中 | 组合视觉搜索、图片生成、视频生成和视频合成工具，适合广告素材与短视频生产。 |
正在使用开源 Agent 自建业务、或通过脚本拼接 Agent 能力的团队，均可考虑迁移至方舟 Managed Agents 进行试点验证。
工作流程#
方舟 Managed Agents 从创建到接入业务，通常经历以下 5 个步骤：
- 创建 Agent：在控制台或通过 API 定义模型、系统提示词与 Skills / Tools / MCPs，获得稳定的
agent_id，可在多个 Session 中通过 ID 复用。 - 创建 Environment：定义沙箱运行环境（网络、预装包、环境变量和产物存储），获得稳定的
environment_id。 - 启动 Session：基于
agent_id与environment_id创建一次会话（Session）。 - 发送事件并流式接收响应：将用户消息作为事件发送至 Session，Agent 自主执行工具并通过 SSE（server-sent events）流式返回结果，事件历史由服务端持久化保存，支持完整获取。
- 引导或中断：Agent 执行过程中，可随时发送额外用户事件以引导其调整方向，或直接中断本轮执行。
上手方式提供以下两种路径：
计费说明#
Managed Agents 按照 Agent 运行过程中实际消耗的 Tokens、Agent 运行时时长和工具调用次数三项累加计费。详情参见 Managed Agents 计费。