文档中心

火山方舟

快速上手

概述

方舟 Managed Agents 是火山方舟提供的预构建、可配置的智能体框架，运行在方舟托管的基础设施之上，最适合承载长时间运行、多轮工具调用、有状态的异步任务。

基于模型 API 构建一个可用的 Agent，需要自行实现 AgentLoop、工具调用、上下文管理、沙箱调度、断点续跑与权限隔离等通用组件。建设周期通常需要 4 至 8 周，且需随模型迭代持续适配。方舟 Managed Agents 提供 Agent 层的完整基础设施，你只需定义 Agent 行为、发送用户事件并订阅结果流。

方舟目前提供两种基于豆包大模型的构建方式：需对 Agent 循环进行细粒度控制时，选用模型 API；需将完整 Agent 交由平台托管、聚焦业务逻辑时，选用 Managed Agents。两者的详细差异参见下文与模型 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 全量留存，不丢失内容
自研长程任务的状态保存与恢复机制	自动保存沙箱状态，长程任务原生支持断点续跑
自研 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 执行过程中，可随时发送额外用户事件以引导其调整方向，或直接中断本轮执行。

上手方式提供以下两种路径：

如需以可视化方式快速完成原型验证，参见快速入门（控制台）。

如需直接以代码 / API 完成端到端接入，参见快速入门（代码）。

计费说明

Managed Agents 按照 Agent 运行过程中实际消耗的 Tokens、Agent 运行时时长和工具调用次数三项累加计费。详情参见 Managed Agents 计费。

最近更新时间：2026.10.10 14:49:40

这个页面对您有帮助吗？

有用

无用