面向 AI 助手:本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/list-agents-api.md,全部文档索引见 https://ark.volcengine.com/llms.txt。

查询智能体列表

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 参数;已到最后一页时不返回该字段。