火山方舟
火山方舟
文档指南
请输入
- 文档首页
火山方舟Managed Agents定义 AgentAgent
复制全文
下载 pdfAgent
文档反馈
问问助手方舟 Managed Agents 是火山方舟平台推出的全托管 Agent 服务，给您带来开箱即用的 Agent 体验。Agent 是方舟 Managed Agents 的基础元件，是一套包含基本信息、System Prompt、扩展能力（Skills、Tools、MCP 等）的配置模板，可以被任意 Session 复用，并支持版本化管理。本文介绍如何定义一个 Agent。
Agent 定义字段
准备工作
- 获取 API Key。API Key 是调用方舟平台模型和服务的鉴权信息。
- 访问 API Key 管理 页面，创建你的 API Key。
- （推荐）配置环境变量。API Key 是敏感信息，一旦意外泄露，可能会造成资金损失或安全风险，因此强烈建议你不要在代码中明文写入 API Key，而应该将其配置到环境变量中。
- 将以下命令中的 your_api_key_here 替换为你的 API Key，并在终端中运行命令，即可将 API Key 配置到环境变量中。详见环境变量配置指南。
- export ARK_API_KEY="your_api_key_here"export ARK_API_KEY="your_api_key_here"setx ARK_API_KEY "your_api_key_here"$env:ARK_API_KEY = "your_api_key_here"
- 开通 Managed Agents 服务。
- 访问 开通管理页面，切换到 Managed Agents 页签开通服务。
- 开通模型服务。
- 访问 开通管理 页面，开通模型服务。
创建 Agent
创建 Agent 后，接口会返回一个稳定的 Agent ID 和初始版本号 1。后续创建 Session 时，可以直接引用这个 Agent ID。
下面的示例创建了一个带内置工具集和自定义 Skill 的热点新闻 Agent：
curl https://ark.cn-beijing.volces.com/api/v3/agents \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "NewsAgent01",
"model": {
"id": "doubao-seed-2-1-pro-260628",
"speed": "standard"
},
"description": "将热点新闻总结为图片的小助手。",
"system": "你是一名热点新闻查询总结小助手，可将每天的前 10 条热点新闻以摘要图片的方式总结出来。",
"skills": [
{
"type": "custom",
"skill_id": "skill-20260812080348-****"
}
],
"tools": [
{
"type": "agent_toolset_20260701"
}
]
}'
其中 skill-20260812080348-**** 表示你上传自定义 Skill 后获得的 skill_id。
示例响应如下：
{
"id": "agent-20260812081435-*****",
"type": "agent",
"name": "NewsAgent01",
"description": "将热点新闻总结为图片的小助手。",
"version": 1,
"model": {
"id": "doubao-seed-2-1-pro-260628",
"speed": "standard"
},
"system": "你是一名热点新闻查询总结小助手，可将每天的前 10 条热点新闻以摘要图片的方式总结出来。",
"tools": [
{
"type": "agent_toolset_20260701",
"default_config": {
"enabled": true
}
}
],
"skills": [
{
"type": "custom",
"skill_id": "skill-20260812080348-****"
}
],
"created_at": "2026-08-12T08:14:35Z",
"updated_at": "2026-08-12T08:14:35Z"
}
更新 Agent 与版本
Agent 是版本化资源。每次更新配置时，都需要显式传入当前版本号；如果版本号不匹配，更新会失败。更新成功后，系统会生成一个新版本。
说明
将以下示例代码中的 {agent_id} 替换为待更新的 Agent ID。
curl https://ark.cn-beijing.volces.com/api/v3/agents/{agent_id} \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"version": 2,
"system": "你是一名热点新闻查询总结小助手，可将每天的前 10 条热点新闻以摘要图片和音频播报的方式总结出来。",
"skills": [
{
"type": "custom",
"skill_id": "skill-20260812075208-****"
},
{
"type": "custom",
"skill_id": "skill-20260729084811-****"
}
]
}'
示例响应如下：
{
"id": "agent-20260812081435-*****",
"type": "agent",
"name": "NewsAgent01",
"description": "将热点新闻总结为图片的小助手。",
"version": 2,
"model": {
"id": "doubao-seed-2-1-pro-260628",
"speed": "standard"
},
"system": "你是一名热点新闻查询总结小助手，可将每天的前 10 条热点新闻以摘要图片和音频播报的方式总结出来。",
"tools": [
{
"type": "agent_toolset_20260701",
"default_config": {
"enabled": true
}
}
],
"skills": [
{
"type": "custom",
"skill_id": "skill-20260812075208-****"
},
{
"type": "custom",
"skill_id": "skill-20260729084811-****"
}
],
"created_at": "2026-08-12T08:14:35Z",
"updated_at": "2026-08-12T08:25:21Z"
}
更新 Agent 时，建议关注以下规则：
- 更新请求必须带当前 version。
- 修改配置后会生成新的 Agent 版本。
- 如果某些字段保持不变，可以只传需要修改的字段；例如只更新 system 时，不需要重复传 tools。
- skills 使用覆盖逻辑。请求体一旦传入 skills，系统会用该数组整体覆盖 Agent 当前的 skills 配置，不会在原有基础上追加。
- 如果你只想新增或调整某个 Skill，需要先读取当前 Agent 的 skills，再把“需要保留的 Skills + 新的 Skills”一起写回请求体。
设计建议
- 把稳定能力放进 Agent，把一次性任务放进 Session 事件。
- system 只定义角色、约束和长期规则，不要把当前任务直接写进 system。
- 需要外部系统能力时，优先使用 MCP。
- 需要复用领域知识或执行规范时，优先挂载 Skills，而不是把大段操作手册直接塞进 system。
相关文档
Skills
Skills 用于给 Agent 补充领域知识、操作流程和最佳实践。
MCP
MCP（Model Context Protocol）用于把第三方系统的工具与数据源接入 Agent。
Tools
Tools 决定 Agent 在 Session 中能主动调用哪些执行能力。
工具权限策略
工具权限策略用于控制 Agent 发起工具调用时，是自动执行，还是暂停等待确认。
最近更新时间：2026.09.10 16:05:17
这个页面对您有帮助吗？
有用
有用
无用
无用