方舟 Managed Agents 是火山方舟提供的 **预构建、可配置的智能体框架** ，运行在方舟托管的基础设施之上，最适合承载 **长时间运行、多轮工具调用、有状态的异步任务** 。基于模型 API 构建一个可用的 Agent，需自行实现 AgentLoop、工具调用、上下文管理、沙箱调度、断点续跑与权限隔离等通用组件——建设周期通常需要 4 至 8 周，且需随模型迭代持续适配。方舟 Managed Agents 将 Agent 层的一整套基础设施完整交付，开发者仅需定义 Agent 行为、发送用户事件并订阅结果流，底层复杂度全部由平台承担。 > 方舟目前提供两种基于豆包大模型的构建方式：需对 Agent 循环进行细粒度控制时，选用 **模型 API** ；需将完整 Agent 交由平台托管、聚焦业务逻辑时，选用 **Managed Agents** 。两者的详细差异参见下文 [与模型 API 对比](https://www.volcengine.com/docs/82379/2553713#vs_model_api)。 **快速入门** 4 步跑通你的第一个方舟托管 Agent：创建 Agent、创建环境、开启会话、发送消息并接收流式响应。 **启动 Session** 基于 Agent 与 Environment 创建 Session，发送用户事件，让 Agent 开始执行任务。 # 基本概念方舟 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 全量留存，不丢失内容 | |自研长程任务的 Checkpoint 与恢复机制 |自动生成快照，长程任务原生支持断点续跑 | |自研 IAM、密钥注入与执行环境隔离 |基于火山 IAM + 零信任凭证隔离，密钥不会进入沙箱进程 | ### 仍由用户掌控的部分 * **模型与系统提示词** ：字段保持不变，仅位置调整至 Agent 定义中。 * **自定义工具** ：仍以 JSON Schema 声明 `input_schema`；执行方式调整为——由用户客户端订阅 `agent.custom_tool_use` 事件，执行后将结果作为 `user.custom_tool_result` 回传。 * **上下文注入** ：仍可通过系统提示词、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 个步骤： 1. **创建 Agent** ：在控制台或通过 API 定义模型、系统提示词与 Skills / Tools / MCPs，获得稳定的 `agent_id`，可在多个 Session 中通过 ID 复用。 2. **创建 Environment** ：定义沙箱运行环境（预装包、环境变量），获得稳定的 `environment_id`。 3. **启动 Session** ：基于 `agent_id` 与 `environment_id` 创建一次会话（Session）。 4. **发送事件并流式接收响应** ：将用户消息作为事件发送至 Session，Agent 自主执行工具并通过 SSE（server\-sent events）流式返回结果，事件历史由服务端持久化保存，支持完整获取。 5. **引导或中断** ：Agent 执行过程中，可随时发送额外用户事件以引导其调整方向，或直接中断本轮执行。上手方式提供以下两种路径： * 如需以 **可视化方式** 快速完成原型验证，参见 [快速入门（控制台）](https://www.volcengine.com/docs/82379/2553715)。 * 如需直接以 **代码 / API** 完成端到端接入，参见 [快速入门（代码）](https://www.volcengine.com/docs/82379/2553714)。 # 计费说明 Managed Agents 按照 Agent 运行过程中实际消耗的 Tokens、Agent 运行时时长和工具调用次数三项累加计费。详情参见 [Managed Agents 计费](https://www.volcengine.com/docs/82379/1544106#ma_billing)。