GET https://ark.cn-beijing.volces.com/api/v3/agents
分页查询当前账号下的智能体。支持按归档状态、创建时间、名称和展示名称筛选,结果按创建时间从新到旧排列。
鉴权#
本接口支持鉴权方式如下,详情请参见 Base URL 及鉴权。
- API Key 鉴权,请在 API Key 管理 页面,获取长效 API Key。
请求参数#
Query 参数#
在 URL Query String 中传入。
created_at_gte string | 创建时间下界
按创建时间筛选,返回创建时间大于等于该值的智能体。使用 ISO 8601 格式。
created_at_lte string | 创建时间上界
按创建时间筛选,返回创建时间小于等于该值的智能体。使用 ISO 8601 格式。
display_name string | 展示名称
按智能体展示名称模糊匹配。与其他筛选参数同时传入时,返回同时满足所有条件的智能体。
include_archived boolean 默认值 false | 包含已归档智能体
是否在结果中包含已归档智能体。省略或设为 false 时,只返回未归档智能体;设为 true 时,同时返回已归档和未归档智能体。
limit integer 默认值 20 | 每页数量
每页返回的数量。
取值范围:[1, 100]
name string | 智能体名称
按智能体名称模糊匹配。与其他筛选参数同时传入时,返回同时满足所有条件的智能体。
page string | 下一页标识
下一页标识。
- 首次请求时省略。
- 后续请求将上一页响应中的
next_page原样传入。 - 该值不是页码,请勿解析或修改。
- 连续翻页时,应保持其他筛选参数不变。
响应参数#
data object[] | 智能体列表
当前页返回的智能体列表;无命中时返回空数组[]
created_at string | 创建时间
data.created_at
智能体创建时间,采用 RFC 3339 格式。
id string | 智能体 ID
data.id
智能体唯一标识,以 agent- 开头。创建会话或管理智能体时,需要使用该值。
name string | 智能体名称
data.name
用于识别和管理智能体的名称。
type string | 对象类型
data.type
返回对象的类型,表示该对象为智能体。
取值固定为 agent。
updated_at string | 更新时间
data.updated_at
智能体最后更新时间,采用 RFC 3339 格式。
version integer | 版本号
data.version
智能体配置版本号。
archived_at string | 归档时间
data.archived_at
智能体首次归档的时间,采用 RFC 3339 格式的 UTC 时间。智能体未归档时,不返回该字段。
base_agent string | 基础 Agent 类型
data.base_agent
智能体创建时确定的基础 Agent 类型。 Seedance Managed Agent 返回 ultra_vision_agent_preview。
可选值:ark_agent_preview、ultra_vision_agent_preview。
context_management object[] | 上下文管理
data.context_management
智能体版本的上下文管理策略。创建、更新或查询 Agent 的响应会在未保存自定义策略或已保存策略未包含 compact_threshold 时,展示平台当前默认压缩策略或默认阈值;当前默认阈值为 192000 token。
响应中的默认展示值不会写回 Agent 版本。显式保存的 compact_threshold 优先返回。
type string | 策略类型
data.context_management.type
策略类型,固定为 compaction。
compact_threshold integer | 压缩阈值
data.context_management.compact_threshold
查询响应展示的自动压缩触发阈值,单位为 token。未显式保存时,对外接口响应会填充平台当前默认值,当前默认值为 192000;该展示值不会写回 Agent 版本或 Session 快照。
instructions string | 摘要指令
data.context_management.instructions
用户配置的压缩摘要指令。
description string | 智能体描述
data.description
智能体的用途、能力范围和适用场景。
display_name string | 展示名称
data.display_name
智能体的展示名称。
mcp_servers object[] | MCP 服务列表
data.mcp_servers
智能体已配置的 MCP 服务列表。
name string | MCP 服务名称
data.mcp_servers.name
用于标识 MCP 服务的名称。
type string | 接入方式
data.mcp_servers.type
MCP 服务的接入方式。
取值固定为 url。
url string | 服务地址
data.mcp_servers.url
MCP 服务的访问地址。
metadata object | 自定义元数据
data.metadata
智能体的自定义键值对元数据。
model object | 模型配置
data.model
智能体使用的模型配置。
id string | 模型或接入点 ID
data.model.id
智能体调用的模型 ID 或推理接入点 ID。例如模型 ID doubao-seed-2-1-pro-260628,或推理接入点 ID ep-20260907123456-abcd1。
reasoning_effort string | 推理投入档位
data.model.reasoning_effort
模型在深度思考时使用的推理投入档位。可选值:none、minimal、low、medium、high、xhigh、max。
service_tier string | 推理服务档位
data.model.service_tier
模型调用使用的推理服务档位。可选值:auto、default、fast。
speed string | 推理速度档位
data.model.speed
模型使用的推理速度档位。可选值:standard、fast。
thinking string | 深度思考
data.model.thinking
模型的深度思考模式。auto 表示由模型决定是否启用深度思考。取值:enabled / disabled / auto。
multiagent object | 多智能体配置
data.multiagent
智能体与子智能体之间的协作配置。
type string | 协作模式
data.multiagent.type
多智能体协作模式:
multiagent_20261001:使用subagents配置预定义 Agent、Self 和 Inline Agent。coordinator:使用agents配置预定义 Agent 或 Self。
agents object[] | 子智能体列表
data.multiagent.agents
当 type 为 coordinator 时,返回子智能体列表;type 为 multiagent_20261001 时,返回空数组或省略该字段。
type string | 子智能体来源
data.multiagent.agents.type
子智能体的来源。agent 表示引用已存在的 Agent;self 表示复用拥有当前成员列表的智能体配置,但不继承其成员列表。Self 可用于 multiagent_20261001.predefined_agents 和 coordinator.agents;使用 Self 时不返回 id 和 version。
id string | 智能体 ID
data.multiagent.agents.id
被引用智能体的 ID。
version integer | 智能体版本
data.multiagent.agents.version
被引用智能体的版本号。
subagents object | Subagent 配置
data.multiagent.subagents
当 type 为 multiagent_20261001 时,返回 Subagent 配置。
type string | Subagent 开关
data.multiagent.subagents.type
是否允许当前 Agent 创建 Subagent。可选值:enabled、disabled。
inline_agents object | Inline Agent 配置
data.multiagent.subagents.inline_agents
运行时 Inline Agent 配置。
type string | Inline Agent 开关
data.multiagent.subagents.inline_agents.type
是否允许在运行时按名称和系统指令创建 Inline Agent。可选值:enabled、disabled。
predefined_agents object[] | 预定义成员
data.multiagent.subagents.predefined_agents
预定义 Agent 和 Self 列表。
type string | 子智能体来源
data.multiagent.subagents.predefined_agents.type
子智能体的来源。agent 表示引用已存在的 Agent;self 表示复用拥有当前成员列表的智能体配置,但不继承其成员列表。Self 可用于 multiagent_20261001.predefined_agents 和 coordinator.agents;使用 Self 时不返回 id 和 version。
id string | 智能体 ID
data.multiagent.subagents.predefined_agents.id
被引用智能体的 ID。
version integer | 智能体版本
data.multiagent.subagents.predefined_agents.version
被引用智能体的版本号。
skills object[] | 技能列表
data.skills
智能体已绑定的技能列表。
type string | 技能来源
data.skills.type
技能来源。
ark:方舟预置技能。skill_hub:来自 SkillHub 的公共技能。custom:当前账号通过 Skills API 创建的自定义技能。
skill_id string | 技能 ID
data.skills.skill_id
绑定到智能体的技能 ID。
version string | 技能版本
data.skills.version
绑定到智能体的技能版本号。
system string | 系统提示词
data.system
您为智能体配置并保存的系统提示词,用于定义智能体的角色和行为要求。
tags object[] | 标签列表
data.tags
智能体的标签列表。
key string | 标签键
data.tags.key
标签键,用于分类和检索。
value string | 标签值
data.tags.value
标签对应的值。
tools object[] | 工具列表
data.tools
您为智能体配置的工具列表。
type string | 工具类型
data.tools.type
工具类型。
agent_toolset_20260916:使用方舟内置的bash、edit、read、write、glob、grep、web_fetch和web_search工具。agent_toolset_multimodal_20260825:使用image_generate、video_generate、visual_search、general_search、compose_video和todo_write工具。mcp_toolset:使用指定 MCP 服务提供的工具。custom:使用由客户端执行的自定义工具。
可选值:agent_toolset_20260401、agent_toolset_20260701、agent_toolset_20260916、agent_toolset_multimodal_20260825、mcp_toolset、custom。
configs object[] | 工具配置列表
data.tools.configs
按工具名称设置工具的启用状态和权限策略。
name string | 工具名称
data.tools.configs.name
工具配置对应的工具名称。
enabled boolean | 是否启用
data.tools.configs.enabled
是否启用此工具。
models object[] | 工具模型列表
data.tools.configs.models
图片生成或视频生成工具实际绑定模型列表。
id string | 模型或接入点 ID
data.tools.configs.models.id
该工具绑定的模型 ID 或推理接入点 ID。
default boolean | 是否为默认模型
data.tools.configs.models.default
是否为该工具的默认模型。
name string | 模型名称
data.tools.configs.models.name
服务端根据模型 ID 或推理接入点 ID 返回的模型名称。
version string | 模型版本
data.tools.configs.models.version
服务端根据模型 ID 或推理接入点 ID 返回的模型版本。
permission_policy object | 权限策略
data.tools.configs.permission_policy
该工具使用的权限策略。
type string | 策略类型
data.tools.configs.permission_policy.type
工具调用许可策略。
always_allow:表示总是允许调用。always_ask:表示每次使用前需要确认。
default_config object | 默认工具配置
data.tools.default_config
未在 configs 中单独配置的工具所使用的默认启用状态和权限策略。
enabled boolean | 默认是否启用
data.tools.default_config.enabled
是否默认启用未在 configs 中单独配置的工具。
true:表示默认启用。false:表示默认禁用。
permission_policy object | 默认权限策略
data.tools.default_config.permission_policy
未在 configs 中单独配置的工具所使用的默认权限策略。
type string | 策略类型
data.tools.default_config.permission_policy.type
工具调用许可策略。
always_allow:表示总是允许调用。always_ask:表示每次使用前需要确认。
description string | 自定义工具描述
data.tools.description
说明自定义工具的功能和适用场景,供模型判断何时调用该工具。
input_schema object | 输入参数定义
data.tools.input_schema
返回 Agent 中保存的自定义工具输入参数 JSON Schema。
properties object | 参数属性定义
data.tools.input_schema.properties
返回 Agent 中保存的 JSON Schema 属性映射。每个键为参数名,每个值为对应参数的 JSON Schema 子对象。
required string[] | 必填参数名称列表
data.tools.input_schema.required
返回调用自定义工具时必须提供的参数名称列表。
type string | Schema 类型
data.tools.input_schema.type
返回 JSON Schema 的顶层类型,固定为 object。
mcp_server_name string | MCP 服务名称
data.tools.mcp_server_name
MCP 工具所属的 MCP 服务名称。
name string | 自定义工具名称
data.tools.name
自定义工具的名称。
next_page string | 下一页标识
下一页标识。将该值原样作为下一次请求的 page 参数;已到最后一页时不返回该字段。