GET https://ark.cn-beijing.volces.com/api/v3/sessions
分页查询当前账号下的会话列表,支持按归档状态、智能体、状态、标签和创建时间过滤。每条结果包含该会话当前可见的智能体、环境、资源和标签信息。
鉴权#
本接口支持鉴权方式如下,详情请参见 Base URL 及鉴权。
- API Key 鉴权,请在 API Key 管理 页面,获取长效 API Key。
请求参数#
Query 参数#
在 URL Query String 中传入。
agent_id string | 智能体 ID
按智能体 ID 过滤,只返回指定智能体的会话
created_at_gt string | 创建时间下界(不含)
创建时间大于此值(ISO 8601),不含边界
created_at_gte string | 创建时间下界(含)
创建时间大于等于此值(ISO 8601),含边界
created_at_lt string | 创建时间上界(不含)
创建时间小于此值(ISO 8601),不含边界
created_at_lte string | 创建时间上界(含)
创建时间小于等于此值(ISO 8601),含边界
deployment_id string | 部署 ID
按部署 ID 过滤,只返回由该 Deployment 创建的会话。普通会话不命中该条件。
ids string | 会话 ID 列表
按会话 ID 过滤,多个 ID 用逗号分隔,最多 100 个。与其他筛选项取交集。
include_archived boolean 默认值 false | 包含已归档会话
是否在结果中包含已归档的会话。
- 省略或设为
false:只返回archived_at未返回且status不为terminated(已终止)的会话。 - 设为
true:不按终止状态和archived_at排除会话。历史上已经终止但无法恢复终止时间的会话可能不返回archived_at。
limit integer 默认值 20 | 每页数量
单页返回的会话数量。
取值范围:[1, 100]
memory_store_id string | 记忆库 ID
按已挂载的记忆库筛选,仅返回资源列表中包含指定 memory_store_id 的会话。
order string 默认值 desc | 排序方向
排序方向。asc 表示按创建时间升序,desc 表示按创建时间降序。
page string | 下一页标识
下一页标识。首次请求时省略;后续将上一次响应的 next_page 原样传入,并保持 order 与过滤条件不变。
scene string | 会话场景
按会话场景标记过滤。省略或传空值时不过滤。
常用值为 default 和 dreams。传入其他值不会报错,但会返回空列表。
status string[] | 会话状态
按会话运行状态过滤。可重复传入该参数;服务端返回匹配任一状态的会话。可选值:idle、running、terminated、rescheduling、initializing、failed、upgrading。
tags object[] | 标签过滤
按标签过滤,格式为 tags[<KEY>]=<VALUE>,例如 tags[team]=agent-infra。多个不同标签之间取交集;值为空时仅按标签键匹配。
key string 必选 | 标签键
tags.key
标签键,用于分类和检索
value string | 标签值
tags.value
用于记录该标签分类的具体内容。
响应参数#
data object[] | 会话列表
匹配查询条件的会话列表,按 order 指定的方向排序。默认按创建时间降序返回,即最新创建的会话在前;无匹配结果时返回空数组 []。
agent object | 智能体信息
data.agent
会话创建时保存的智能体配置快照。后续更新智能体不会影响该会话中的快照。
created_at string | 创建时间
data.agent.created_at
智能体创建完成的时间,采用 RFC 3339 格式。
id string | 智能体 ID
data.agent.id
智能体唯一标识符
name string | 智能体名称
data.agent.name
智能体名称,用于用户识别和管理
type string | 对象类型
data.agent.type
对象类型,固定为agent
updated_at string | 更新时间
data.agent.updated_at
智能体配置最后更新的时间,采用 RFC 3339 格式。
version integer | 版本号
data.agent.version
会话创建时冻结的智能体版本号。
base_agent string | 基础智能体类型
data.agent.base_agent
会话当前使用的基础 Agent 类型。
ark_agent_preview:通用 Agent。ultra_vision_agent_preview:Seedance Managed Agent。
context_management object[] | 上下文管理
data.agent.context_management
创建会话时冻结的上下文管理策略。Session 响应会在快照未保存自定义策略或已保存策略未包含 compact_threshold 时,展示平台当前默认压缩策略或默认阈值;当前默认阈值为 192000 token。
响应中的默认展示值不会写回 Session 快照。显式保存的 compact_threshold 优先返回。
type string | 策略类型
data.agent.context_management.type
策略类型,固定为 compaction。
compact_threshold integer | 压缩阈值
data.agent.context_management.compact_threshold
查询响应展示的自动压缩触发阈值,单位为 token。未显式保存时,对外接口响应会填充平台当前默认值,当前默认值为 192000;该展示值不会写回 Agent 版本或 Session 快照。
instructions string | 摘要指令
data.agent.context_management.instructions
用户配置的压缩摘要指令。
description string | 智能体描述
data.agent.description
智能体描述,用于说明智能体的用途、能力范围、适用场景等
display_name string | 显示名称
data.agent.display_name
会话当前使用的智能体显示名称。
mcp_servers object[] | MCP 服务列表
data.agent.mcp_servers
已配置的 MCP 服务列表
name string | MCP 服务名称
data.agent.mcp_servers.name
MCP 服务名称,供 tools[].mcp_server_name 引用。
type string | MCP 接入方式
data.agent.mcp_servers.type
MCP 服务接入方式,固定为 url。
url string | MCP 服务地址
data.agent.mcp_servers.url
会话创建时冻结的 MCP 服务访问地址。
metadata object | 自定义元数据
data.agent.metadata
创建智能体时设置的自定义键值对,服务端不定义固定子字段。
model object | 模型配置
data.agent.model
智能体使用的模型配置,包含模型或推理接入点 ID 与推理速度档位。
id string | 模型或接入点 ID
data.agent.model.id
智能体调用的模型 ID 或推理接入点 ID。例如模型 ID doubao-seed-2-1-pro-260628,或推理接入点 ID ep-20260907123456-abcd1。
reasoning_effort string | 推理投入档位
data.agent.model.reasoning_effort
会话当前使用的推理投入档位。
service_tier string | 推理服务档位
data.agent.model.service_tier
会话当前使用的推理服务档位。
speed string 默认值 standard | 推理速度
data.agent.model.speed
推理速度模式。可选值:standard、fast。
thinking string | 思考模式
data.agent.model.thinking
会话当前使用的思考模式。
multiagent object | 多智能体配置
data.agent.multiagent
会话当前使用的多智能体配置。
type string | 协作模式
data.agent.multiagent.type
多智能体协作模式。multiagent_20261001 使用 subagents;coordinator 使用 agents。
agents object[] | 成员智能体
data.agent.multiagent.agents
当 type 为 coordinator 时,返回会话创建时冻结的成员智能体列表。
type string | 引用类型
data.agent.multiagent.agents.type
成员引用类型:
agent:引用创建 Session 时冻结的其他智能体配置。self:使用当前智能体在创建会话时的有效配置。
context_management object[] | 上下文管理
data.agent.multiagent.agents.context_management
创建会话时冻结的成员智能体上下文管理策略。Session 响应会在成员快照未保存自定义策略或已保存策略未包含 compact_threshold 时,展示平台当前默认压缩策略或默认阈值;当前默认阈值为 192000 token。
响应中的默认展示值不会写回 Session 快照。显式保存的 compact_threshold 优先返回。
type string | 策略类型
data.agent.multiagent.agents.context_management.type
策略类型,固定为 compaction。
compact_threshold integer | 压缩阈值
data.agent.multiagent.agents.context_management.compact_threshold
查询响应展示的自动压缩触发阈值,单位为 token。未显式保存时,对外接口响应会填充平台当前默认值,当前默认值为 192000;该展示值不会写回 Agent 版本或 Session 快照。
instructions string | 摘要指令
data.agent.multiagent.agents.context_management.instructions
用户配置的压缩摘要指令。
description string | 智能体说明
data.agent.multiagent.agents.description
会话创建时冻结的成员智能体说明。
display_name string | 显示名称
data.agent.multiagent.agents.display_name
会话创建时冻结的成员智能体显示名称。
id string | 智能体 ID
data.agent.multiagent.agents.id
成员智能体的 ID;当 type 为 self 时,返回当前智能体的 ID。
mcp_servers object[] | MCP 服务列表
data.agent.multiagent.agents.mcp_servers
会话创建时冻结的成员智能体 MCP 服务配置列表。
name string | MCP 服务名称
data.agent.multiagent.agents.mcp_servers.name
MCP 服务名称,供 tools[].mcp_server_name 引用。
type string | MCP 接入方式
data.agent.multiagent.agents.mcp_servers.type
MCP 服务接入方式,固定为 url。
url string | MCP 服务地址
data.agent.multiagent.agents.mcp_servers.url
会话创建时冻结的 MCP 服务访问地址。
model object | 模型配置
data.agent.multiagent.agents.model
会话创建时冻结的成员智能体模型配置。
id string | 模型或接入点 ID
data.agent.multiagent.agents.model.id
成员智能体使用的模型 ID 或推理接入点 ID。
reasoning_effort string | 推理投入档位
data.agent.multiagent.agents.model.reasoning_effort
成员智能体当前使用的推理投入档位。
service_tier string | 推理服务档位
data.agent.multiagent.agents.model.service_tier
成员智能体当前使用的推理服务档位。
speed string | 推理速度
data.agent.multiagent.agents.model.speed
成员智能体使用的模型推理速度档位。
thinking string | 思考模式
data.agent.multiagent.agents.model.thinking
成员智能体当前使用的思考模式。
name string | 智能体名称
data.agent.multiagent.agents.name
会话创建时冻结的成员智能体名称。
skills object[] | Skill 列表
data.agent.multiagent.agents.skills
会话创建时冻结的成员智能体 Skill 配置列表。
type string | Skill 类型
data.agent.multiagent.agents.skills.type
Skill 来源类型:
ark:方舟平台预置 Skill。skill_hub:Skill Hub 中的公共 Skill。custom:当前账号创建的自定义 Skill。
display_name string | Skill 名称
data.agent.multiagent.agents.skills.display_name
会话创建时记录的 Skill 展示名称。
skill_id string | Skill ID
data.agent.multiagent.agents.skills.skill_id
会话使用的 Skill ID。
use_latest boolean | 使用最新版本
data.agent.multiagent.agents.skills.use_latest
是否在创建会话时选择该 Skill 的最新版本。true 表示选择当时的最新版本,false 表示使用 version 指定的版本。
version string | Skill 版本
data.agent.multiagent.agents.skills.version
会话创建时冻结的 Skill 版本号。
system string | 系统提示词
data.agent.multiagent.agents.system
会话创建时冻结的成员智能体系统提示词。
tools object[] | 工具列表
data.agent.multiagent.agents.tools
会话创建时冻结的成员智能体工具配置列表。
type string | 工具类型
data.agent.multiagent.agents.tools.type
工具类型:
agent_toolset_20260916:当前版本的方舟内置工具集。agent_toolset_multimodal_20260825:使用image_generate、video_generate、visual_search、general_search、compose_video和todo_write工具。mcp_toolset:指定 MCP 服务提供的工具集。custom:由客户端执行的自定义工具。
可选值:agent_toolset_20260916、agent_toolset_20260701、agent_toolset_multimodal_20260825、mcp_toolset、custom。
configs object[] | 工具配置
data.agent.multiagent.agents.tools.configs
会话创建时冻结的逐项工具配置。
name string | 工具名称
data.agent.multiagent.agents.tools.configs.name
会话快照中记录的工具名称。
enabled boolean | 是否启用
data.agent.multiagent.agents.tools.configs.enabled
工具是否启用。
models object[] | 工具模型列表
data.agent.multiagent.agents.tools.configs.models
会话快照中记录的图片生成或视频生成工具模型 ID 或推理接入点 ID 列表。
id string | 模型或接入点 ID
data.agent.multiagent.agents.tools.configs.models.id
该工具绑定的模型 ID 或推理接入点 ID。
default boolean | 是否为默认模型
data.agent.multiagent.agents.tools.configs.models.default
是否为该工具的默认模型。
name string | 模型名称
data.agent.multiagent.agents.tools.configs.models.name
模型 ID 或推理接入点 ID 对应的模型名称。
version string | 模型版本
data.agent.multiagent.agents.tools.configs.models.version
模型 ID 或推理接入点 ID 对应的模型版本。
permission_policy object | 权限策略
data.agent.multiagent.agents.tools.configs.permission_policy
工具使用的调用许可策略。
type string | 策略类型
data.agent.multiagent.agents.tools.configs.permission_policy.type
策略类型,always_allow 表示允许直接调用,always_ask 表示每次调用前需要用户确认。
default_config object | 默认工具配置
data.agent.multiagent.agents.tools.default_config
未在 configs 中单独列出的工具所使用的默认配置。
enabled boolean | 是否启用
data.agent.multiagent.agents.tools.default_config.enabled
未单独配置的工具是否默认启用。
permission_policy object | 权限策略
data.agent.multiagent.agents.tools.default_config.permission_policy
未单独配置的工具使用的调用许可策略。
type string | 策略类型
data.agent.multiagent.agents.tools.default_config.permission_policy.type
策略类型,always_allow 表示允许直接调用,always_ask 表示每次调用前需要用户确认。
description string | 自定义工具说明
data.agent.multiagent.agents.tools.description
会话创建时冻结的自定义工具说明,用于记录工具的功能和适用场景。
input_schema object | 输入参数定义
data.agent.multiagent.agents.tools.input_schema
返回 Session 的 Agent 快照中记录的自定义工具输入参数 JSON Schema。
properties object | 参数属性定义
data.agent.multiagent.agents.tools.input_schema.properties
返回 Session 的 Agent 快照中记录的 JSON Schema 属性映射。每个键为参数名,每个值为对应参数的 JSON Schema 子对象。
required string[] | 必填参数名称列表
data.agent.multiagent.agents.tools.input_schema.required
返回调用自定义工具时必须提供的参数名称列表。
type string | Schema 类型
data.agent.multiagent.agents.tools.input_schema.type
返回 JSON Schema 的顶层类型,固定为 object。
mcp_server_name string | MCP 服务名称
data.agent.multiagent.agents.tools.mcp_server_name
会话中 mcp_toolset 引用的 MCP 服务名称。
name string | 自定义工具名称
data.agent.multiagent.agents.tools.name
会话创建时冻结的自定义工具名称。
version integer | 版本号
data.agent.multiagent.agents.version
会话创建时冻结的成员智能体版本号。
subagents object | Subagent 配置
data.agent.multiagent.subagents
当 type 为 multiagent_20261001 时,返回会话创建时冻结的 Subagent 配置。
type string | Subagent 开关
data.agent.multiagent.subagents.type
是否允许当前 Agent 创建 Subagent。可选值:enabled、disabled。
inline_agents object | Inline Agent 配置
data.agent.multiagent.subagents.inline_agents
运行时 Inline Agent 配置。
type string | Inline Agent 开关
data.agent.multiagent.subagents.inline_agents.type
是否允许在运行时按名称和系统指令创建 Inline Agent。可选值:enabled、disabled。
predefined_agents object[] | 预定义成员
data.agent.multiagent.subagents.predefined_agents
会话创建时为 multiagent_20261001 冻结的预定义 Agent 和 Self 列表。
- 被引用 Agent 使用
multiagent_20261001时,可以在 Session 深度限制内继续冻结其下级成员。 - 被引用 Agent 使用
coordinator时,按叶子成员处理。
type string | 引用类型
data.agent.multiagent.subagents.predefined_agents.type
成员引用类型:
agent:引用创建 Session 时冻结的其他智能体配置。self:使用当前智能体在创建会话时的有效配置。
context_management object[] | 上下文管理
data.agent.multiagent.subagents.predefined_agents.context_management
创建会话时冻结的成员智能体上下文管理策略。Session 响应会在成员快照未保存自定义策略或已保存策略未包含 compact_threshold 时,展示平台当前默认压缩策略或默认阈值;当前默认阈值为 192000 token。
响应中的默认展示值不会写回 Session 快照。显式保存的 compact_threshold 优先返回。
type string | 策略类型
data.agent.multiagent.subagents.predefined_agents.context_management.type
策略类型,固定为 compaction。
compact_threshold integer | 压缩阈值
data.agent.multiagent.subagents.predefined_agents.context_management.compact_threshold
查询响应展示的自动压缩触发阈值,单位为 token。未显式保存时,对外接口响应会填充平台当前默认值,当前默认值为 192000;该展示值不会写回 Agent 版本或 Session 快照。
instructions string | 摘要指令
data.agent.multiagent.subagents.predefined_agents.context_management.instructions
用户配置的压缩摘要指令。
description string | 智能体说明
data.agent.multiagent.subagents.predefined_agents.description
会话创建时冻结的成员智能体说明。
display_name string | 显示名称
data.agent.multiagent.subagents.predefined_agents.display_name
会话创建时冻结的成员智能体显示名称。
id string | 智能体 ID
data.agent.multiagent.subagents.predefined_agents.id
成员智能体的 ID;当 type 为 self 时,返回当前智能体的 ID。
mcp_servers object[] | MCP 服务列表
data.agent.multiagent.subagents.predefined_agents.mcp_servers
会话创建时冻结的成员智能体 MCP 服务配置列表。
name string | MCP 服务名称
data.agent.multiagent.subagents.predefined_agents.mcp_servers.name
MCP 服务名称,供 tools[].mcp_server_name 引用。
type string | MCP 接入方式
data.agent.multiagent.subagents.predefined_agents.mcp_servers.type
MCP 服务接入方式,固定为 url。
url string | MCP 服务地址
data.agent.multiagent.subagents.predefined_agents.mcp_servers.url
会话创建时冻结的 MCP 服务访问地址。
model object | 模型配置
data.agent.multiagent.subagents.predefined_agents.model
会话创建时冻结的成员智能体模型配置。
id string | 模型或接入点 ID
data.agent.multiagent.subagents.predefined_agents.model.id
成员智能体使用的模型 ID 或推理接入点 ID。
reasoning_effort string | 推理投入档位
data.agent.multiagent.subagents.predefined_agents.model.reasoning_effort
成员智能体当前使用的推理投入档位。
service_tier string | 推理服务档位
data.agent.multiagent.subagents.predefined_agents.model.service_tier
成员智能体当前使用的推理服务档位。
speed string | 推理速度
data.agent.multiagent.subagents.predefined_agents.model.speed
成员智能体使用的模型推理速度档位。
thinking string | 思考模式
data.agent.multiagent.subagents.predefined_agents.model.thinking
成员智能体当前使用的思考模式。
name string | 智能体名称
data.agent.multiagent.subagents.predefined_agents.name
会话创建时冻结的成员智能体名称。
skills object[] | Skill 列表
data.agent.multiagent.subagents.predefined_agents.skills
会话创建时冻结的成员智能体 Skill 配置列表。
type string | Skill 类型
data.agent.multiagent.subagents.predefined_agents.skills.type
Skill 来源类型:
ark:方舟平台预置 Skill。skill_hub:Skill Hub 中的公共 Skill。custom:当前账号创建的自定义 Skill。
display_name string | Skill 名称
data.agent.multiagent.subagents.predefined_agents.skills.display_name
会话创建时记录的 Skill 展示名称。
skill_id string | Skill ID
data.agent.multiagent.subagents.predefined_agents.skills.skill_id
会话使用的 Skill ID。
use_latest boolean | 使用最新版本
data.agent.multiagent.subagents.predefined_agents.skills.use_latest
是否在创建会话时选择该 Skill 的最新版本。true 表示选择当时的最新版本,false 表示使用 version 指定的版本。
version string | Skill 版本
data.agent.multiagent.subagents.predefined_agents.skills.version
会话创建时冻结的 Skill 版本号。
system string | 系统提示词
data.agent.multiagent.subagents.predefined_agents.system
会话创建时冻结的成员智能体系统提示词。
tools object[] | 工具列表
data.agent.multiagent.subagents.predefined_agents.tools
会话创建时冻结的成员智能体工具配置列表。
type string | 工具类型
data.agent.multiagent.subagents.predefined_agents.tools.type
工具类型:
agent_toolset_20260916:当前版本的方舟内置工具集。agent_toolset_multimodal_20260825:使用image_generate、video_generate、visual_search、general_search、compose_video和todo_write工具。mcp_toolset:指定 MCP 服务提供的工具集。custom:由客户端执行的自定义工具。
可选值:agent_toolset_20260916、agent_toolset_20260701、agent_toolset_multimodal_20260825、mcp_toolset、custom。
configs object[] | 工具配置
data.agent.multiagent.subagents.predefined_agents.tools.configs
会话创建时冻结的逐项工具配置。
name string | 工具名称
data.agent.multiagent.subagents.predefined_agents.tools.configs.name
会话快照中记录的工具名称。
enabled boolean | 是否启用
data.agent.multiagent.subagents.predefined_agents.tools.configs.enabled
工具是否启用。
models object[] | 工具模型列表
data.agent.multiagent.subagents.predefined_agents.tools.configs.models
会话快照中记录的图片生成或视频生成工具模型 ID 或推理接入点 ID 列表。
id string | 模型或接入点 ID
data.agent.multiagent.subagents.predefined_agents.tools.configs.models.id
该工具绑定的模型 ID 或推理接入点 ID。
default boolean | 是否为默认模型
data.agent.multiagent.subagents.predefined_agents.tools.configs.models.default
是否为该工具的默认模型。
name string | 模型名称
data.agent.multiagent.subagents.predefined_agents.tools.configs.models.name
模型 ID 或推理接入点 ID 对应的模型名称。
version string | 模型版本
data.agent.multiagent.subagents.predefined_agents.tools.configs.models.version
模型 ID 或推理接入点 ID 对应的模型版本。
permission_policy object | 权限策略
data.agent.multiagent.subagents.predefined_agents.tools.configs.permission_policy
工具使用的调用许可策略。
type string | 策略类型
data.agent.multiagent.subagents.predefined_agents.tools.configs.permission_policy.type
策略类型,always_allow 表示允许直接调用,always_ask 表示每次调用前需要用户确认。
default_config object | 默认工具配置
data.agent.multiagent.subagents.predefined_agents.tools.default_config
未在 configs 中单独列出的工具所使用的默认配置。
enabled boolean | 是否启用
data.agent.multiagent.subagents.predefined_agents.tools.default_config.enabled
未单独配置的工具是否默认启用。
permission_policy object | 权限策略
data.agent.multiagent.subagents.predefined_agents.tools.default_config.permission_policy
未单独配置的工具使用的调用许可策略。
type string | 策略类型
data.agent.multiagent.subagents.predefined_agents.tools.default_config.permission_policy.type
策略类型,always_allow 表示允许直接调用,always_ask 表示每次调用前需要用户确认。
description string | 自定义工具说明
data.agent.multiagent.subagents.predefined_agents.tools.description
会话创建时冻结的自定义工具说明,用于记录工具的功能和适用场景。
input_schema object | 输入参数定义
data.agent.multiagent.subagents.predefined_agents.tools.input_schema
返回 Session 的 Agent 快照中记录的自定义工具输入参数 JSON Schema。
properties object | 参数属性定义
data.agent.multiagent.subagents.predefined_agents.tools.input_schema.properties
返回 Session 的 Agent 快照中记录的 JSON Schema 属性映射。每个键为参数名,每个值为对应参数的 JSON Schema 子对象。
required string[] | 必填参数名称列表
data.agent.multiagent.subagents.predefined_agents.tools.input_schema.required
返回调用自定义工具时必须提供的参数名称列表。
type string | Schema 类型
data.agent.multiagent.subagents.predefined_agents.tools.input_schema.type
返回 JSON Schema 的顶层类型,固定为 object。
mcp_server_name string | MCP 服务名称
data.agent.multiagent.subagents.predefined_agents.tools.mcp_server_name
会话中 mcp_toolset 引用的 MCP 服务名称。
name string | 自定义工具名称
data.agent.multiagent.subagents.predefined_agents.tools.name
会话创建时冻结的自定义工具名称。
version integer | 版本号
data.agent.multiagent.subagents.predefined_agents.version
会话创建时冻结的成员智能体版本号。
scene string | 场景标记
data.agent.scene
会话智能体快照所属的业务场景。
default:默认场景。dreams:用于记忆整理任务的场景。
skills object[] | 技能列表
data.agent.skills
会话创建时冻结的 Skill 配置列表。
type string | Skill 类型
data.agent.skills.type
Skill 来源类型:
ark:方舟平台预置 Skill。skill_hub:Skill Hub 中的公共 Skill。custom:当前账号创建的自定义 Skill。
display_name string | Skill 名称
data.agent.skills.display_name
会话创建时记录的 Skill 展示名称。
skill_id string | Skill ID
data.agent.skills.skill_id
会话使用的 Skill ID。
use_latest boolean | 使用最新版本
data.agent.skills.use_latest
是否在创建会话时选择该 Skill 的最新版本。true 表示选择当时的最新版本,false 表示使用 version 指定的版本。
version string | Skill 版本
data.agent.skills.version
会话创建时冻结的 Skill 版本号。
system string | 系统提示词
data.agent.system
系统提示词,定义智能体的角色和行为规则
tools object[] | 工具列表
data.agent.tools
已配置的工具列表
type string | 工具类型
data.agent.tools.type
工具类型:
agent_toolset_20260916:当前版本的方舟内置工具集。agent_toolset_multimodal_20260825:使用image_generate、video_generate、visual_search、general_search、compose_video和todo_write工具。mcp_toolset:指定 MCP 服务提供的工具集。custom:由客户端执行的自定义工具。
可选值:agent_toolset_20260916、agent_toolset_20260701、agent_toolset_multimodal_20260825、mcp_toolset、custom。
configs object[] | 工具配置
data.agent.tools.configs
会话创建时冻结的逐项工具配置。
name string | 工具名称
data.agent.tools.configs.name
会话快照中记录的工具名称。
enabled boolean | 是否启用
data.agent.tools.configs.enabled
工具是否启用。
models object[] | 工具模型列表
data.agent.tools.configs.models
会话快照中记录的图片生成或视频生成工具模型 ID 或推理接入点 ID 列表。
id string | 模型或接入点 ID
data.agent.tools.configs.models.id
该工具绑定的模型 ID 或推理接入点 ID。
default boolean | 是否为默认模型
data.agent.tools.configs.models.default
是否为该工具的默认模型。
name string | 模型名称
data.agent.tools.configs.models.name
模型 ID 或推理接入点 ID 对应的模型名称。
version string | 模型版本
data.agent.tools.configs.models.version
模型 ID 或推理接入点 ID 对应的模型版本。
permission_policy object | 权限策略
data.agent.tools.configs.permission_policy
工具使用的调用许可策略。
type string | 策略类型
data.agent.tools.configs.permission_policy.type
策略类型,always_allow 表示允许直接调用,always_ask 表示每次调用前需要用户确认。
default_config object | 默认工具配置
data.agent.tools.default_config
未在 configs 中单独列出的工具所使用的默认配置。
enabled boolean | 是否启用
data.agent.tools.default_config.enabled
未单独配置的工具是否默认启用。
permission_policy object | 权限策略
data.agent.tools.default_config.permission_policy
未单独配置的工具使用的调用许可策略。
type string | 策略类型
data.agent.tools.default_config.permission_policy.type
策略类型,always_allow 表示允许直接调用,always_ask 表示每次调用前需要用户确认。
description string | 自定义工具说明
data.agent.tools.description
会话创建时冻结的自定义工具说明,用于记录工具的功能和适用场景。
input_schema object | 输入参数定义
data.agent.tools.input_schema
返回 Session 的 Agent 快照中记录的自定义工具输入参数 JSON Schema。
properties object | 参数属性定义
data.agent.tools.input_schema.properties
返回 Session 的 Agent 快照中记录的 JSON Schema 属性映射。每个键为参数名,每个值为对应参数的 JSON Schema 子对象。
required string[] | 必填参数名称列表
data.agent.tools.input_schema.required
返回调用自定义工具时必须提供的参数名称列表。
type string | Schema 类型
data.agent.tools.input_schema.type
返回 JSON Schema 的顶层类型,固定为 object。
mcp_server_name string | MCP 服务名称
data.agent.tools.mcp_server_name
会话中 mcp_toolset 引用的 MCP 服务名称。
name string | 自定义工具名称
data.agent.tools.name
会话创建时冻结的自定义工具名称。
created_at string | 创建时间
data.created_at
会话创建完成的时间,采用 RFC 3339 格式。
environment_id string | 环境 ID
data.environment_id
会话实际使用的 Environment ID。
id string | 会话 ID
data.id
会话唯一标识符,格式为 sesn-xxxxx。
stats object | 时长统计
data.stats
会话的累计运行时长与生命周期总时长。
active_seconds number | 累计运行时长
data.stats.active_seconds
会话处于运行状态的累计秒数,与 usage.active_seconds 相同。
仅统计已结束的运行区间;当前尚未结束的 running 区间暂不计入。
duration_seconds number | 会话总时长
data.stats.duration_seconds
会话从创建到当前查询时刻的总时长,单位为秒。会话终止后,返回从创建到终止的时长。
status string | 会话状态
data.status
会话运行状态。可选值:idle、running、terminated、rescheduling、initializing、failed、upgrading。
type string | 对象类型
data.type
对象类型,固定为session
updated_at string | 更新时间
data.updated_at
会话信息最后更新的时间,采用 RFC 3339 格式。
archived_at string | 归档时间
data.archived_at
会话首次归档的时间,采用 RFC 3339 格式的 UTC 时间。调用归档接口时,服务端会将 idle 会话转为 terminated。
deployment_id string | 部署 ID
data.deployment_id
创建该会话的 Deployment ID。仅由 Deployment 创建的会话返回;其他方式创建的会话不返回该字段。
environment object | 环境信息
data.environment
会话实际使用的环境配置快照。后续修改原 Environment 不会改变该快照。
created_at string | 创建时间
data.environment.created_at
环境创建完成的时间,采用 RFC 3339 格式。
id string | 环境 ID
data.environment.id
环境唯一标识符
name string | 环境名称
data.environment.name
环境名称,用于在环境列表和会话配置中区分该环境。
type string | 对象类型
data.environment.type
会话环境快照类型。environment 表示直接使用基础 Environment;environment_with_overrides 表示当前会话使用了环境配置覆写。
updated_at string | 更新时间
data.environment.updated_at
环境配置最后更新的时间,采用 RFC 3339 格式。
config object | 环境配置
data.environment.config
环境运行配置,包含运行类型、网络策略、依赖包与环境变量
type string | 环境类型
data.environment.config.type
运行环境类型:cloud 表示平台托管环境,self_hosted 表示用户自托管环境。
build_script string | 构建脚本
data.environment.config.build_script
在依赖包安装后执行的构建脚本;为空表示未配置构建脚本。
env object | 环境变量
data.environment.config.env
会话运行环境中的环境变量键值对
networking object | 出网策略
data.environment.config.networking
容器出网策略配置
type string | 出网策略类型
data.environment.config.networking.type
会话当前使用的出网策略。可选值:unrestricted、limited。
allow_package_managers boolean | 允许包管理器
data.environment.config.networking.allow_package_managers
限定出网模式下,是否允许访问包管理器软件源。
allowed_hosts string[] | 允许的主机
data.environment.config.networking.allowed_hosts
限定出网模式下,允许沙箱直接访问的外部域名列表。
packages object | 依赖包配置
data.environment.config.packages
启动时预装的依赖包配置
apt string[] | apt 包
data.environment.config.packages.apt
会话环境启动时通过 apt 预装的系统包列表。
cargo string[] | Cargo 包
data.environment.config.packages.cargo
会话环境启动时通过 Cargo 预装的 Rust crate 列表。
gem string[] | gem 包
data.environment.config.packages.gem
会话环境启动时通过 RubyGems 预装的 Ruby 包列表。
go string[] | Go 模块
data.environment.config.packages.go
会话环境启动时通过 Go 工具链预装的模块依赖列表。
npm string[] | npm 包
data.environment.config.packages.npm
会话环境启动时通过 npm 预装的 Node.js 包列表。
pip string[] | pip 包
data.environment.config.packages.pip
会话环境启动时通过 pip 预装的 Python 包列表。
type string | 配置类型
data.environment.config.packages.type
依赖包配置的类型标识,固定为 packages。
setup_script string | 启动脚本
data.environment.config.setup_script
会话运行环境启动时执行的初始化脚本;留空或未设置表示不执行任何脚本
spec string 默认值 1x | 运行规格
data.environment.config.spec
会话使用的运行规格,控制沙箱的 CPU 与内存配置。可选值:1x、2x、4x、8x。
template_id string | 模板 ID
data.environment.config.template_id
会话环境当前使用的逻辑模板 ID。base 表示常规执行模板,browser 表示浏览器任务模板。
tos object | 产物存储配置
data.environment.config.tos
智能体产物持久化存储配置。为空表示未配置用户 Bucket,产物落到方舟公共 TOS
bucket string | TOS 桶
data.environment.config.tos.bucket
会话环境快照中保存的用户 TOS 存储桶名称。
prefix string | 对象前缀
data.environment.config.tos.prefix
会话环境快照中保存的对象存储目录前缀。
description string | 环境描述
data.environment.description
环境描述,用于说明环境的用途、网络策略、依赖包等配置
metadata object | 自定义元数据
data.environment.metadata
用户自定义元数据
overridden_fields string[] | 覆写字段
data.environment.overridden_fields
当前会话相对基础 Environment 实际覆写的 config 子字段名称列表。仅在 type 为 environment_with_overrides 且存在覆写字段时返回。
scene string | 场景标记
data.environment.scene
环境快照所属的业务场景。
default:默认场景。dreams:用于记忆整理任务的场景。
resources object[] | 资源列表
data.resources
会话当前挂载到运行环境的资源列表。
文件资源 object
通过 Files API 上传并挂载到会话的文件。
created_at string | 挂载时间
data.resources.created_at
资源挂载到会话的时间,采用 RFC 3339 格式。
id string | 资源 ID
data.resources.id
会话资源 ID。
type string | 资源类型
data.resources.type
资源类型,固定为 file。
updated_at string | 更新时间
data.resources.updated_at
会话资源信息最后更新的时间,采用 RFC 3339 格式。
access string | 访问权限
data.resources.access
文件访问权限,固定为 read_only。
file_id string | 文件 ID
data.resources.file_id
当前可用的文件 ID。
mount_path string | 挂载路径
data.resources.mount_path
文件在会话运行环境中的完整挂载路径。
记忆库资源 object
挂载到会话的记忆库。
created_at string | 挂载时间
data.resources.created_at
资源挂载到会话的时间,采用 RFC 3339 格式。
id string | 资源 ID
data.resources.id
会话资源 ID。
type string | 资源类型
data.resources.type
资源类型,固定为 memory_store。
updated_at string | 更新时间
data.resources.updated_at
会话资源信息最后更新的时间,采用 RFC 3339 格式。
access string | 访问权限
data.resources.access
会话对记忆库的访问权限。
-
read_only:智能体只能读取记忆库。 -
read_write:智能体可以读取和修改记忆库。
instructions string | 使用指导
data.resources.instructions
会话当前用于该记忆库的使用指导。
memory_store_id string | 记忆库 ID
data.resources.memory_store_id
挂载到会话的记忆库 ID。
TOS 资源 object
挂载到会话的 TOS 对象目录。
created_at string | 挂载时间
data.resources.created_at
资源挂载到会话的时间,采用 RFC 3339 格式。
id string | 资源 ID
data.resources.id
会话资源 ID。
type string | 资源类型
data.resources.type
资源类型,固定为 tos。
updated_at string | 更新时间
data.resources.updated_at
会话资源信息最后更新的时间,采用 RFC 3339 格式。
access string | 访问权限
data.resources.access
会话对 TOS 目录的访问权限。可选值:read_only、read_write。
mount_path string | 挂载路径
data.resources.mount_path
TOS 目录在会话运行环境中的挂载路径。创建会话时未指定挂载路径,则不返回该字段。
tos_bucket string | TOS 存储桶
data.resources.tos_bucket
TOS 挂载源所在的存储桶名称。
tos_key string | TOS 目录前缀
data.resources.tos_key
TOS 中已挂载目录的对象前缀。
tos_region string | TOS 地域
data.resources.tos_region
TOS 挂载源所在地域的 Region ID。
scene string | 会话场景
data.scene
会话场景标记。
default:普通会话。dreams:用于 Dream 记忆整理任务的会话。
tags object[] | 标签列表
data.tags
会话标签列表,每项包含 key 和可选的 value。
key string | 标签键
data.tags.key
标签键,用于分类和检索
value string | 标签值
data.tags.value
用于记录该标签分类的具体内容。
title string | 会话标题
data.title
会话标题,便于用户在会话列表中识别
vault_ids string[] / null | 保管库 ID 列表
data.vault_ids
会话绑定的保管库 ID 列表,智能体可访问其中的凭据
next_page string | 下一页标识
服务端返回的下一页标识。客户端无需解析,将此值原样作为下一次请求的 page 参数即可继续翻页;未返回此字段时表示已到最后一页。