Skip to main content
会话（Session）是智能体的一次运行实例，对应一项具体任务。 创建会话时，平台会把指定的智能体版本、执行环境版本和会话资源固定下来，并返回一个以 sesn_ 开头的会话 ID。 后续可以使用该 ID 发送事件、订阅事件和管理会话生命周期。
创建会话前，请先准备好一个 智能体 和一个处于可用状态的 执行环境。
创建会话不等于启动任务。 创建成功后会话处于 idle 状态，不会执行智能体，也不会产生任务事件。 建议先打开 事件流，再发送第一条 user.message；收到该输入后，会话才会进入 running 状态。

​
创建前的配置

调用 POST /v1/sessions 创建会话。 请求体中只有 agent_id 和 environment_id 必填： agent_overrides 用于在当前会话中临时调整冻结的智能体版本，不会修改智能体资源或创建新的智能体版本。 目前只支持 mcp_servers 和 skills 两个集合字段，不支持覆盖 model、system 或 tools。 每个集合字段都支持三种状态：省略表示继承冻结智能体版本中的集合，显式传入空数组表示清空本会话中的集合，传入有值的数组表示整体替换集合，不会与原集合合并。 该配置只影响当前会话。 resources 中的每个对象都通过 type 区分资源类型：
  • file：通过 file_id 引用已上传的文件。
  • vault：通过 vault_id 绑定凭据库；绑定关系在创建时确定。
  • memory_store：通过 memory_store_id 绑定记忆库，并通过 access 指定 read_only 或 read_write；绑定关系和访问模式在创建时确定。可选 instructions 为本次绑定向模型提供附加指引。
资源是引用关系，不会把文件或凭据内容复制进请求体。 文件、凭据库和记忆库的准备方式分别见 文件、凭据库 和 记忆库。

​
创建会话

下面的请求创建会话并绑定一个已上传文件。 如果不需要绑定资源，可以省略 resources；如果需要绑定凭据库或记忆库，请在同一个数组中添加对应的引用。
创建成功后，接口返回会话对象。 此时 status 为 idle，表示会话已经创建但尚未启动：

​
创建时冻结版本

创建会话时，平台会为会话选择并固定以下配置：
  • 智能体版本：省略 agent_version 时，固定创建时可用的最新版本；指定该字段时，固定指定的版本。 之后更新智能体不会改变这个会话使用的版本。
  • 执行环境版本：请求传入的是 environment_id，平台在创建时为该环境选择并固定符合条件的可用版本。 environment_id 绑定后不能更改；如果环境不可见、已归档或没有可用版本，创建请求会被拒绝。
  • 会话资源：创建时绑定的凭据库和记忆库不能再追加或替换。 文件可以在创建后通过会话资源接口追加或移除，具体操作见 文件。
想让新任务使用更新后的智能体或执行环境配置时，请创建新会话。 已创建的会话继续使用其冻结的版本。

​
启动任务

创建会话后按以下顺序启动任务：
1

订阅事件流

调用 GET /v1/sessions/{session_id}/events/stream 建立 SSE 连接，以便接收启动后的状态和输出事件。
2

发送首条消息

调用 POST /v1/sessions/{session_id}/events，发送一个 user.message 事件。 该请求才会把任务加入会话输入队列并触发执行。
3

处理事件

订阅 session.status、agent.message 等事件，直到本轮执行结束。 事件格式和断线续读方式见 事件流。
下面的示例需要在两个终端中运行。先在终端 1 订阅事件流，再在终端 2 发送首条消息；将示例中的 sesn_your_session_id 替换为创建会话后返回的会话 ID。 终端 1：订阅事件流
终端 2：发送首条消息
发送消息后，事件会持续输出到终端 1。收到 session.status 和 agent.message 等事件后，可以观察任务状态和智能体输出。事件流的断线恢复和事件处理方式见 事件流。

​
下一步

订阅事件流

建立 SSE 连接、发送消息并处理实时事件。

会话操作

查询会话、更新标题、取消执行、归档或删除会话。