# 概述

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

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

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

> 方舟目前提供两种基于豆包大模型的构建方式：需对 Agent 循环进行细粒度控制时，选用 **模型 API**；需将完整 Agent 交由平台托管、聚焦业务逻辑时，选用 **Managed Agents**。两者的详细差异参见下文 [与模型 API 对比](/docs/overview#vs_model_api)。

**[快速入门](/docs/quick-start-code)**

4 步跑通你的第一个方舟托管 Agent：创建 Agent、创建环境、开启会话、发送消息并接收流式响应。

**[启动 Session](/docs/start-session)**

基于 Agent 与 Environment 创建 Session，发送用户事件，让 Agent 开始执行任务。

<span id="core_concepts"></span>
# 基本概念

方舟 Managed Agents 围绕以下四个概念构建：

| 概念              | 描述                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Agent**       | 可版本化、可复用的智能体配置资产，定义了一个智能体的角色、能力、行为边界和运行规则，是所有任务运行的模板和基准。创建一次，通过 `agent_id` 在多个 Session 中复用 |
| **Environment** | Session 运行的环境配置，包含网络、预装依赖包、环境变量与产物存储。通过 `environment_id` 引用                                                               |
| **Session**     | 在 Environment 中运行的 Agent 实例，用于执行一次具体任务。上下文、文件、状态相互隔离，同一 Agent 可发起多个并行 Session                                             |
| **Events**      | 应用与 Agent 之间交换的原子消息，涵盖用户消息、思考、工具调用、工具结果与状态更新。以只增不删的方式在服务端持久化，支持实时订阅或事后回放                                          |

<span id="advantages"></span>
# 核心优势

<span id="vs_model_api"></span>
## 与模型 API 对比

**模型 API** 是访问模型能力的最原子接口——需自行实现循环、解析工具调用、维护上下文，适用于需要 **细粒度控制** 的场景。**方舟 Managed Agents** 则是访问 Agent 能力的封装接口——将 Agent 层原本需自建的通用能力统一收敛至平台内部。

<span id="no_longer_needed"></span>
### 不再需要自行实现的部分

| 之前（模型 API + 自建循环）                                                        | 之后（方舟 Managed Agents）                                                       |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| 维护对话历史数组，每一轮将完整历史传回模型                                                   | Session 由服务端持久化历史，仅需发送 / 订阅事件                                               |
| 手动循环调用：模型返回 → 解析 `tool_use` → 执行工具 → 追加 `tool_result` → 再次调用模型          | 平台内置 AgentLoop 自动驱动整个循环；Agent 结束时发出 `session.status_idle`                   |
| 自建沙箱以执行 Agent 生成的代码，机器、容器、扩缩容与清理均需自行管理                                  | Session 自带沙箱，代码执行、文件读写、Bash 命令由平台代为承载，任务结束即释放                              |
| 自研上下文压缩策略以避免超出上下文窗口                                                     | 上下文自动压缩，Event API 全量留存，不丢失内容                                                |
| 自研长程任务的状态保存与恢复机制                                                     | 自动保存沙箱状态，长程任务原生支持断点续跑                                                       |
| 自研 IAM、密钥注入与执行环境隔离                                                      | 基于火山 IAM + 零信任凭证隔离，密钥不会进入沙箱进程                                               |

<span id="still_controlled"></span>
### 仍由你掌控的部分

- **模型与系统提示词**：字段保持不变，仅位置调整至 Agent 定义中。
- **自定义工具**：仍以 JSON Schema 声明 `input_schema`；执行方式调整为——由用户客户端订阅 `agent.custom_tool_use` 事件后自行执行。
- **上下文注入**：仍可通过系统提示词、Skills、上传文件等方式注入。
- **中断与引导**：可随时向 Session 发送额外用户事件以调整方向，或直接中断本轮执行。

<span id="when_to_use_model_api"></span>
### 何时仍应选择模型 API

若目标 **恰在于自定义 Agent 循环本身**——例如探索新的推理策略、构建自研 Agent 框架、或需对每一步 `tool_use` 进行特殊改写——则模型 API 更为合适。Managed Agents 面向的是「直接获取可运行的 Agent」，而非「构建 Agent 引擎」。

<span id="vs_open_source_agent"></span>
## 与开源 Agent 对比

主流开源 Agent Runtime（LangChain、OpenCode 等）解决了「能够运行」的问题，但要实现「稳定、高效、具备业务价值」的运行仍需大量投入。方舟并非「在开源框架之上叠加一层豆包适配」，而是 **自底向上自研 AgentLoop 调度内核，并与豆包大模型的原生能力进行深度双向优化**——相当于为模型配备一套量身定制的操作系统，而非在通用硬件上粗放运行。

| 对比维度      | 方舟 Managed Agents（原生 AgentLoop）  | 开源 Agent Runtime            |
| ------------- | ---------------------------------- | ---------------------------- |
| **模型适配方式** | 与豆包全系列原生双向优化               | 通用 prompt 模板适配所有模型      |
| **推理完成率**   | 思维链原生拆解、断点续跑、上下文自动压缩 | 长任务易偏离预期、中断后无法续跑、上下文丢失 |
| **工具调用**    | 协议级对齐，自动校验 / 重试 / 并行        | 通用 JSON 解析                  |
| **长程任务**    | 原生支持长程任务运行，自动生成快照、按需拉起 | 固定模板适配所有场景，需自建沙箱调度  |
| **接入成本**    | 开箱即用，零适配成本                    | 需 4–8 周自研适配，踩坑周期较长     |

<span id="use_cases"></span>
# 适用场景

方舟 Managed Agents 最适合具备以下特征的工作负载：

- **长时间运行**：单次任务需运行数分钟至数小时，涉及多次工具调用与迭代思考。
- **有状态**：跨多轮交互持久保存文件系统、对话历史与执行状态，支持断点续跑。
- **异步执行**：任务发起后由 Agent 自主推进，客户端仅需订阅事件流即可获取结果。
- **最少的基础设施**：无需自建 Agent 循环、沙箱与工具执行层。
- **弹性调用**：调用量波峰波谷显著，期望按用量计费而非常驻资源。

在上述特征之上，以下为已验证 PMF 的典型业务场景：

| 场景                     | 重复度 | 风险 | 说明                                     |
| ---------------------- | --- | -- | ---------------------------------------- |
| **IT 工单处理**            | 高   | 低  | 结构化强、模板化程度高，Agent 处理准确率高 |
| **报表自动生成**             | 高   | 低  | 数据抓取与汇总逻辑固定，易于 Agent 化    |
| **供应商邮件处理**            | 中   | 低  | 分类与回复流程明确，适合规则化自动化       |
| **代码 Review 与文档**      | 高   | 低  | 研发团队收益直观，ROI 显著              |
| **销售线索初筛**             | 中   | 低  | CRM 录入自动化，释放销售人力            |
| **视觉内容创作**             | 中   | 中  | 组合视觉搜索、图片生成、视频生成和视频合成工具，适合广告素材与短视频生产。 |

正在使用开源 Agent 自建业务、或通过脚本拼接 Agent 能力的团队，均可考虑迁移至方舟 Managed Agents 进行试点验证。

<span id="workflow"></span>
# 工作流程

方舟 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 执行过程中，可随时发送额外用户事件以引导其调整方向，或直接中断本轮执行。

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

- 如需以 **可视化方式** 快速完成原型验证，参见 [快速入门（控制台）](/docs/quick-start-console)。
- 如需直接以 **代码 / API** 完成端到端接入，参见 [快速入门（代码）](/docs/quick-start-code)。

<span id="pricing"></span>
# 计费说明

Managed Agents 按照 Agent 运行过程中实际消耗的 Tokens、Agent 运行时时长和工具调用次数三项累加计费。详情参见 [Managed Agents 计费](/docs/model-pricing#ma_billing)。