会话设置

创建和加载会话

会话代表客户端与 Agent 之间的特定对话或线程。每个会话维护自己的上下文、对话历史和状态，允许与同一 Agent 进行多个独立的交互。

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

会话设置流程

创建会话

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

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

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

Agent 必须回复一个标识此对话的唯一会话 ID：

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

加载会话

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

检查支持

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

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "loadSession": true
    }
  }
}

如果 loadSession 为 false 或不存在，则 Agent 不支持加载会话，客户端不得尝试调用 session/load。

加载会话

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

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

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

Agent 必须以 session/update 通知的形式（类似 session/prompt）向客户端重放整个对话。例如，对话历史中的一条用户消息：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_789xyz",
    "update": {
      "sessionUpdate": "user_message_chunk",
      "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_chunk",
      "messageId": "msg_agent_c42b9",
      "content": {
        "type": "text",
        "text": "The capital of France is Paris."
      }
    }
  }
}

如果 Agent 在重放期间提供消息 ID，每个 messageId 是重放消息的不透明唯一标识符。当所有对话条目都已流式传输给客户端后，Agent 必须响应原始的 session/load 请求。

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

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

恢复会话

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

检查支持

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

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "resume": {}
      }
    }
  }
}

如果 sessionCapabilities.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": [
      {
        "name": "filesystem",
        "command": "/path/to/mcp-server",
        "args": ["--mode", "filesystem"],
        "env": []
      }
    ]
  }
}

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

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

当 Agent 支持这些功能时，响应可以还包含初始模式、模型或会话配置状态。

关闭活跃会话

宣告 sessionCapabilities.close 的 Agent 允许客户端告知 Agent 取消该会话的所有进行中的工作并释放与该活跃会话关联的所有资源。

检查支持

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

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "close": {}
      }
    }
  }
}

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

关闭会话

要关闭活跃会话，客户端必须使用会话 ID 调用 session/close 方法：

{
  "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 可以返回错误。

额外工作区根目录

宣告 sessionCapabilities.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 宣告 sessionCapabilities.additionalDirectories 时才发送 additionalDirectories。

会话 ID

session/new 返回的会话 ID 是对话上下文的唯一标识符。客户端使用此 ID 来：

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

工作目录

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

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

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

MCP 服务器

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

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

MCP 服务器可以使用不同的传输方式连接。

所有 Agent 必须支持 stdio 传输，而 HTTP 和 SSE 传输是可选能力，可在初始化期间检查。

虽然规范不要求，但新的 Agent 应当支持 HTTP 传输以确保与现代 MCP 服务器的兼容性。

传输类型

Stdio 传输

所有 Agent 必须支持通过 stdio（标准输入/输出）连接到 MCP 服务器。这是默认的传输机制。

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

EnvVariable 对象包含以下字段：

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

Stdio 传输配置示例：

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

HTTP 传输

当 Agent 支持 mcpCapabilities.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"
    }
  ]
}

SSE 传输

当 Agent 支持 mcpCapabilities.sse 时，客户端可以使用 SSE 传输指定 MCP 服务器配置。此传输已被 MCP 规范弃用。

字段	类型	描述
`type`	string	必需。必须为 `"sse"` 以指示 SSE 传输。
`name`	string	必需。服务器的人类可读标识符。
`url`	string	必需。SSE 端点的 URL。
`headers`	HttpHeader[]	必需。建立 SSE 连接时包含的 HTTP 头。

SSE 传输配置示例：

{
  "type": "sse",
  "name": "event-stream",
  "url": "https://events.example.com/mcp",
  "headers": [
    {
      "name": "X-API-Key",
      "value": "apikey456"
    }
  ]
}

检查传输支持

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

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "mcpCapabilities": {
        "http": true,
        "sse": true
      }
    }
  }
}

如果 mcpCapabilities.http 为 false 或不存在，则 Agent 不支持 HTTP 传输。如果 mcpCapabilities.sse 为 false 或不存在，则 Agent 不支持 SSE 传输。Agent 应当连接到客户端指定的所有 MCP 服务器。客户端可以使用此能力通过包含自己的 MCP 服务器直接向底层语言模型提供工具。