Agent 结构

Agent 对象

创建、列表、更新、归档，以及不带 version 参数的 GET /v1/agents/{agent_id} 会返回该结构。

带 version 参数的 GET /v1/agents/{agent_id} 和 GET /v1/agents/{agent_id}/versions 会返回该结构。

tools[] 通过 type 区分不同结构。

字段	类型	适用类型	说明
`type`	string	全部	必填。可选值：`agent_toolset_20260401`、`mcp_toolset`、`custom`
`enabled_tools`	string 数组	`agent_toolset_20260401`	内置工具白名单。非空数组表示严格白名单；省略或传 `[]` 时使用默认内置工具集，并继续叠加 `disallowed_tools` 和 `configs[].enabled`。取值必须使用下方列出的内置工具名
`disallowed_tools`	string 数组	`agent_toolset_20260401`	要隐藏并拒绝的内置工具，取值必须使用下方列出的内置工具名。同一工具不能同时出现在 `enabled_tools` 和 `disallowed_tools`
`configs`	Tool config 数组	`agent_toolset_20260401`、`mcp_toolset`	单工具启用状态和权限规则。逐个工具的权限在这里通过 `permission_policy` 配置
`mcp_server_name`	string	`mcp_toolset`	必填。必须匹配某个 `mcp_servers[].name`
`name`	string	`custom`	必填的自定义工具名。不能与内置工具重名，也不能以 `mcp__` 开头
`description`	string	`custom`	必填的自定义工具描述
`input_schema`	object	`custom`	必填的 JSON Schema 对象，`input_schema.type` 必须为 `"object"`

custom 工具不支持 permission_policy；权限需要通过 agent_toolset_20260401 或 mcp_toolset 的 configs[].permission_policy 配置。

支持以下内置工具名：

用于 tools[].configs[]。

字段	类型	必填	说明
`name`	string	是	要配置的工具名。`agent_toolset_20260401` 使用内置工具名；`mcp_toolset` 使用该 MCP server 暴露的原始工具名
`enabled`	boolean	否	`false` 表示隐藏并拒绝该工具；`true` 表示显式启用该工具
`permission_policy`	Permission policy	否	该工具的运行时权限行为

字段	类型	必填	说明
`type`	string	是	可选值：`always_allow`、`always_ask`、`always_deny`

always_allow 表示直接执行；always_ask 表示暂停并等待 user.tool_confirmation；always_deny 表示返回被拒绝的工具结果。

用于 mcp_servers[]。

字段	类型	必填	说明
`name`	string	是	Agent 内唯一的 MCP server 名称
`type`	string	是	支持值：`"http"`
`url`	string	是	Streamable HTTP MCP endpoint URL

MCP server 鉴权通过 Vault 配置。

用于 skills[]。

创建可复用、可版本化的 Agent 配置。