会话设置

创建和加载会话

会话代表客户端和 Agent 之间特定的对话或线程。

每个会话维护自己的上下文、对话历史和状态，允许与同一个 Agent 进行多个独立的交互。

在创建会话之前，客户端必须先完成初始化阶段以建立协议兼容性和能力。

创建会话

客户端通过调用 session/new 方法创建新会话，包含：

会话的工作目录
Agent 应连接的MCP 服务器列表

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/new",
  "params": {
    "cwd": "/home/user/project",
    "mcpServers": [
      {
        "type": "stdio",
        "name": "workspace-tools",
        "command": "/path/to/mcp-server",
        "args": ["--stdio"],
        "env": []
      }
    ]
  }
}

Agent 必须以标识此对话的唯一会话 ID 响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sessionId": "sess_abc123def456"
  }
}

加载会话

支持 session.load 能力的 Agent 允许客户端恢复之前的对话。此功能支持跨重启的持久化以及在不同客户端实例间共享会话。

检查支持

在尝试加载会话之前，客户端必须通过检查 initialize 响应中的 session.load 字段来验证 Agent 是否支持此能力：

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 2,
    "capabilities": {
      "session": {
        "load": {}
      }
    }
  }
}

如果 session.load 被省略或为 null，Agent 不支持加载会话，客户端不得尝试调用 session/load。

加载会话

要加载已有会话，客户端必须调用 session/load 方法，包含：

要恢复的会话 ID
要连接的 MCP 服务器
工作目录

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/load",
  "params": {
    "sessionId": "sess_789xyz",
    "cwd": "/home/user/project",
    "mcpServers": [
      {
        "type": "stdio",
        "name": "workspace-tools",
        "command": "/path/to/mcp-server",
        "args": ["--mode", "workspace"],
        "env": []
      }
    ]
  }
}

Agent 必须以 session/update 通知的形式（如同 session/prompt）向客户端重放整个对话。用户、Agent 和思考消息可以各自以带有完整内容数组的消息更新或分块的形式重放。

例如，对话历史中的用户消息：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_789xyz",
    "update": {
      "sessionUpdate": "user_message",
      "messageId": "msg_user_8f7a1",
      "content": [
        {
          "type": "text",
          "text": "What's the capital of France?"
        }
      ]
    }
  }
}

随后是 Agent 的响应：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_789xyz",
    "update": {
      "sessionUpdate": "agent_message",
      "messageId": "msg_agent_c42b9",
      "content": [
        {
          "type": "text",
          "text": "The capital of France is Paris."
        }
      ]
    }
  }
}

在重放期间，Agent 必须为每条重放消息包含一个不透明的唯一 messageId。user_message、agent_message 和 agent_thought 更新是以 messageId 为键的 upsert 操作；它们的内容数组替换整个消息内容，而具有相同 messageId 的分块更新则追加内容。

客户端按接收顺序应用重放的消息更新和分块。如果带有内容的消息更新在同一 messageId 的分块之后到达，它将替换从这些分块累积的内容。如果分块在消息更新之后到达，它们将追加到该更新的当前内容。省略内容的消息更新可以更新 _meta 或未来字段而不改变当前内容。

当所有对话条目都已报告给客户端后，Agent 必须响应原始的 session/load 请求。

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

然后客户端可以继续发送提示，就像会话从未中断一样。

恢复会话

声明 session.resume 的 Agent 允许客户端重新连接到已有会话而无需重放对话历史。

检查支持

在尝试恢复会话之前，客户端必须通过检查 initialize 响应中的 session.resume 字段来验证 Agent 是否支持此能力：

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 2,
    "capabilities": {
      "session": {
        "resume": {}
      }
    }
  }
}

如果 session.resume 不存在，Agent 不支持恢复会话，客户端不得尝试调用 session/resume。

恢复会话

要在不重放先前消息的情况下恢复已有会话，客户端必须调用 session/resume 方法，包含：

要恢复的会话 ID
要连接的 MCP 服务器
工作目录

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/resume",
  "params": {
    "sessionId": "sess_789xyz",
    "cwd": "/home/user/project",
    "mcpServers": [
      {
        "type": "stdio",
        "name": "workspace-tools",
        "command": "/path/to/mcp-server",
        "args": ["--mode", "workspace"],
        "env": []
      }
    ]
  }
}

与 session/load 不同，Agent 不得在响应之前通过 session/update 通知重放对话历史。相反，它恢复会话上下文，重新连接到请求的 MCP 服务器，并在会话准备好继续时返回。

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {}
}

当 Agent 支持会话配置选项功能时，响应也可以包含初始会话配置状态。

关闭活动会话

声明 session.close 的 Agent 允许客户端告知 Agent 取消会话的任何正在进行的工作并释放与该活动会话关联的资源。

检查支持

在尝试关闭会话之前，客户端必须通过检查 initialize 响应中的 session.close 字段来验证 Agent 是否支持此能力：

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 2,
    "capabilities": {
      "session": {
        "close": {}
      }
    }
  }
}

如果 session.close 不存在，Agent 不支持关闭会话，客户端不得尝试调用 session/close。

关闭会话

要关闭活动会话，客户端必须调用 session/close 方法并传入会话 ID：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/close",
  "params": {
    "sessionId": "sess_789xyz"
  }
}

参数	类型	描述
`sessionId`	`SessionId`	必需。要关闭的活动会话 ID。

Agent 必须像调用了 session/cancel 一样取消该会话的任何正在进行的工作，然后释放与该会话关联的资源。

成功时，Agent 以空结果对象响应：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {}
}

如果会话不存在或当前不活动，Agent 可以返回错误。

额外工作区根目录

声明 session.additionalDirectories 的 Agent 允许客户端在支持的会话生命周期请求中包含 additionalDirectories，以扩展会话的有效工作区根集。支持的稳定生命周期请求包括 session/new、session/load 和 session/resume。

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/load",
  "params": {
    "sessionId": "sess_789xyz",
    "cwd": "/home/user/project",
    "additionalDirectories": [
      "/home/user/shared-lib",
      "/home/user/product-docs"
    ],
    "mcpServers": []
  }
}

存在时，additionalDirectories 具有以下行为：

cwd 仍然是主工作目录和相对路径的基准
每个 additionalDirectories 条目必须是绝对路径
省略该字段或提供空数组不会为结果会话激活任何额外根
在 session/load 和 session/resume 时，客户端必须再次发送完整的预期额外根列表；只要请求的 cwd 与会话的 cwd 匹配，该列表可以与任何先前或已报告的列表不同，省略该字段或提供空数组不会隐式恢复已存储的根

客户端必须仅在 Agent 声明 session.additionalDirectories 时才发送 additionalDirectories。

会话 ID

session/new 返回的会话 ID 是对话上下文的唯一标识符。

客户端使用此 ID 来：

通过 session/prompt 发送提示请求
通过 session/cancel 取消正在进行的操作
通过 session/load 加载之前的会话（如果 Agent 支持 session.load 能力）
通过 session/resume 恢复之前的会话（如果 Agent 支持 session.resume 能力）
通过 session/close 关闭活动会话（如果 Agent 支持 session.close 能力）

工作目录

cwd（当前工作目录）参数建立会话的主文件系统上下文。此目录：

必须为绝对路径
必须用于会话，无论 Agent 子进程在哪里启动
必须保持作为相对路径解析的基准
必须是会话有效根集的一部分

当使用 session.additionalDirectories 时，会话的有效根集为 [cwd, ...additionalDirectories]。此根集应该作为文件系统上工具操作的边界。

MCP 服务器

Model Context Protocol (MCP) 允许 Agent 访问外部工具和数据源。

创建会话时，客户端可以包含 Agent 应连接的 MCP 服务器连接详情。

MCP 服务器可以使用不同的传输方式连接。Agent 在初始化期间使用 session.mcp.stdio、session.mcp.http 以及任何扩展特定的传输能力来声明支持的传输方式。

传输类型

每个 MCP 服务器对象都有一个 type 判别字段来标识其传输方式。自定义实现特定传输类型必须以 _ 开头；未知的非下划线传输类型保留给未来的 ACP 变体。

stdio 传输

当 Agent 支持 session.mcp.stdio 时，客户端可以使用 stdio 传输指定 MCP 服务器配置。

字段	类型	描述
`type`	`string`	必需。必须为 `"stdio"` 以指示 stdio 传输。
`name`	`string`	必需。服务器的人类可读标识符。
`command`	`string`	必需。MCP 服务器可执行文件的绝对路径。
`args`	`array`	必需。传递给服务器的命令行参数。
`env`	`EnvVariable[]`	启动服务器时设置的环境变量。

EnvVariable 对象包含以下字段：

字段	类型	描述
`name`	`string`	环境变量的名称。
`value`	`string`	环境变量的值。

stdio 传输配置示例：

{
  "type": "stdio",
  "name": "workspace-tools",
  "command": "/path/to/mcp-server",
  "args": ["--stdio"],
  "env": [
    {
      "name": "API_KEY",
      "value": "secret123"
    }
  ]
}

HTTP 传输

当 Agent 支持 session.mcp.http 时，客户端可以使用 HTTP 传输指定 MCP 服务器配置。

字段	类型	描述
`type`	`string`	必需。必须为 `"http"` 以指示 HTTP 传输。
`name`	`string`	必需。服务器的人类可读标识符。
`url`	`string`	必需。MCP 服务器的 URL。
`headers`	`HttpHeader[]`	必需。发送到服务器的请求中包含的 HTTP 头。

HttpHeader 对象包含以下字段：

字段	类型	描述
`name`	`string`	HTTP 头的名称。
`value`	`string`	HTTP 头的值。

HTTP 传输配置示例：

{
  "type": "http",
  "name": "api-server",
  "url": "https://api.example.com/mcp",
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer token123"
    },
    {
      "name": "Content-Type",
      "value": "application/json"
    }
  ]
}

检查传输支持

在使用 stdio 或 HTTP 传输之前，客户端必须在初始化期间验证 Agent 的能力：

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 2,
    "capabilities": {
      "session": {
        "mcp": {
          "stdio": {},
          "http": {}
        }
      }
    }
  }
}

如果 session.mcp.stdio 被省略或为 null，Agent 不支持 stdio 传输。如果 session.mcp.http 被省略或为 null，Agent 不支持 HTTP 传输。提供 {} 表示 Agent 支持相应的传输。

Agent 应该连接到客户端指定的所有 MCP 服务器。

客户端可以使用此功能通过包含自己的 MCP 服务器来直接向底层语言模型提供工具。