火山方舟
火山方舟
文档指南
请输入
- 文档首页
火山方舟Managed Agents定义 AgentTools
复制全文
下载 pdfTools
文档反馈
问问助手模型可以理解任务并生成内容，但无法仅靠推理直接操作文件、执行命令或访问业务系统。为 Agent 配置 Tools 后，Agent 可以调用相应的执行能力，并根据工具结果继续处理任务，完成从理解需求到执行操作的闭环。
选择工具
根据任务需要访问的资源和工具执行方，选择对应的工具类型。
- 任务需要在云环境中操作文件、执行命令或获取网页信息时，使用内置工具。
- 任务需要访问已经接入 MCP Server 的外部系统时，使用 MCP 工具。
- 任务只需调用少量自有业务操作，且由业务应用执行时，使用自定义工具。
- 复杂任务因多次失败或模型能力限制而停滞时，使用 Evolution 工具集中的 Advisor 工具获取执行建议。
使用内置工具
当任务需要在方舟提供的云环境中处理文件、运行命令或获取网页信息时，使用内置工具集 agent_toolset_20260701。典型场景包括整理上传的文件、生成并运行代码，以及检索和汇总公开信息。
把 agent_toolset_20260701 加到 Agent 后，以下工具默认全部启用。
工具 | 配置名 | 说明 |
Bash | bash | 在沙箱中执行 Bash 命令。 |
Read | read | 读取沙箱内文件。 |
Write | write | 写入或覆盖沙箱内文件。 |
Edit | edit | 对文件执行字符串替换。 |
Glob | glob | 按名称查找文件。 |
Grep | grep | 按正则搜索文本内容。 |
Web Fetch | web_fetch | 抓取指定 URL 内容。 |
Web Search | web_search | 发起联网搜索。 |
注意
Web Search 按实际调用次数计费。
接入 MCP 工具
当任务需要访问已经通过 MCP Server 接入的外部系统，或需要复用一组标准化外部工具时，使用 MCP 工具集 mcp_toolset。典型场景包括查询项目数据、读取业务信息和触发外部工作流。
MCP 工具集通过 type: "mcp_toolset" 将一个 MCP Server 暴露的工具提供给 Agent。mcp_server_name 必须与 mcp_servers[].name 一致；只声明 MCP Server 而不添加对应的 mcp_toolset 时，Agent 无法调用该 Server 的工具。
显式提供 default_config 但省略 permission_policy 时，MCP 工具运行时使用 always_ask，内置工具使用 always_allow。为避免 MCP 调用意外暂停，建议显式配置权限策略。
接入自定义工具
当任务只需要调用少量自有业务操作，且无需为这些操作单独部署 MCP Server 时，使用自定义工具 custom。典型场景包括查询订单、提交工单和触发审批。业务应用负责执行实际操作，再把结果回传给 Agent。
自定义工具通过 type: "custom" 声明。每个工具需要配置名称、用途描述和输入参数 Schema。以下示例使用 curl 创建 Agent，并使用 jq 保存返回的 Agent ID。示例同时显式关闭内置工具集，避免主 Agent 回退启用全部内置工具：
AGENT_RESPONSE=$(curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/agents" \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "CustomToolDemo",
"model": {
"id": "doubao-seed-2-1-pro-260628"
},
"system": "你是一个可以调用业务工具的助手。需要外部业务能力时，调用已声明的自定义工具。不要编造工具结果。",
"tools": [
{
"type": "agent_toolset_20260701",
"default_config": {
"enabled": false,
"permission_policy": {
"type": "always_allow"
}
}
},
{
"type": "custom",
"name": "query_order",
"description": "根据订单 ID 查询订单状态。仅当用户要求查询订单信息时使用。",
"input_schema": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "订单 ID。"
}
},
"required": ["order_id"],
"additionalProperties": false
}
}
]
}') || exit 1
jq . <<<"$AGENT_RESPONSE" || exit 1
AGENT_ID=$(jq -er '.id' <<<"$AGENT_RESPONSE") || exit 1
export AGENT_ID
printf 'Agent ID: %s\n' "$AGENT_ID"
配置后，Agent 需要查询订单时会发送 agent.custom_tool_use。业务应用读取工具名称和输入参数，执行查询，再通过 user.custom_tool_result 回传结果。完整接入流程和多媒体场景示例请参见 [基础] Custom Tool 使用教程。
使用 Advisor 工具
当复杂任务包含多个步骤，Agent 可能因多次执行失败或当前模型无法处理的问题而停滞时，使用 Evolution 工具集中的 Advisor 工具。配置 evolution 类型和 advisor 后，Agent 可以获取执行建议并继续任务；步骤明确、结果确定的操作优先使用内置工具、MCP 工具或自定义工具。
创建或更新 Agent 时，在 tools 中添加 evolution，并将 configs[].name 设置为 advisor：
curl https://ark.cn-beijing.volces.com/api/v3/agents \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "自演进 Agent",
"model": {
"id": "doubao-seed-2-1-pro-260628"
},
"tools": [
{
"type": "agent_toolset_20260701",
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_allow"
}
}
},
{
"type": "evolution",
"configs": [
{
"name": "advisor",
"enabled": true
}
]
}
]
}'
省略 configs[].enabled 时，Advisor 默认启用；设置为 false 时关闭。evolution 不支持 default_config，Advisor 不支持 permission_policy。不能只传 type: "evolution"，缺少 configs[].name: "advisor" 时，服务端返回 400 InvalidParameter。完整使用方法请参见 Advisor。
配置内置工具
创建 Agent 前，先确定任务必须使用哪些工具、哪些工具可以修改数据，以及哪些调用需要业务应用确认。显式配置 default_config.enabled 和 permission_policy，再通过 configs 覆盖单个工具，可以避免不同工具类型的默认行为造成权限范围偏差。
注意
不要通过省略 tools、传入空数组 []，或只配置 MCP、Evolution 等其他工具来关闭主 Agent 的内置工具。主 Agent 在未找到内置工具集配置时会回退为启用全部内置工具，并使用 always_allow；如需限制工具范围，请显式配置 agent_toolset_20260701，将 default_config.enabled 设为 false，再逐项启用必要工具。详细行为请参见 核对默认工具范围。
启用全部内置工具
如果 Agent 需要使用全部基础执行能力，挂载 agent_toolset_20260701，并显式启用工具集和权限策略：
curl https://ark.cn-beijing.volces.com/api/v3/agents \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "代码助理",
"model": {
"id": "doubao-seed-2-1-pro-260628"
},
"tools": [
{
"type": "agent_toolset_20260701",
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_allow"
}
}
}
]
}'
关闭部分工具
如果 Agent 不应访问网页，可以保持工具集启用，再通过 configs 关闭 web_fetch 和 web_search：
curl https://ark.cn-beijing.volces.com/api/v3/agents \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "离线文档助理",
"model": {
"id": "doubao-seed-2-1-pro-260628"
},
"tools": [
{
"type": "agent_toolset_20260701",
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_allow"
}
},
"configs": [
{
"name": "web_fetch",
"enabled": false
},
{
"name": "web_search",
"enabled": false
}
]
}
]
}'
只启用必要工具
如果 Agent 只需要读取和检索沙箱文件，先将工具集整体关闭，再显式启用 read、glob 和 grep：
curl https://ark.cn-beijing.volces.com/api/v3/agents \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "只读审查 Agent",
"model": {
"id": "doubao-seed-2-1-pro-260628"
},
"tools": [
{
"type": "agent_toolset_20260701",
"default_config": {
"enabled": false,
"permission_policy": {
"type": "always_ask"
}
},
"configs": [
{
"name": "read",
"enabled": true,
"permission_policy": {
"type": "always_allow"
}
},
{
"name": "glob",
"enabled": true,
"permission_policy": {
"type": "always_allow"
}
},
{
"name": "grep",
"enabled": true,
"permission_policy": {
"type": "always_allow"
}
}
]
}
]
}'
这种配置适合代码审查和资料检索等只读任务。
设置权限策略
always_allow 表示平台直接执行工具，always_ask 表示平台在执行前暂停 Session，等待业务应用确认。建议在请求中显式配置工具集的默认策略，并通过 configs[].permission_policy 覆盖风险更高的单个工具。
验证和处理工具调用
创建或更新 Agent 后，按以下顺序验证配置是否生效：
- 调用查询智能体详情，检查响应中的 tools 是否符合预期；使用 MCP 工具时，同时检查 mcp_servers。
- 创建新 Session，或调用升级会话升级现有 Session。已创建的 Session 不会自动使用 Agent 的新版本。
- 发送一条能够触发目标工具的测试任务。
- 检查 Session 事件，确认工具调用、执行结果和最终回复已经形成闭环。
以下以查询订单状态并整理结果为例说明主要事件流。具体事件取决于工具的执行方和权限策略。
处理云环境工具调用
云环境中，方舟服务端负责执行内置工具和 MCP 工具。下图展示 Agent 发起调用、按需等待确认并返回结果的过程。always_allow 会直接执行工具；always_ask 会先暂停 Session，等待业务应用批准或拒绝。
自动执行
使用 always_allow 时，平台直接执行工具并返回结果：
- 内置工具：agent.tool_use → agent.tool_result
- MCP 工具：agent.mcp_tool_use → agent.mcp_tool_result
同一轮可能调用多个工具。使用 tool_use_id 或 mcp_tool_use_id 将每个结果与对应调用配对，不要只依赖事件到达顺序。
确认后执行
内置工具或 MCP 工具使用 always_ask 时，Session 会暂停并等待确认：
- Session 返回 agent.tool_use 或 agent.mcp_tool_use。
- Session 返回 session.status_idle，其中 stop_reason.type=requires_action，stop_reason.event_ids 列出待确认的调用事件。
- 客户端发送 user.tool_confirmation，通过 tool_use_id 指定调用事件，并将 result 设置为 allow 或 deny。
- 所有待确认事件处理完成后，Session 返回 session.status_running。批准的工具继续执行，拒绝结果交给 Agent 调整后续处理。
处理确认结果
拒绝调用时，可以通过 deny_message 把原因回传给 Agent。Agent 会根据拒绝原因选择其他工具、降级处理，或向最终用户说明无法继续执行。
在 requires_action 阶段，先处理 stop_reason.event_ids 中的全部确认事件，不要用新的 user.message 替代确认。always_allow、always_ask 及覆盖规则请参见 工具权限策略。
处理自托管工具调用
自托管 Environment 中的 Worker 完成内置工具后，通过 user.tool_result 回传结果：
- Session 返回 agent.tool_use，下发内置工具调用。
- Session 返回 session.status_idle，其中 stop_reason.type=requires_action。
- Worker 获取对应的 Work，并在企业 Sandbox 中执行工具。
- Worker 通过 user.tool_result 回传结果。tool_use_id 必须填写对应的 agent.tool_use.id；工具执行失败时，将 is_error 设为 true，并在 content 中返回失败说明。
- 所有待处理结果回传后，Session 返回 session.status_running，Agent 根据工具结果继续处理任务。
处理自定义工具调用
自定义工具由业务应用执行，事件闭环如下：
- Session 返回 agent.custom_tool_use，其中包含工具名称、输入参数和调用事件 ID。
- Session 返回 session.status_idle，其中 stop_reason.type=requires_action，stop_reason.event_ids 列出待处理的调用事件。
- 业务应用根据工具名称和输入参数执行对应操作。
- 业务应用发送 user.custom_tool_result，并将调用事件 ID 原样填入 custom_tool_use_id。如果同一轮存在多个待处理调用，需要分别回传结果。
- 所有待处理结果回传后，Session 返回 session.status_running，Agent 根据工具结果继续处理任务。
更新工具配置
更新 Agent 可以使用的工具时，tools 使用整体替换语义。为避免误取消其他可用工具，按照以下步骤读取、合并并写回完整 tools 数组：
- 调用查询智能体详情，获取最新 version 和完整 tools 数组。
- 在本地副本中保留不需要修改的工具，只调整目标工具。
- 调用更新智能体，同时提交当前 version 和合并后的完整 tools 数组。
- 再次查询 Agent，确认版本号和工具配置已经更新。
- 创建新 Session，或升级现有 Session 后验证工具调用。
更新请求中 tools 的取值语义如下：
取值 | 配置结果 | 使用建议 |
省略或 null | 保留当前 tools 配置。 | 只修改其他 Agent 字段时使用。 |
空数组 [] | 只清空已保存的 tools 配置，不会关闭主 Agent 的内置工具。主 Agent 运行时仍会回退为启用全部内置工具，并使用 always_allow。 | 如需限制内置工具，改用显式工具集配置。 |
非空数组 | 使用请求中的数组整体替换当前配置。 | 先读取并合并所有需要保留的工具。 |
排查工具问题
先根据 Session 事件流定位中断点，再执行对应检查：
- 未出现目标工具的调用事件：核对 Agent 配置、Session 版本和任务触发条件。
- 出现 stop_reason.type=requires_action：根据阻塞事件类型回传确认或工具结果。
- 工具结果包含错误：根据调用 ID 定位输入、权限或执行环境。
- 出现 session.error：根据错误类型和重试状态决定等待、修正后重试或创建新 Session。
- 工具可以执行但权限范围过大：核对文件、网络和凭据隔离边界。
核对配置、版本和触发条件
如果事件流中没有出现 agent.tool_use、agent.mcp_tool_use 或 agent.custom_tool_use，按以下顺序检查：
- 查询 Agent，确认目标工具或工具集已经保存。MCP 工具还需要检查 mcp_servers。
- 确认当前 Session 使用的 Agent 版本；Agent 更新不会自动影响已创建的 Session。
- 按工具类型核对配置与触发条件。
- 使用相同的明确测试任务比较新旧 Session，避免把任务差异误判为版本问题。
Agent 会根据任务内容和工具说明判断是否调用工具。单次未调用不能直接证明配置无效；应先使用明确要求目标能力的测试任务复现。
核对默认工具范围
主 Agent 与子 Agent 在未配置内置工具集时采用不同的运行时行为：
配置 | 主 Agent | 子 Agent | 建议 |
省略 tools、传 []，或只配置其他工具类型 | 回退为启用全部内置工具，权限策略为 always_allow。 | 不提供内置工具；Session 启用的 Memory 工具不受此规则影响。 | 不依赖省略行为，显式配置内置工具集。 |
配置 agent_toolset_20260701，省略 default_config | 服务端保存 enabled=true 和 always_allow。 | 按相同配置提供内置工具。 | 在请求中显式写出启用状态和权限策略。 |
配置 default_config.enabled=false，再逐项启用 | 只提供 configs 中显式启用的工具。 | 只提供 configs 中显式启用的工具。 | 需要最小工具集时使用。 |
判断子 Agent 是否实际执行工具时，以子线程中的 agent.tool_use 和 agent.tool_result 为准。System Prompt 或最终回复中声称已执行工具，不代表运行环境实际提供或执行了该工具。
核对默认权限策略
权限策略存在以下默认分支：
配置 | 内置工具 | MCP 工具 |
整个 default_config 省略 | 服务端保存 always_allow。 | 服务端保存 always_allow。 |
已提供 default_config，但省略 permission_policy | 运行时使用 always_allow。 | 运行时使用 always_ask。 |
显式配置 permission_policy | 使用配置的 always_allow 或 always_ask。 | 使用配置的 always_allow 或 always_ask。 |
处理 requires_action
Session 返回 stop_reason.type=requires_action 时，先读取 stop_reason.event_ids，再根据每个阻塞事件的类型执行对应操作：
阻塞事件 | 场景 | 处理方式 |
agent.tool_use 或 agent.mcp_tool_use | 云环境中的工具使用 always_ask。 | 发送 user.tool_confirmation，将阻塞事件 ID 填入 tool_use_id，并设置 allow 或 deny。确认 MCP 调用时也使用 tool_use_id；mcp_tool_use_id 仅用于关联 agent.mcp_tool_result。 |
agent.tool_use | 自托管 Environment 中的 Worker 执行内置工具。 | Worker 完成执行后发送 user.tool_result，使用 tool_use_id 关联调用；失败时设置 is_error: true 并返回错误说明。 |
agent.custom_tool_use | 业务应用执行自定义工具。 | 发送 user.custom_tool_result，使用 custom_tool_use_id 关联调用；失败时设置 is_error: true 并返回错误说明。 |
同一轮可能包含多个阻塞事件。处理 stop_reason.event_ids 中的全部事件后，Session 才会恢复运行。不要用新的 user.message 代替确认或工具结果。
排查工具结果错误
工具结果包含错误时，先关联对应的调用事件，再定位执行方：
- agent.tool_result：通过 tool_use_id 检查原始工具输入，再核对文件路径、Environment 权限、网络策略和执行日志。
- agent.mcp_tool_result：通过 mcp_tool_use_id 检查原始工具输入，再核对 MCP 工具启用状态、凭据和 Server 返回信息。
- user.tool_result 或 user.custom_tool_result：检查业务应用或 Worker 的执行日志，确认 is_error、content 和调用 ID 与实际结果一致。
工具结果尚未处理完成时，不要重复发送原始任务，否则同一工具可能重复执行。
处理 Session 错误
session.error 不一定由工具配置引起。先读取 error.type、error.message 和 error.retry_status.type，并结合错误前的最后一个事件定位问题。
重试状态 | 处理方式 |
retrying | 服务端正在自动重试。继续消费事件，不要重复发送任务。 |
exhausted | 当前轮次的重试次数已用尽。等待 Session 恢复为 idle，修正输入或配置后再发送任务。 |
terminal | Session 将进入 terminated，不能继续发送事件。修正配置后创建新 Session。 |
如果错误发生在 MCP 调用阶段，按错误类型继续检查：
- mcp_authentication_failed_error：检查 MCP Server 的鉴权配置、Session 引用的 Vaults 和凭据有效性。
- mcp_connection_failed_error：检查 MCP Server URL、网络连通性和服务状态。
修正 MCP 配置后，更新 Agent，并创建新 Session 或升级现有 Session。如果 error.type 不是 MCP 相关类型，且错误前没有工具调用事件，优先排查模型调用或 Session 运行问题，不要把所有 session.error 都归因于工具。事件字段和其他错误类型请参见 会话事件结构参考。
核对文件和网络隔离
注意
关闭 write、edit、web_fetch 或 web_search 不等于完成强隔离。read、glob 和 grep 仍可能访问敏感文件；如果 Agent 仍可使用 bash，或者 Environment 允许不受限联网，命令仍可能读取或修改文件并访问网络。需要强隔离时，同时收敛内置工具、Environment 文件和网络策略，以及外部凭据权限。
相关文档
Agent
Agent 是包含基本信息、System Prompt、扩展能力的配置模板。
Skills
Skills 用于给 Agent 补充领域知识、操作流程和最佳实践。
MCP
MCP（Model Context Protocol）用于把第三方系统的工具与数据源接入 Agent。
工具权限策略
工具权限策略用于控制 Agent 发起工具调用时，是自动执行，还是暂停等待确认。
最近更新时间：2026.10.06 18:43:23
这个页面对您有帮助吗？
有用
有用
无用
无用