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

创建会话

POST https://ark.cn-beijing.volces.com/api/v3/sessions

创建会话并绑定指定的智能体与环境。创建时可为本次会话覆写智能体或 Environment 的部分配置。创建成功后，可使用返回的会话 ID 发送事件、查询状态、升级配置或删除会话。

调用前需先准备智能体和环境。如需挂载文件、记忆库或凭证，还需先通过对应接口创建资源并取得其 ID。

根据目标选择接口：

  • 需要新会话或更换绑定的智能体、环境时，使用本接口。
  • 只修改标题或标签时，使用 更新会话标题和标签。
  • 保留同一会话并刷新当前智能体、环境或保管库配置时，使用 升级会话。

单个智能体默认最多可同时拥有 1000 个活跃会话；达到配额时，创建会话接口返回 HTTP 429 SessionQuotaExceeded。实际配额可能因账号配置而不同。

鉴权#

本接口支持鉴权方式如下，详情请参见 Base URL 及鉴权。

  • API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。

请求参数#

Body 参数#

agent string / object 必选  |  智能体标识

指定会话使用的智能体。可直接传入智能体 ID；需要固定智能体版本时，传入智能体引用对象并设置 id 和 version。

需要为本次会话临时调整 Agent 配置时，传入 agent_with_overrides 对象。覆写仅写入会话的智能体快照，不修改基础 Agent。

智能体 ID string

直接传入智能体 ID，会话启动时使用该智能体的最新版本。

智能体引用 object

智能体引用对象。通过 id 指定智能体，通过 version 指定会话使用的智能体版本；省略 version 时使用最新版本。

id string 必选  |  智能体 ID

agent.id

要用于创建会话的智能体 ID。

type string 必选  |  引用类型

agent.type

引用类型，固定为 agent

version integer  |  版本号

agent.version

智能体版本号；省略时使用最新版本

智能体配置覆写 object

智能体配置覆写对象。以 id 指定的智能体版本为基础，覆写仅影响本次会话，不会创建新版本或修改基础 Agent。

  • 省略字段时，沿用基础 Agent 的对应配置。
  • 传入 system 时，替换本次会话中的系统提示词。
  • 传入 model 时，仅覆写其中已提供的子字段；省略的模型子字段沿用基础 Agent 的配置。
  • tools、mcp_servers 或 skills 传入 [] 时清空对应列表，传入非空数组时整体替换，不与基础配置合并。
  • 传入 multiagent 时，整体替换多智能体协作配置；其中 agents 传入 [] 时清空子智能体列表。
id string 必选  |  智能体 ID

agent.id

基础智能体 ID。缺失或为空时返回 HTTP 400 MissingParameter。

type string 必选  |  覆写类型

agent.type

覆写类型，固定为 agent_with_overrides

mcp_servers object[]  |  MCP 服务列表

agent.mcp_servers

本次会话使用的 MCP 服务列表。省略时保留原配置，传入 [] 时清空，传入非空数组时整体替换。

type string 必选  |  接入方式

agent.mcp_servers.type

MCP 服务的接入方式。

取值固定为 url。

url string 必选  |  服务地址

agent.mcp_servers.url

MCP 服务的访问地址。同一智能体内不能配置重复的 MCP 服务地址。

name string  |  MCP 服务名称

agent.mcp_servers.name

MCP 服务名称，最长 255 个字符，用于在当前 Agent 中识别该服务；配置 MCP 工具集时，tools[].mcp_server_name 必须填写此名称。

  • 省略名称或名称不符合命名规则时，服务端根据 url 生成名称。
  • 服务端会将符合命名规则的名称转换为小写。
  • 多个名称冲突时，服务端为后续名称添加数字后缀。
model object  |  模型运行参数覆写

agent.model

仅对本次会话生效的模型配置。支持设置 id、speed、service_tier、thinking 和 reasoning_effort；省略子字段时沿用基础智能体的对应配置。

id string  |  模型 ID 覆写

agent.model.id

本次会话使用的模型 ID。省略时沿用基础智能体的模型；指定时仅影响本次会话，不修改基础智能体。

模型 ID 无效时返回 HTTP 400；模型未开通时返回 HTTP 403 ModelNotOpen。

reasoning_effort string  |  推理投入档位

agent.model.reasoning_effort

推理投入档位。省略时沿用基础智能体的配置；传空字符串时使用当前模型的默认配置。

传入不支持的取值时返回 HTTP 400 InvalidParameter。各模型支持的取值和默认值，请参见 模型支持的参数列表。取值：none / minimal / low / medium / high / xhigh / max。

service_tier string  |  推理服务档位

agent.model.service_tier

推理服务档位。省略时沿用基础智能体的配置；传空字符串时使用当前模型的默认配置。

传入不支持的取值时返回 HTTP 400 InvalidParameter。各模型支持的取值和默认值，请参见 模型支持的参数列表。取值：auto / default / fast。

speed string  |  推理速度

agent.model.speed

模型推理速度档位。省略时沿用基础智能体的配置；传空字符串时使用模型服务的默认配置。

并非所有模型都支持 fast，传入不支持的取值时返回 HTTP 400 InvalidParameter。取值：standard / fast。

thinking string  |  思考模式

agent.model.thinking

思考模式。auto 表示由模型判断是否启用思考；省略时沿用基础智能体的配置；传空字符串时使用当前模型的默认配置。

传入不支持的取值时返回 HTTP 400 InvalidParameter。各模型支持的取值和默认值，请参见 模型支持的参数列表。取值：enabled / disabled / auto。

multiagent object  |  多智能体配置

agent.multiagent

本次会话使用的多智能体协作配置。省略时保留基础 Agent 的配置；提供时整体替换，agents 传入 [] 时清空子智能体列表。

agents object[] 必选  |  子智能体列表

agent.multiagent.agents

子智能体列表，最多 20 项。传入 [] 时清空基础 Agent 的子智能体列表。

type string 必选  |  子智能体来源

agent.multiagent.agents.type

子智能体来源。agent 表示引用当前账号和项目中的已有 Agent；self 表示复用当前主 Agent 的配置。

id string  |  子智能体 ID

agent.multiagent.agents.id

子智能体 ID。当 type 为 agent 时必填；当 type 为 self 时省略。

version integer  |  子智能体版本

agent.multiagent.agents.version

子智能体版本号，仅当 type 为 agent 时生效。省略时使用该子智能体的最新版本。

type string 必选  |  协作模式

agent.multiagent.type

多智能体协作模式，固定为 coordinator。当前智能体负责任务分配并汇总子智能体的结果。

skills object[]  |  技能列表

agent.skills

本次会话使用的技能列表。省略时保留原配置，传入 [] 时清空，传入非空数组时整体替换。

skill_id string 必选  |  技能 ID

agent.skills.skill_id

要绑定到智能体的技能 ID。

type string 必选  |  技能来源

agent.skills.type

技能来源。

  • ark：方舟预置技能。
  • skill_hub：来自 SkillHub 的公共技能。
  • custom：当前账号通过 Skills API 创建的自定义技能。
version string  |  技能版本

agent.skills.version

要绑定的技能版本号。省略时使用该技能的最新版本。

system string  |  系统提示词覆写

agent.system

本次会话使用的系统提示词。省略时沿用基础智能体的配置。

tools object[]  |  工具列表

agent.tools

本次会话使用的工具列表。省略时保留原配置，传入 [] 时清空，传入非空数组时整体替换。

type string 必选  |  工具类型

agent.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[]  |  工具配置列表

agent.tools.configs

按工具名称设置工具的启用状态和权限策略。

name string 必选  |  工具名称

agent.tools.configs.name

工具配置对应的工具名称。

enabled boolean  |  是否启用

agent.tools.configs.enabled

是否启用此工具。

models object[]  |  工具模型列表

agent.tools.configs.models

图片生成或视频生成工具使用的模型接入点列表。

id string 必选  |  接入点 ID

agent.tools.configs.models.id

图片生成或视频生成工具调用的推理接入点 ID。

default boolean 默认值 false  |  是否为默认模型

agent.tools.configs.models.default

是否作为该工具的默认模型。配置多个接入点时，必须且只能将一项设置为 true。

permission_policy object  |  权限策略

agent.tools.configs.permission_policy

该工具使用的权限策略。

type string 必选  |  策略类型

agent.tools.configs.permission_policy.type

工具调用许可策略。

  • always_allow：表示总是允许调用。
  • always_ask：表示每次使用前需要确认。
default_config object  |  默认工具配置

agent.tools.default_config

未在 configs 中单独配置的工具所使用的默认启用状态和权限策略。

enabled boolean  |  是否启用

agent.tools.default_config.enabled

是否默认启用未在 configs 中单独配置的工具。

  • true：表示默认启用。
  • false：表示默认禁用。
permission_policy object  |  权限策略

agent.tools.default_config.permission_policy

未在 configs 中单独配置的工具所使用的默认权限策略。

type string 必选  |  策略类型

agent.tools.default_config.permission_policy.type

工具调用许可策略。

  • always_allow：表示总是允许调用。
  • always_ask：表示每次使用前需要确认。
description string  |  自定义工具描述

agent.tools.description

说明自定义工具的功能和适用场景，供模型判断何时调用该工具。

input_schema object  |  输入参数定义

agent.tools.input_schema

定义自定义工具的输入参数及其约束。

properties object  |  参数属性定义

agent.tools.input_schema.properties

自定义工具输入参数的 JSON Schema properties 对象。键为参数名，值为对应参数的 JSON Schema 子对象。

required string[]  |  必填参数名称列表

agent.tools.input_schema.required

自定义工具输入中必填的参数名称列表。列表中的每个名称必须与 properties 中定义的参数名称一致。

type string 默认值 object  |  Schema 类型

agent.tools.input_schema.type

指定 JSON Schema 的顶层类型，仅支持 object。

mcp_server_name string  |  MCP 服务名称

agent.tools.mcp_server_name

MCP 工具所属的 MCP 服务名称。

name string  |  自定义工具名称

agent.tools.name

自定义工具的名称。

version integer  |  版本号

agent.version

基础智能体版本号。省略时使用最新版本；指定版本时，以该版本保存的配置为基础应用本次覆写。

environment_id string  |  环境 ID

直接使用已创建的 Environment 运行会话时，填写该 Environment 的 ID。需要为本次会话临时调整已开放的运行配置时，改用 environment。

environment object  |  环境覆写

需要为本次会话临时调整已有 Environment 的运行配置时，使用该对象。

id string 必选  |  环境 ID

environment.id

要作为本次配置覆写基础的 Environment ID。

type string 必选  |  对象类型

environment.type

对象类型，固定为 environment_with_overrides

config object  |  覆写后的运行配置

environment.config

本次会话使用的 Environment 运行配置覆写；省略时沿用原 Environment 的配置。

type string 必选  |  环境类型

environment.config.type

运行环境类型：cloud 表示平台托管的云端运行环境，self_hosted 表示用户自托管环境。覆写时必须与基础 Environment 保持一致。

env object  |  环境变量

environment.config.env

本次 Session 使用的环境变量，以变量名和变量值组成的字符串键值对形式传入。

packages object  |  依赖包配置

environment.config.packages

本次 Session 启动时预装的依赖包。

apt string[]  |  APT 软件包

environment.config.packages.apt

apt 依赖。

cargo string[]  |  Cargo 包

environment.config.packages.cargo

cargo 依赖。

gem string[]  |  Ruby Gem 包

environment.config.packages.gem

gem 依赖。

go string[]  |  Go 模块

environment.config.packages.go

go module 依赖。

npm string[]  |  npm 包

environment.config.packages.npm

npm 依赖。

pip string[]  |  Python 包

environment.config.packages.pip

pip 依赖。

type string  |  配置类型

environment.config.packages.type

固定为 packages。

setup_script string  |  初始化脚本

environment.config.setup_script

本次 Session 启动时执行的初始化脚本。

tos object  |  产物存储覆写

environment.config.tos

会话级产物存储覆写，tos 对象整体生效。

省略 tos 时保留基础 Environment 的配置；传入 {} 时清空配置并使用默认存储；传入非空对象时，必须同时提供 bucket 和 prefix。

bucket string  |  TOS 桶

environment.config.tos.bucket

用户 TOS 存储桶名称。Bucket 必须与当前方舟 API 接入地域一致，否则请求会被拒绝。

prefix string  |  对象前缀

environment.config.tos.prefix

智能体产物在用户 Bucket 中的存储目录前缀。

resources object[]  |  初始资源

会话启动时挂载到运行环境的文件、记忆库或 TOS 目录。

文件资源 object

通过 Files API 上传并挂载到会话的文件。

type string 必选  |  资源类型

resources.type

资源类型，固定为 file。

file_id string 必选  |  文件 ID

resources.file_id

要挂载到会话的文件 ID，通过 Files API 上传文件后获得。

mount_path string  |  挂载路径

resources.mount_path

文件在会话运行环境中的挂载路径。省略或传入空值时，使用文件上传时的原始文件名，最终路径为 /mnt/session/uploads/<filename>。

记忆库资源 object

挂载到会话的记忆库。

type string 必选  |  资源类型

resources.type

资源类型，固定为 memory_store。

memory_store_id string 必选  |  记忆库 ID

resources.memory_store_id

要挂载到会话的记忆库 ID，由创建记忆库接口返回，形如 memstore-...。

access string 默认值 read_write  |  访问权限

resources.access

会话对记忆库的访问权限：

  • read_only：智能体可以读取记忆库，但不能写入。
  • read_write：智能体可以读取和写入记忆库。
TOS 资源 object

挂载到会话的 TOS 对象目录。

type string 必选  |  资源类型

resources.type

资源类型，固定为 tos。

tos_bucket string 必选  |  TOS 存储桶

resources.tos_bucket

待挂载目录所在的 TOS 存储桶名称。

tos_region string  |  TOS 地域

resources.tos_region

源存储桶所在地域的 Region ID。省略时使用当前服务地域；显式提供时必须与当前服务地域一致。

tos_key string 必选  |  TOS 目录前缀

resources.tos_key

TOS 中待挂载目录的对象前缀。

access string 默认值 read_only  |  访问权限

resources.access

会话对 TOS 目录的访问权限：

  • read_only：智能体可以读取目录内容，但不能修改。
  • read_write：智能体可以读取和修改目录内容。
mount_path string  |  挂载路径

resources.mount_path

TOS 目录在会话运行环境中的挂载路径。默认值：/mnt/session/storage

tags object[]  |  标签列表

会话关联的标签列表，用于分类检索，最多 20 项。同一请求中的标签键不可重复。

key string 必选  |  标签键

tags.key

标签键，用于分类和检索。必填，最长 128 个字符；支持字母、数字、空格及 _ . : / = + - @。

value string  |  标签值

tags.value

用于记录该标签分类的具体内容。

title string  |  会话标题

会话标题，便于用户识别和管理，最长 255 个字符

vault_ids string[]  |  保管库 ID 列表

绑定到会话的保管库 ID 列表

响应参数#

agent object  |  智能体信息

创建会话时保存的智能体配置快照，包含该会话实际使用的模型、系统提示词、工具、MCP 服务和技能等配置。后续更新智能体不会影响该会话中的快照。

created_at string  |  创建时间

agent.created_at

智能体创建完成的时间，采用 RFC 3339 格式。

id string  |  智能体 ID

agent.id

会话当前使用的智能体 ID。

name string  |  智能体名称

agent.name

会话当前使用的智能体名称。

type string  |  对象类型

agent.type

对象类型，固定为 agent。

updated_at string  |  更新时间

agent.updated_at

智能体配置最后更新的时间，采用 RFC 3339 格式。

version integer  |  版本号

agent.version

会话当前使用的智能体版本号。

base_agent string  |  基础智能体类型

agent.base_agent

会话当前使用的基础 Agent 类型。

  • ark_agent_preview：通用 Agent。
  • ultra_vision_agent_preview：视觉增强 Agent。
description string  |  智能体说明

agent.description

会话当前使用的智能体说明。

display_name string  |  显示名称

agent.display_name

会话当前使用的智能体显示名称。

mcp_servers object[]  |  MCP 服务列表

agent.mcp_servers

会话当前使用的 MCP 服务配置列表。

name string  |  MCP 服务名称

agent.mcp_servers.name

MCP 服务名称，供 tools[].mcp_server_name 引用。

type string  |  MCP 接入方式

agent.mcp_servers.type

MCP 服务接入方式，固定为 url。

url string  |  MCP 服务地址

agent.mcp_servers.url

会话创建时冻结的 MCP 服务访问地址。

metadata object  |  自定义元数据

agent.metadata

创建智能体时设置的自定义键值对，服务端不定义固定子字段。

model object  |  模型配置

agent.model

会话当前使用的模型配置。

id string  |  模型 ID

agent.model.id

会话当前使用的模型 ID。

protocol string  |  调用协议

agent.model.protocol

会话模型调用使用的协议：

  • ark_responses：方舟 Responses 协议。
  • openai_chat_completions：OpenAI Chat Completions 兼容协议。
  • openai_responses：OpenAI Responses 兼容协议。
  • anthropic_messages：Anthropic Messages 兼容协议。
reasoning_effort string  |  推理投入档位

agent.model.reasoning_effort

会话当前使用的推理投入档位。

service_tier string  |  推理服务档位

agent.model.service_tier

会话当前使用的推理服务档位。

speed string  |  推理速度

agent.model.speed

模型推理速度档位。

thinking string  |  思考模式

agent.model.thinking

会话当前使用的思考模式。

multiagent object  |  多智能体配置

agent.multiagent

会话当前使用的多智能体配置。

agents object[]  |  成员智能体

agent.multiagent.agents

会话创建时冻结的成员智能体列表。

type string  |  引用类型

agent.multiagent.agents.type

成员引用类型：

  • agent：引用其他智能体。
  • self：引用当前智能体。
description string  |  智能体说明

agent.multiagent.agents.description

会话创建时冻结的成员智能体说明。

display_name string  |  显示名称

agent.multiagent.agents.display_name

会话创建时冻结的成员智能体显示名称。

id string  |  智能体 ID

agent.multiagent.agents.id

成员智能体的 ID；当 type 为 self 时，返回当前智能体的 ID。

mcp_servers object[]  |  MCP 服务列表

agent.multiagent.agents.mcp_servers

会话创建时冻结的成员智能体 MCP 服务配置列表。

name string  |  MCP 服务名称

agent.multiagent.agents.mcp_servers.name

MCP 服务名称，供 tools[].mcp_server_name 引用。

type string  |  MCP 接入方式

agent.multiagent.agents.mcp_servers.type

MCP 服务接入方式，固定为 url。

url string  |  MCP 服务地址

agent.multiagent.agents.mcp_servers.url

会话创建时冻结的 MCP 服务访问地址。

model object  |  模型配置

agent.multiagent.agents.model

会话创建时冻结的成员智能体模型配置。

id string  |  模型 ID

agent.multiagent.agents.model.id

成员智能体使用的模型 ID。

speed string  |  推理速度

agent.multiagent.agents.model.speed

成员智能体使用的模型推理速度档位。

name string  |  智能体名称

agent.multiagent.agents.name

会话创建时冻结的成员智能体名称。

skills object[]  |  Skill 列表

agent.multiagent.agents.skills

会话创建时冻结的成员智能体 Skill 配置列表。

type string  |  Skill 类型

agent.multiagent.agents.skills.type

Skill 来源类型：

  • ark：方舟平台预置 Skill。
  • skill_hub：Skill Hub 中的公共 Skill。
  • custom：当前账号创建的自定义 Skill。
display_name string  |  Skill 名称

agent.multiagent.agents.skills.display_name

会话创建时记录的 Skill 展示名称。

skill_id string  |  Skill ID

agent.multiagent.agents.skills.skill_id

会话使用的 Skill ID。

use_latest boolean  |  使用最新版本

agent.multiagent.agents.skills.use_latest

是否在创建会话时选择该 Skill 的最新版本。true 表示选择当时的最新版本，false 表示使用 version 指定的版本。

version string  |  Skill 版本

agent.multiagent.agents.skills.version

会话创建时冻结的 Skill 版本号。

system string  |  系统提示词

agent.multiagent.agents.system

会话创建时冻结的成员智能体系统提示词。

tools object[]  |  工具列表

agent.multiagent.agents.tools

会话创建时冻结的成员智能体工具配置列表。

type string  |  工具类型

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[]  |  工具配置

agent.multiagent.agents.tools.configs

会话创建时冻结的逐项工具配置。

name string  |  工具名称

agent.multiagent.agents.tools.configs.name

会话快照中记录的工具名称。

enabled boolean  |  是否启用

agent.multiagent.agents.tools.configs.enabled

工具是否启用。

models object[]  |  工具模型列表

agent.multiagent.agents.tools.configs.models

会话快照中记录的图片生成或视频生成工具模型接入点列表。

id string  |  接入点 ID

agent.multiagent.agents.tools.configs.models.id

该工具绑定的推理接入点 ID。

default boolean  |  是否为默认模型

agent.multiagent.agents.tools.configs.models.default

是否为该工具的默认模型。

name string  |  模型名称

agent.multiagent.agents.tools.configs.models.name

服务端根据接入点 ID 返回的模型名称。

version string  |  模型版本

agent.multiagent.agents.tools.configs.models.version

服务端根据接入点 ID 返回的模型版本。

permission_policy object  |  权限策略

agent.multiagent.agents.tools.configs.permission_policy

工具使用的调用许可策略。

type string  |  策略类型

agent.multiagent.agents.tools.configs.permission_policy.type

策略类型，always_allow 表示允许直接调用，always_ask 表示每次调用前需要用户确认。

default_config object  |  默认工具配置

agent.multiagent.agents.tools.default_config

未在 configs 中单独列出的工具所使用的默认配置。

enabled boolean  |  是否启用

agent.multiagent.agents.tools.default_config.enabled

未单独配置的工具是否默认启用。

permission_policy object  |  权限策略

agent.multiagent.agents.tools.default_config.permission_policy

未单独配置的工具使用的调用许可策略。

type string  |  策略类型

agent.multiagent.agents.tools.default_config.permission_policy.type

策略类型，always_allow 表示允许直接调用，always_ask 表示每次调用前需要用户确认。

description string  |  自定义工具说明

agent.multiagent.agents.tools.description

会话创建时冻结的自定义工具说明，用于记录工具的功能和适用场景。

input_schema object  |  输入参数定义

agent.multiagent.agents.tools.input_schema

返回 Session 的 Agent 快照中记录的自定义工具输入参数 JSON Schema。

properties object  |  参数属性定义

agent.multiagent.agents.tools.input_schema.properties

返回 Session 的 Agent 快照中记录的 JSON Schema 属性映射。每个键为参数名，每个值为对应参数的 JSON Schema 子对象。

required string[]  |  必填参数名称列表

agent.multiagent.agents.tools.input_schema.required

返回调用自定义工具时必须提供的参数名称列表。

type string  |  Schema 类型

agent.multiagent.agents.tools.input_schema.type

返回 JSON Schema 的顶层类型，固定为 object。

mcp_server_name string  |  MCP 服务名称

agent.multiagent.agents.tools.mcp_server_name

会话中 mcp_toolset 引用的 MCP 服务名称。

name string  |  自定义工具名称

agent.multiagent.agents.tools.name

会话创建时冻结的自定义工具名称。

version integer  |  版本号

agent.multiagent.agents.version

会话创建时冻结的成员智能体版本号。

type string  |  协作模式

agent.multiagent.type

多智能体协作模式，固定为 coordinator。

skills object[]  |  Skill 列表

agent.skills

会话当前使用的 Skill 配置列表。

type string  |  Skill 类型

agent.skills.type

Skill 来源类型：

  • ark：方舟平台预置 Skill。
  • skill_hub：Skill Hub 中的公共 Skill。
  • custom：当前账号创建的自定义 Skill。
display_name string  |  Skill 名称

agent.skills.display_name

会话创建时记录的 Skill 展示名称。

skill_id string  |  Skill ID

agent.skills.skill_id

会话使用的 Skill ID。

use_latest boolean  |  使用最新版本

agent.skills.use_latest

是否在创建会话时选择该 Skill 的最新版本。true 表示选择当时的最新版本，false 表示使用 version 指定的版本。

version string  |  Skill 版本

agent.skills.version

会话创建时冻结的 Skill 版本号。

system string  |  系统提示词

agent.system

会话当前使用的系统提示词。

tools object[]  |  工具列表

agent.tools

会话当前使用的工具配置列表。

type string  |  工具类型

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[]  |  工具配置

agent.tools.configs

会话创建时冻结的逐项工具配置。

name string  |  工具名称

agent.tools.configs.name

会话快照中记录的工具名称。

enabled boolean  |  是否启用

agent.tools.configs.enabled

工具是否启用。

models object[]  |  工具模型列表

agent.tools.configs.models

会话快照中记录的图片生成或视频生成工具模型接入点列表。

id string  |  接入点 ID

agent.tools.configs.models.id

该工具绑定的推理接入点 ID。

default boolean  |  是否为默认模型

agent.tools.configs.models.default

是否为该工具的默认模型。

name string  |  模型名称

agent.tools.configs.models.name

服务端根据接入点 ID 返回的模型名称。

version string  |  模型版本

agent.tools.configs.models.version

服务端根据接入点 ID 返回的模型版本。

permission_policy object  |  权限策略

agent.tools.configs.permission_policy

工具使用的调用许可策略。

type string  |  策略类型

agent.tools.configs.permission_policy.type

策略类型，always_allow 表示允许直接调用，always_ask 表示每次调用前需要用户确认。

default_config object  |  默认工具配置

agent.tools.default_config

未在 configs 中单独列出的工具所使用的默认配置。

enabled boolean  |  是否启用

agent.tools.default_config.enabled

未单独配置的工具是否默认启用。

permission_policy object  |  权限策略

agent.tools.default_config.permission_policy

未单独配置的工具使用的调用许可策略。

type string  |  策略类型

agent.tools.default_config.permission_policy.type

策略类型，always_allow 表示允许直接调用，always_ask 表示每次调用前需要用户确认。

description string  |  自定义工具说明

agent.tools.description

会话创建时冻结的自定义工具说明，用于记录工具的功能和适用场景。

input_schema object  |  输入参数定义

agent.tools.input_schema

返回 Session 的 Agent 快照中记录的自定义工具输入参数 JSON Schema。

properties object  |  参数属性定义

agent.tools.input_schema.properties

返回 Session 的 Agent 快照中记录的 JSON Schema 属性映射。每个键为参数名，每个值为对应参数的 JSON Schema 子对象。

required string[]  |  必填参数名称列表

agent.tools.input_schema.required

返回调用自定义工具时必须提供的参数名称列表。

type string  |  Schema 类型

agent.tools.input_schema.type

返回 JSON Schema 的顶层类型，固定为 object。

mcp_server_name string  |  MCP 服务名称

agent.tools.mcp_server_name

会话中 mcp_toolset 引用的 MCP 服务名称。

name string  |  自定义工具名称

agent.tools.name

会话创建时冻结的自定义工具名称。

created_at string  |  创建时间

会话创建完成的时间，采用 RFC 3339 格式。

environment_id string  |  环境 ID

会话实际使用的 Environment ID。

id string  |  会话 ID

会话唯一标识符，格式为 sesn- 开头的字符串

status string  |  会话状态

会话运行状态。普通创建成功后，初始状态为 idle，可继续发送事件。取值：idle / running / terminated / rescheduling / initializing / failed / upgrading。

type string  |  对象类型

对象类型，固定为session

updated_at string  |  更新时间

会话信息最后更新的时间，采用 RFC 3339 格式。

archived_at string  |  归档时间

会话归档的时间，采用 RFC 3339 格式。会话未归档时，服务端不返回该字段。

environment object  |  环境信息

会话实际使用的环境配置快照。后续修改原 Environment 不会改变该快照。

created_at string  |  创建时间

environment.created_at

环境创建完成的时间，采用 RFC 3339 格式。

id string  |  环境 ID

environment.id

环境唯一标识符

name string  |  环境名称

environment.name

环境名称，用于在环境列表和会话配置中区分该环境。

type string  |  对象类型

environment.type

会话环境快照类型。environment 表示直接使用基础 Environment；environment_with_overrides 表示当前会话使用了环境配置覆写。

updated_at string  |  更新时间

environment.updated_at

环境配置最后更新的时间，采用 RFC 3339 格式。

config object  |  环境配置

environment.config

环境运行配置，包含运行类型、网络策略、依赖包与环境变量

type string  |  环境类型

environment.config.type

运行环境类型：cloud 表示平台托管环境，self_hosted 表示用户自托管环境。

env object  |  环境变量

environment.config.env

会话运行环境中的环境变量键值对

networking object  |  出网策略

environment.config.networking

容器出网策略配置

type string  |  出网策略类型

environment.config.networking.type

会话当前使用的出网策略。unrestricted 表示不限制出网目标。

packages object  |  依赖包配置

environment.config.packages

启动时预装的依赖包配置

apt string[]  |  apt 包

environment.config.packages.apt

会话环境启动时通过 apt 预装的系统包列表。

cargo string[]  |  Cargo 包

environment.config.packages.cargo

会话环境启动时通过 Cargo 预装的 Rust crate 列表。

gem string[]  |  gem 包

environment.config.packages.gem

会话环境启动时通过 RubyGems 预装的 Ruby 包列表。

go string[]  |  Go 模块

environment.config.packages.go

会话环境启动时通过 Go 工具链预装的模块依赖列表。

npm string[]  |  npm 包

environment.config.packages.npm

会话环境启动时通过 npm 预装的 Node.js 包列表。

pip string[]  |  pip 包

environment.config.packages.pip

会话环境启动时通过 pip 预装的 Python 包列表。

type string  |  配置类型

environment.config.packages.type

依赖包配置的类型标识，固定为 packages。

setup_script string  |  启动脚本

environment.config.setup_script

会话运行环境启动时执行的初始化脚本；留空或未设置表示不执行任何脚本

tos object  |  产物存储配置

environment.config.tos

智能体产物持久化存储配置。为空表示未配置用户 Bucket，产物落到方舟公共 TOS

bucket string  |  TOS 桶

environment.config.tos.bucket

会话环境快照中保存的用户 TOS 存储桶名称。

prefix string  |  对象前缀

environment.config.tos.prefix

会话环境快照中保存的对象存储目录前缀。

description string  |  环境描述

environment.description

环境描述，用于说明环境的用途、网络策略、依赖包等配置

metadata object  |  自定义元数据

environment.metadata

用户自定义元数据

overridden_fields string[]  |  覆写字段

environment.overridden_fields

当前会话相对基础 Environment 实际覆写的 config 子字段名称列表。仅在 type 为 environment_with_overrides 且存在覆写字段时返回。

scope string  |  作用域

environment.scope

环境作用域：organization 表示组织内共享；account 表示账号内可见。

resources object[]  |  资源列表

会话创建后实际挂载到运行环境的资源列表。

文件资源 object

通过 Files API 上传并挂载到会话的文件。

created_at string  |  挂载时间

resources.created_at

资源挂载到会话的时间，采用 RFC 3339 格式。

id string  |  资源 ID

resources.id

会话资源 ID。

type string  |  资源类型

resources.type

资源类型，固定为 file。

updated_at string  |  更新时间

resources.updated_at

会话资源信息最后更新的时间，采用 RFC 3339 格式。

access string  |  访问权限

resources.access

文件访问权限，固定为 read_only。

file_id string  |  文件 ID

resources.file_id

当前可用的文件 ID。

mount_path string  |  挂载路径

resources.mount_path

文件在会话运行环境中的完整挂载路径。

记忆库资源 object

挂载到会话的记忆库。

created_at string  |  挂载时间

resources.created_at

资源挂载到会话的时间，采用 RFC 3339 格式。

id string  |  资源 ID

resources.id

会话资源 ID。

type string  |  资源类型

resources.type

资源类型，固定为 memory_store。

updated_at string  |  更新时间

resources.updated_at

会话资源信息最后更新的时间，采用 RFC 3339 格式。

access string  |  访问权限

resources.access

会话对记忆库的访问权限。可选值：read_only、read_write。

memory_store_id string  |  记忆库 ID

resources.memory_store_id

挂载到会话的记忆库 ID。

TOS 资源 object

挂载到会话的 TOS 对象目录。

created_at string  |  挂载时间

resources.created_at

资源挂载到会话的时间，采用 RFC 3339 格式。

id string  |  资源 ID

resources.id

会话资源 ID。

type string  |  资源类型

resources.type

资源类型，固定为 tos。

updated_at string  |  更新时间

resources.updated_at

会话资源信息最后更新的时间，采用 RFC 3339 格式。

access string  |  访问权限

resources.access

会话对 TOS 目录的访问权限。可选值：read_only、read_write。

mount_path string  |  挂载路径

resources.mount_path

TOS 目录在会话运行环境中的挂载路径。创建会话时未指定挂载路径，则不返回该字段。

tos_bucket string  |  TOS 存储桶

resources.tos_bucket

TOS 挂载源所在的存储桶名称。

tos_key string  |  TOS 目录前缀

resources.tos_key

TOS 中已挂载目录的对象前缀。

tos_region string  |  TOS 地域

resources.tos_region

TOS 挂载源所在地域的 Region ID。

tags object[]  |  标签列表

会话关联的标签列表，用于分类检索

key string  |  标签键

tags.key

标签键，用于分类和检索。必填，最长 128 个字符；支持字母、数字、空格及 _ . : / = + - @。

value string  |  标签值

tags.value

用于记录该标签分类的具体内容。

title string  |  会话标题

会话标题，便于用户在会话列表中识别

vault_ids string[] / null  |  保管库 ID 列表

会话可访问的保管库 ID 列表。智能体可在运行过程中使用其中的凭证。