文档中心

火山方舟

定义 Agent

Agent

方舟 Managed Agents 是火山方舟平台推出的全托管 Agent 服务，给您带来开箱即用的 Agent 体验。Agent 是方舟 Managed Agents 的基础元件，是一套包含基本信息、System Prompt、扩展能力（Skills、Tools、MCP 等）的配置模板，可以被任意 Session 复用，并支持版本化管理。本文介绍如何定义一个 Agent。

Agent 版本

创建 Agent 时，先根据任务选择 Agent 版本：

通用 Agent：适用于代码执行、内容检索和文档处理等通用任务。

视觉增强 Agent：适用于图片生成、视频生成、视觉搜索和视频合成等任务。

Agent 定义字段

Agent 的完整字段定义（包括名称、模型、System Prompt、Skills、Tools、MCP、多智能体协作、元数据等），请参见创建智能体。

准备工作

获取 API Key。API Key 是调用方舟平台模型和服务的鉴权信息。

访问 API Key 管理页面，创建你的 API Key。

安装 curl 和 jq，并配置环境变量。API Key 是敏感信息，一旦意外泄露，可能会造成资金损失或安全风险，因此不要在代码中明文写入 API Key，应将其配置到环境变量中。

将以下命令中的 your_api_key_here 替换为你的 API Key，并在终端中运行命令，即可将 API Key 配置到环境变量中。详见环境变量配置指南。

macOS
Linux
Windows_CMD
Windows_PowerShell

export ARK_API_KEY="your_api_key_here"

开通 Managed Agents 服务。

访问开通管理页面，切换到 Managed Agents 页签开通服务。

开通模型服务。

访问开通管理页面，开通模型服务。

创建 Agent

创建 Agent 后，接口会返回一个稳定的 Agent ID 和初始版本号 1。后续创建 Session 时，可以直接引用这个 Agent ID。

下面的示例创建一个带内置工具集和自定义 Skill 的热点新闻 Agent。示例显式配置内置工具的启用状态和权限策略，并将响应中的 Agent ID 与当前版本保存到环境变量：

其中 skill-20260812080348-**** 表示你上传自定义 Skill 后获得的 skill_id。

示例响应如下：

更新 Agent 与版本

Agent 是版本化资源。每次更新配置时，都需要显式传入当前版本号；如果版本号不匹配，更新会失败。更新成功后，系统会生成一个新版本。

以下示例先查询 Agent 的当前版本，再提交更新。运行本页的创建示例后，可以直接复用 AGENT_ID；更新其他 Agent 时，先将其 ID 写入该环境变量。

示例响应如下：

更新 Agent 时，建议关注以下规则：

更新请求必须带当前 version。

修改配置后会生成新的 Agent 版本。

更新接口返回 HTTP 400 InvalidParameter 且错误信息包含 version: conflict 时，说明其他请求已经更新了该 Agent。重新查询 Agent，合并最新配置后再提交，不要只递增本地版本号。

如果某些字段保持不变，可以只传需要修改的字段；例如只更新 system 时，不需要重复传 tools。

mcp_servers、tools 和 skills 都使用整体替换逻辑。请求体一旦传入其中一个数组，服务端会用该数组整体覆盖对应的当前配置，不会在原有基础上追加。

如果只想新增或调整其中一项，先查询 Agent 的最新配置，在本地合并需要保留的条目，再把完整数组与当前 version 一起写回。

取值	mcp_servers、tools 和 skills 的处理方式	适用场景
省略或 null	保留对应字段的当前配置。	只更新其他字段。
空数组 []	清空对应字段的已保存配置。	明确移除全部 MCP Server、工具或技能。
非空数组	使用请求中的数组整体替换当前配置。	先读取并合并所有需要保留的条目。

注意

如需限制主 Agent 的内置工具范围，请显式配置内置工具集并关闭默认范围，不要通过清空 tools 实现。详情请参见核对默认工具范围。

设计建议

把稳定能力放进 Agent，把一次性任务放进 Session 事件。

system 只定义角色、约束和长期规则，不要把当前任务直接写进 system。

需要外部系统能力时，优先使用 MCP。

需要复用领域知识或执行规范时，优先挂载 Skills，而不是把大段操作手册直接塞进 system。