Skip to main content
POST
创建会话
每个请求都必须发送 ?beta=true

授权

X-Api-Key
string
header
默认值:sk-ant-local-default
必填

OMA 工作区 API 密钥。

请求头

anthropic-version
string
anthropic-beta
string

查询参数

beta
enum<boolean>
必填

为此接口启用 Beta API 合同,必须为 true

可用选项:
true

请求体

application/json

创建 session 的请求参数。

agent
必填

智能体标识符。可传入 agent ID 字符串(将为会话固定最新版本),或同时指定 ID 和 version 的 agent 对象。

示例:

"agent_011CZkYpogX7uDKUyvBTophP"

environment_id
string
必填

为该会话定义容器配置的 environment 的 ID。

Required string length: 1 - 128
示例:

"env_011CZkZ9X2dpNyB7HsEFoRfW"

title
string | null

人类可读的会话标题。

Maximum string length: 500
示例:

"订单 #1234 咨询"

metadata
object

附加到会话的任意键值元数据。最多 16 对,键最长 64 个字符,值最长 512 个字符。

resources
object[]

要挂载到会话容器中的资源(例如仓库、文件)。

将 GitHub 仓库挂载到会话的容器中。

示例:
vault_ids
string[]

智能体可在会话期间使用的已存储凭据的密钥库 ID 列表。

initial_events
object[]

创建 session 时要发送的初始事件,按顺序处理。支持 user.messageuser.define_outcome 事件。最多 50 个事件。

向会话发送用户消息的参数。

示例:
budget
object

为该会话强制执行的花费上限。省略则创建不设上限的会话。该会话可运行的每个模型——智能体自身的模型以及每个可调用智能体的模型——都必须有公开的目录价格,否则请求会以原因 model_not_budgetable 被拒绝。

响应

请求成功。

托管智能体的 session

type
enum<string>
必填
可用选项:
session
示例:

"session"

id
string
必填
示例:

"sesn_011CZkZAtmR3yMPDzynEDxu7"

status
enum<string>
必填

会话状态枚举

可用选项:
rescheduling,
running,
idle,
terminated
示例:

"idle"

created_at
string<date-time>
必填

RFC 3339 格式的时间戳

示例:

"2026-03-15T10:00:00Z"

updated_at
string<date-time>
必填

RFC 3339 格式的时间戳

示例:

"2026-03-15T10:00:00Z"

environment_id
string
必填
示例:

"env_011CZkZ9X2dpNyB7HsEFoRfW"

title
string | null
必填
示例:

"订单 #1234 咨询"

metadata
object
必填
示例:
agent
object
必填

已解析的 session 所用 agent 定义。session 创建时该 agent 的快照。

示例:
resources
object[]
必填
示例:
示例:
vault_ids
string[]
必填

创建时附加到会话的密钥库 ID 列表。未提供密钥库时为空。

示例:
outcome_evaluations
object[]
必填

按结果划分的评估状态。发送给会话的每个 define_outcome 事件对应一个条目。

示例:
usage
object
必填

会话的累计令牌用量。

示例:
stats
object
必填

该会话的计时统计信息。

示例:
archived_at
string<date-time> | null
必填

会话的归档时间。未归档时为 null。

示例:

null

budget
object | null
必填

会话强制执行的花费上限;未设置预算时为 null。

示例:

null

deployment_id
string | null

当会话由部署引用创建时对应的部署 ID。否则为 Null。