初始化

所有 Agent Client Protocol 连接的起始

初始化阶段允许客户端和 Agent 协商协议版本、能力和认证方式。

初始化流程

在创建会话之前，客户端必须通过调用 initialize 方法初始化连接，包含：

支持的最新协议版本
支持的能力

它们应当同时向 Agent 提供名称和版本。

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientCapabilities": {
      "fs": {
        "readTextFile": true,
        "writeTextFile": true
      },
      "terminal": true
    },
    "clientInfo": {
      "name": "my-client",
      "title": "My Client",
      "version": "1.0.0"
    }
  }
}

Agent 必须回复所选的协议版本及其支持的能力。它应当同时向客户端提供名称和版本：

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "loadSession": true,
      "promptCapabilities": {
        "image": true,
        "audio": true,
        "embeddedContext": true
      },
      "mcpCapabilities": {
        "http": true,
        "sse": true
      }
    },
    "agentInfo": {
      "name": "my-agent",
      "title": "My Agent",
      "version": "1.0.0"
    },
    "authMethods": []
  }
}

协议版本

initialize 请求和响应中出现的协议版本是一个整数，用于标识**主（MAJOR）**协议版本。该版本仅在引入破坏性变更时递增。客户端和 Agent 必须就协议版本达成一致，并按照其规范行事。参见能力了解非破坏性功能如何引入。

版本协商

initialize 请求必须包含客户端支持的最新协议版本。如果 Agent 支持所请求的版本，它必须以相同版本响应。否则，Agent 必须以其支持的最新版本响应。如果客户端不支持 Agent 在 initialize 响应中指定的版本，客户端应当关闭连接并告知用户。

能力

能力描述客户端和 Agent 支持的功能。

initialize 请求中包含的所有能力都是可选的。客户端和 Agent 应当支持对端能力的所有可能组合。

引入新能力不被视为破坏性变更。因此，客户端和 Agent 必须将 initialize 请求中省略的所有能力视为不支持。

能力是高层次的，不附着于特定的基础协议概念。

能力可以指定协议方法、通知或其参数子集的可用性。它们也可以标识 Agent 或客户端实现的行为。

实现还可以使用 _meta 字段宣告自定义能力以表示对协议扩展的支持。

客户端能力

客户端应当指定是否支持以下能力：

文件系统

字段	类型	描述
`readTextFile`	boolean	`fs/read_text_file` 方法可用。
`writeTextFile`	boolean	`fs/write_text_file` 方法可用。

了解更多关于文件系统方法

终端

字段	类型	描述
`terminal`	boolean	所有 `terminal/*` 方法可用，允许 Agent 执行和管理 shell 命令。

了解更多关于终端

布尔配置选项

字段	类型	描述
`session.configOptions.boolean`	BooleanConfigOptionCapabilities 对象	客户端支持 `boolean` 会话配置选项。任何层级的省略或 `null` 表示客户端未宣告支持。提供 `{}` 表示 Agent 可以在 v1 `configOptions` 负载中包含 `type: "boolean"` 选项。

了解更多关于会话配置选项

Agent 能力

Agent 应当指定是否支持以下能力：

字段	类型	描述
`loadSession`	boolean	默认：false。`session/load` 方法可用。
`promptCapabilities`	PromptCapabilities 对象	指示 `session/prompt` 请求中可能包含的不同类型内容的对象。
`auth`	AgentAuthCapabilities 对象	Agent 支持的与认证相关的能力。

提示能力

作为基线，所有 Agent 必须在 session/prompt 请求中支持 ContentBlock::Text 和 ContentBlock::ResourceLink。可选地，它们可以通过指定以下能力支持更丰富的内容类型：

字段	类型	描述
`image`	boolean	默认：false。提示可以包含 `ContentBlock::Image`。
`audio`	boolean	默认：false。提示可以包含 `ContentBlock::Audio`。
`embeddedContext`	boolean	默认：false。提示可以包含 `ContentBlock::Resource`。

MCP 能力

字段	类型	描述
`http`	boolean	默认：false。Agent 支持通过 HTTP 连接到 MCP 服务器。
`sse`	boolean	默认：false。Agent 支持通过 SSE 连接到 MCP 服务器。注意：该传输已被 MCP 规范弃用。

认证能力

字段	类型	描述
`logout`	LogoutCapabilities 对象	`logout` 方法可用。

了解更多关于认证

会话能力

作为基线，所有 Agent 必须支持 session/new、session/prompt、session/cancel 和 session/update。可选地，它们可以通过指定额外能力来支持其他会话方法和通知。

字段	类型	描述
`delete`	SessionDeleteCapabilities 对象	`session/delete` 方法可用。省略或 `null` 均表示 Agent 未宣告支持。提供空对象表示 Agent 支持从 `session/list` 中删除会话。
`additionalDirectories`	SessionAdditionalDirectoriesCapabilities 对象	Agent 在支持的会话生命周期请求上支持 `additionalDirectories`。省略或 `null` 均表示 Agent 未宣告支持。提供 `{}` 表示 Agent 支持额外的工作区根目录。

session/load 仍由顶层 load_session 能力处理。这将在未来版本的协议中统一。

实现信息

客户端和 Agent 应当分别在 clientInfo 和 agentInfo 字段中提供其实现信息。两者都接受以下三个字段：

字段	类型	描述
`name`	string	用于编程或逻辑用途，但如果 title 不存在，可以作为显示名称的后备。
`title`	string	用于 UI 和终端用户场景——优化为人类可读且易于理解。如果未提供，应使用 name 进行显示。
`version`	string	实现的版本。可向用户显示或用于调试或指标目的。

注意：在未来版本的协议中，此信息将是必需的。

一旦连接初始化完成，你就可以创建会话并开始与 Agent 的对话。