创建会话

请求体

• modelstring可选

  智能体使用的模型：直接写模型名字符串（如 claude-opus-5），或传对象做附加配置（见子字段）。

• agentstring | object必填

  会话要运行的智能体：直接写智能体 ID 字符串（固定用最新版本），或传对象指定 id 与 version（见子字段）。

  ▸ 展开子字段（8）

  • idstring必填

    会话要运行的智能体 ID。

  • typestring必填

    引用类型，目前只有 agent。

    取值 agent_with_overrides
  • versionnumber可选

    固定使用的智能体版本；省略用最新版本。

  • mcp_serversarray可选

    替换本会话的 MCP 服务器列表：传入的数组整体生效；传空数组清除，省略沿用智能体的配置。

  • modelstring | object可选

    替换本会话的模型：模型名字符串（如 claude-opus-5）或配置对象；省略沿用智能体自身的模型。

  • skillsarray可选

    替换本会话的 Skill 列表；传空数组清除，省略沿用智能体的配置。

  • systemstring可选

    替换本会话的系统提示词，最长 100,000 字符；传 null 清除，省略沿用智能体的。

  • toolsarray可选

    替换本会话的工具配置；传空数组清除，省略沿用智能体的配置。

• environment_idstring可选

  会话运行所在的环境 ID，决定容器的基础环境。

• titlestring可选

  会话标题，便于在控制台辨认。

• metadataobject可选

  会话的自定义元数据键值对。

• budgetobject可选

  会话的预算上限设置。

  ▸ 展开子字段（2）

  • max_list_costobject必填

    预算内列表类调用的花费上限。

  • typestring必填

    预算类型，目前只有 max_list_cost。

    取值 limit
• initial_eventsarray可选

  创建时按顺序发给会话的初始事件，支持 user.message 与 user.define_outcome，一次最多 50 条。

• resourcesarray可选

  要挂载进会话容器的资源（如代码仓库、文件）。

• vault_idsarray可选

  保险库 ID 列表：会话里智能体可以使用这些已存凭据。

• cwdstring可选
  默认 "/home/user/workspace"

  Session working directory on any machine. Must be an absolute path within /home/user with no . or .. segments. Repeated and trailing slashes are normalized. Invalid values return 400 invalid_request_error with Invalid cwd.

• ▸ 更多参数（3）

  • computer_idstring可选

    Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. computer_id selects a tenant-owned active computer. Session selection overrides the agent default; a sandbox environment_id and computer_id cannot be combined.

  • time_zonestring可选
    默认 "UTC"

    Praxis extension: the session's IANA time zone name (e.g. Asia/Shanghai) — the clock the runtime environment block renders for every turn. Absent means UTC. Only IANA names are accepted; fixed offsets ("+08:00") and unknown names return 400. Never stored in `metadata`.

  • thinkingobject可选

    Praxis extension: explicit session thinking effort; null inherits the pinned agent default, then the model default. none disables thinking only when model.thinking.can_disable is true. Unsupported efforts return 400 invalid_request_error.

    ▸ 展开子字段（1）

    • effortstring必填

      Thinking level for this session. The model must support the chosen effort; none requires can_disable. Null on thinking restores inheritance from the agent and model.

      取值 lowmediumhighxhighnone

返回

200

可在创建时传 model（models.allowed 内的 ID 字符串；无 allowed 时只允许默认模型）与 thinking（{effort: "low|medium|high|xhigh|none"} 或 null），在首条 initial_events 执行前保存。省略或 null 继承智能体默认，再使用模型默认。档位必须在 model.thinking.efforts 内；none 要求 can_disable 为 true，否则返回 400 invalid_request_error。响应包含 thinking 与 model.thinking: {efforts, can_disable, default_effort}；未知能力为 null，默认档位也可为 null。示例：{"agent":"agent_123","model":"deepseek-v4-flash","thinking":{"effort":"xhigh"}}。这些选择字段只在 /agent/v1 提供。先创建智能体，将示例 agent_123 换成返回的 id。省略 environment_id 得到轻量机器（light），有默认或显式 computer_id 时使用该 Computer；指定 node22 或租户自建 cloud 环境则使用沙箱配方。无配方时响应省略 environment_id。不支持内联智能体覆盖、预算与凭据库。支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/<file_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。

错误按 Anthropic 错误格式返回（type / message / request_id），参见 错误码