Schema

Agent Client Protocol 的 Schema 定义

Agent

定义所有符合 ACP 的 Agent 必须实现的接口。

Agent 是使用生成式 AI 自主修改代码的程序。它们处理来自客户端的请求，并使用语言模型和工具执行任务。

authenticate

使用指定的认证方法对客户端进行认证。

当 Agent 在允许创建会话之前要求认证时调用。客户端提供在初始化期间声明的认证方法 ID。

成功认证后，客户端可以继续使用 new_session 创建会话，而不会收到 auth_required 错误。

AuthenticateRequest

authenticate 方法的请求参数。

指定要使用的认证方法。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

methodId

string

必需

要使用的认证方法 ID。必须是 initialize 响应中声明的方法之一。

AuthenticateResponse

authenticate 方法的响应。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

initialize

与客户端建立连接并协商协议能力。

此方法在连接开始时调用一次以：

• 协商要使用的协议版本
• 在客户端和 Agent 之间交换能力信息
• 确定可用的认证方法

Agent 应以其支持的协议版本和能力响应。

InitializeRequest

initialize 方法的请求参数。

由客户端发送以建立连接并协商能力。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

capabilities

ClientCapabilities

客户端支持的能力。

默认值：{}

clientInfo

Implementation | null

发送给 Agent 的客户端名称和版本信息。

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

protocolVersion

ProtocolVersion

必需

客户端支持的最新协议版本。

InitializeResponse

initialize 方法的响应。

包含协商的协议版本和 Agent 能力。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

agentInfo

Implementation | null

发送给客户端的 Agent 名称和版本信息。

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

authMethods

AuthMethod[]

Agent 支持的认证方法。

默认值：[]

capabilities

AgentCapabilities

Agent 支持的能力。

默认值：{"auth":{}}

protocolVersion

ProtocolVersion

必需

如果 Agent 支持客户端指定的协议版本则为该版本，否则为 Agent 支持的最新协议版本。

如果客户端不支持此版本，应断开连接。

logout

登出当前认证状态。

成功登出后，所有新会话都需要认证。不保证正在运行的会话的行为。

LogoutRequest

logout 方法的请求参数。

终止当前认证会话。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

参阅协议文档：

LogoutResponse

logout 方法的响应。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

参阅协议文档：

session/cancel

取消会话的正在进行的操作。

这是客户端发送的通知，用于取消正在进行的提示轮次。

收到此通知后，Agent 应该：

• 尽快停止所有语言模型请求
• 中止所有正在进行的工具调用
• 发送任何待处理的 session/update 通知
• 以 StopReason::Cancelled 响应原始的 session/prompt 请求

CancelNotification

取消会话正在进行的操作的通知。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

sessionId

SessionId

必需

要取消操作的会话 ID。

session/close

关闭活动会话并释放与之关联的所有资源。

此方法仅在 Agent 声明 session.close 能力时可用。

Agent 必须取消任何正在进行的工作（如同调用了 session/cancel），然后释放与会话关联的所有资源。

CloseSessionRequest

关闭活动会话的请求参数。

如果支持，Agent 必须取消与会话相关的任何正在进行的工作（视为调用了 session/cancel），然后释放与会话关联的所有资源。

仅在 Agent 支持 session.close 能力时可用。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

sessionId

SessionId

必需

要关闭的会话 ID。

CloseSessionResponse

关闭会话的响应。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

session/delete

从 session/list 中删除已有会话。

此方法仅在 Agent 声明 session.delete 能力时可用。

DeleteSessionRequest

从 session/list 中删除已有会话的请求参数。

仅在 Agent 支持 session.delete 能力时可用。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

sessionId

SessionId

必需

要删除的会话 ID。

DeleteSessionResponse

删除会话的响应。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

session/list

列出 Agent 已知的已有会话。

此方法仅在 Agent 声明 session.list 能力时可用。

Agent 应返回会话的元数据，支持可选的过滤和分页。

ListSessionsRequest

列出现有会话的请求参数。

仅在 Agent 支持 session.list 能力时可用。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

cursor

string | null

来自前一次响应 nextCursor 字段的不透明游标令牌，用于基于游标的分页

cwd

string | null

按工作目录过滤会话。必须为绝对路径。

ListSessionsResponse

列出会话的响应。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

nextCursor

string | null

不透明游标令牌。如果存在，将其传入下一次请求的 cursor 参数以获取下一页。如果不存在，表示没有更多结果。

sessions

SessionInfo[]

必需

会话信息对象数组

session/load

加载已有会话以恢复之前的对话。

此方法仅在 Agent 声明 session.load 能力时可用。

Agent 应该：

• 恢复会话上下文和对话历史
• 连接到指定的 MCP 服务器
• 通过通知将整个对话历史流式传输回客户端

LoadSessionRequest

加载已有会话的请求参数。

仅在 Agent 支持 session.load 能力时可用。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

additionalDirectories

string[]

要为此会话激活的额外工作区根。每个路径必须为绝对路径。

省略或为空时，不激活额外根。非空时，这是已加载会话的完整额外根列表。只要请求的 cwd 与会话的 cwd 匹配，它可以与任何先前使用或报告的列表不同。

cwd

string

必需

此会话的工作目录。

mcpServers

McpServer[]

必需

要为此会话连接的 MCP 服务器列表。

sessionId

SessionId

必需

要加载的会话 ID。

LoadSessionResponse

加载已有会话的响应。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

configOptions

SessionConfigOption[] | null

如果 Agent 支持，则为初始会话配置选项。

session/new

与 Agent 创建新的对话会话。

会话代表具有自己历史和状态的独立对话上下文。

Agent 应该：

• 创建新的会话上下文
• 连接到任何指定的 MCP 服务器
• 返回唯一的会话 ID 用于后续请求
• 如果 Agent 要求认证，可能返回 auth_required 错误。

NewSessionRequest

创建新会话的请求参数。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

参阅协议文档：可扩展性

additionalDirectories

string[]

此会话的额外工作区根。每个路径必须为绝对路径。

这些扩展会话的工作区范围而不改变 cwd，cwd 仍然是相对路径的基准。省略或为空时，不为新会话激活额外根。

cwd

string

必需

此会话的工作目录。必须为绝对路径。

mcpServers

McpServer[]

必需

Agent 应连接到的 MCP（Model Context Protocol）服务器列表。

NewSessionResponse

创建新会话的响应。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

参阅协议文档：可扩展性

configOptions

SessionConfigOption[] | null

如果 Agent 支持，则为初始会话配置选项。

sessionId

SessionId

必需

已创建会话的唯一标识符。

用于此对话的所有后续请求。

session/prompt

在会话中处理用户提示。

此方法处理提示的整个生命周期：

• 接收带有可选上下文（文件、图像等）的用户消息
• 使用语言模型处理提示
• 向客户端报告语言模型内容和工具调用
• 请求运行工具的权限
• 执行任何请求的工具调用
• 在轮次完成时返回并附带停止原因

参阅协议文档：提示轮次

PromptRequest

向 Agent 发送用户提示的请求参数。

包含用户的消息和任何附加上下文。

参阅协议文档：用户消息

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

参阅协议文档：可扩展性

prompt

ContentBlock[]

必需

组成用户消息的内容块。

作为基线，Agent 必须 支持 ContentBlock::Text 和 ContentBlock::ResourceLink，而其他变体通过 PromptCapabilities 可选启用。

客户端 必须 根据 PromptCapabilities 调整其界面。

客户端 可以 将引用的上下文片段作为 ContentBlock::Resource 或 ContentBlock::ResourceLink 包含。

可用时，ContentBlock::Resource 是首选的，因为它避免了额外的往返，并允许消息包含来自 Agent 可能无法访问的来源的上下文片段。

sessionId

SessionId

必需

要将此用户消息发送到的会话 ID

PromptResponse

处理用户提示的响应。

参阅协议文档：检查完成

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

参阅协议文档：可扩展性

stopReason

StopReason

必需

指示 Agent 停止处理轮次的原因。

session/resume

恢复已有会话而不返回先前的消息。

此方法仅在 Agent 声明 session.resume 能力时可用。

Agent 应恢复会话上下文，允许对话继续而无需重放消息历史（与 session/load 不同）。

ResumeSessionRequest

恢复已有会话的请求参数。

恢复已有会话而不返回先前的消息（与 session/load 不同）。这对可以恢复会话但不实现完整会话加载的 Agent 很有用。

仅在 Agent 支持 session.resume 能力时可用。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

参阅协议文档：可扩展性

additionalDirectories

string[]

要为此会话激活的额外工作区根。每个路径必须为绝对路径。

省略或为空时，不激活额外根。非空时，这是已恢复会话的完整额外根列表。只要请求的 cwd 与会话的 cwd 匹配，它可以与任何先前使用或报告的列表不同。

cwd

string

必需

此会话的工作目录。

mcpServers

McpServer[]

要为此会话连接的 MCP 服务器列表。

sessionId

SessionId

必需

要恢复的会话 ID。

ResumeSessionResponse

恢复已有会话的响应。

类型：Object

属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现 不得 对这些键上的值做出假设。

参阅协议文档：可扩展性

configOptions

SessionConfigOption[] | null

如果 Agent 支持，则为初始会话配置选项。

session/set_config_option

设置会话配置选项的值。

参阅协议文档：设置配置选项

注意：完整 Schema 定义请参阅官方 JSON Schema 文件。