内置工具集由平台默认提供。在智能体上声明 MCP 服务后其工具即对模型可用；
mcp_toolset 声明位于 tools 字段，用于调整这些工具的配置。本页介绍内置工具集、自定义工具，以及工具集共用的加载模式配置。
内置工具集
未显式声明agent_toolset 时，智能体默认加载 default_toolset_20260901 的全部沙箱工具。按类别划分如下：
要调整内置工具集的配置（包括按工具覆盖
enabled、permission_policy、result_hint、load_mode），需显式声明 agent_toolset；未声明时使用默认配置，无法单独调整。关闭沙箱工具时，也需显式声明工具集，并将 default_config.enabled 设为 false。工具集配置
agent_toolset 的 name 目前使用 default_toolset_20260901。未显式声明 agent_toolset 时，默认加载该工具集的全部沙箱工具；显式声明后只加载声明的工具集，不会追加默认值。
default_config 作用于工具集中的所有工具，configs 可按工具名覆盖这些默认值。权限相关字段与 权限策略 一致：enabled 控制工具是否暴露给模型；permission_policy 可取 always_allow 或 always_ask，未设置时默认启用并按 always_allow 评估。always_ask 会在 agent.tool_use 事件后暂停执行，等待客户端回复 user.tool_confirmation。禁用工具请使用 enabled: false。
下面的示例关闭整个内置沙箱工具集：
mcp_toolset，通过 mcp_server_name 指向智能体中声明的 MCP 服务。它同样支持 default_config 和 configs，其中 configs 只能覆盖 MCP 服务实际提供的工具。内置沙箱工具不在这里配置，仍由 agent_toolset 的 default_config 和 configs 管理。
限制与安全边界
内置工具对读写规模与执行时长设有上限，超限的调用会返回带原因说明的错误结果，模型通常会据此调整策略（例如分段读取），而不会中断会话：
文件读写和进程执行都发生在会话使用的云沙箱中，不同沙箱实例之间相互隔离。
实例本地文件可能在实例回收后丢失；挂载到会话的工作区、会话文件和 记忆库 可以跨实例保存，但采用异步写回，实例退出前尚未完成同步的最新写入仍可能丢失。
需要长期保留的关键产物，应使用
save_artifact 工具显式交付为不可变版本。
实例重建后，平台会自动把后续工具调用落到新实例上，客户端不需要额外处理。
沙箱网络与凭据
沙箱进程的出站网络由环境的网络策略控制，平台级工具不受该环境网络策略直接控制。环境可以额外配置代理，把指定的出站流量经自有代理转发；代理不等同于凭据注入。
凭据注入只覆盖经平台出口代理的 HTTP/HTTPS 流量（端口
80/443）；其他端口是否可访问由网络策略决定。凭据库（Vault）中的凭据不会注入所有出站请求，而是根据凭据类型和匹配规则注入或替换：MCP 凭据按 MCP 服务地址匹配；environment_variable 凭据按凭据自身的主机白名单和注入位置配置，在匹配的出站请求中替换占位符。
自定义工具
自定义工具由你的客户端执行。将工具声明写入智能体的tools 后，模型可以发起调用；平台通过事件流把工具名和输入参数交给客户端，客户端执行并回传结果，会话随后继续。
声明自定义工具
在tools 数组中添加 type 为 "custom" 的成员：
tools 最多包含 128 个声明。自定义工具名称不能重复，也不能与内置工具重名；input_schema.type 不是 object 时，创建请求会返回 400 invalid_parameter_error。
下面的示例创建一个只使用 lookup_order 自定义工具的智能体。示例显式关闭默认内置工具集，避免模型选择其他工具：
未声明
agent_toolset 时，智能体默认加载全部内置沙箱工具。只需要自定义工具时，请像示例一样显式声明内置工具集并设置 default_config.enabled: false。接收并执行工具调用
创建智能体后，按 启动会话 的说明创建会话、订阅 事件流 并发送用户消息。模型决定调用自定义工具时，事件流会发送agent.custom_tool_use：
id 作为 event_id，在本地执行工具后，通过 POST /v1/sessions/{session_id}/events 回传结果：
202。content 是按顺序排列的工具结果内容；is_error 表示工具调用是否失败，省略时默认为 false。
等待状态与恢复
等待客户端返回自定义工具结果或工具确认时，发起调用的线程暂停执行；会话中没有其他线程在运行时，session.status 事件的 data.status 为 idle，data.stop_reason.type 为 requires_action。event_ids 列出待处理事件 ID，既包括等待自定义工具结果的 agent.custom_tool_use，也包括等待工具确认的 agent.tool_use：
409 conflict_error。
多智能体会话中，等待只暂停发起调用的线程：其他线程仍在运行时，会话级 session.status 保持 running，等待状态体现在该线程的 session.thread_status 事件上。session.status 转为 idle 时，event_ids 汇总会话内全部等待线程；session.thread_status 只覆盖对应线程。线程级事件见 多智能体编排。
在单个会话中覆盖工具
创建会话时，可以通过agent_overrides.tools 整体替换冻结智能体版本的工具配置。自定义工具使用与智能体相同的声明和校验规则：
tools 采用整体替换语义，不会与冻结智能体版本中的工具数组合并。该覆盖只影响当前会话，不会修改智能体或产生新的智能体版本。
按需动态加载
工具集变大时（尤其是插件携带的 MCP 工具），把全部工具 schema 内联进每轮模型请求会显著占用上下文。工具集支持两种 schema 加载模式，通过load_mode 配置：
内置工具集中，
search_image_by_text 和 search_image_by_image 默认使用 on_demand，其余内置工具默认使用 eager。
按需加载的工作方式：
- 平台向模型播报按需工具的名字清单，但不提供参数 schema；
- 模型通过
select_tools元工具按名字加载需要的工具，schema 随即进入上下文； - 之后模型即可像普通工具一样调用它。
load_mode 同样支持两级配置：default_config.load_mode 作用于整个工具集，configs 中的 load_mode 按工具覆盖。不支持的模型会自动回退为全量内联，行为与未配置时一致，你无需为此调整代码。
select_tools 的加载动作会以普通的 agent.tool_use 事件出现在事件流中，客户端无需特殊处理。模型或提供方不支持按需加载时静默回退，不产生错误。下一步
接入 MCP 工具
通过 MCP 服务为智能体接入外部工具与数据。
配置工具权限策略
了解 enabled 与 permission_policy 的当前行为。
查看工具调用事件
订阅工具调用与结果事件，掌握每一步执行。