Schema

Agent Client Protocol 的 Schema 定义

Schema 文件可以直接从最新 GitHub 发布下载。

Agent

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

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

authenticate

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

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

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

参见协议文档：初始化

AuthenticateRequest

authenticate 方法的请求参数。指定要使用的认证方法。类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

methodId

AuthMethodId

必需

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

AuthenticateResponse

authenticate 方法的响应。类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

initialize

与客户端建立连接并协商协议能力。此方法在连接开始时调用一次以：

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

Agent 应以其支持的协议版本和能力响应。参见协议文档：初始化

InitializeRequest

initialize 方法的请求参数。由客户端发送以建立连接并协商能力。参见协议文档：初始化类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

clientCapabilities

ClientCapabilities

客户端支持的能力。

默认：{"fs":{"readTextFile":false,"writeTextFile":false},"terminal":false}

clientInfo

Implementation | null

发送给 Agent 的客户端名称和版本信息。注意：在未来版本的协议中，这将是必需的。

protocolVersion

ProtocolVersion

必需

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

InitializeResponse

initialize 方法的响应。包含协商的协议版本和 Agent 能力。参见协议文档：初始化类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

agentCapabilities

AgentCapabilities

Agent 支持的能力。

默认：{"loadSession":false,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false},"mcpCapabilities":{"http":false,"sse":false},"sessionCapabilities":{},"auth":{}}

agentInfo

Implementation | null

发送给客户端的 Agent 名称和版本信息。注意：在未来版本的协议中，这将是必需的。

authMethods

AuthMethod[]

Agent 支持的认证方法。

默认：[]

protocolVersion

ProtocolVersion

必需

如果 Agent 支持客户端指定的协议版本，则为该版本，否则为 Agent 支持的最新协议版本。如果客户端不支持此版本，应断开连接。

logout

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

LogoutRequest

logout 方法的请求参数。终止当前认证会话。类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

LogoutResponse

logout 方法的响应。类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

session/cancel

取消会话的进行中操作。这是客户端发送的通知，用于取消正在进行的提示回合。收到此通知后，Agent 应当：

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

参见协议文档：取消

CancelNotification

取消会话进行中操作的通知。参见协议文档：取消类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

sessionId

SessionId

必需

要取消操作的会话的 ID。

session/close

关闭活跃会话并释放与之关联的所有资源。此方法仅在 Agent 宣告 sessionCapabilities.close 能力时可用。Agent 必须取消任何进行中的工作（就像调用了 session/cancel 一样），然后释放与会话关联的所有资源。

CloseSessionRequest

关闭活跃会话的请求参数。如果支持，Agent 必须取消与会话相关的任何进行中的工作（将其视为调用了 session/cancel），然后释放与会话关联的所有资源。仅在 Agent 支持 sessionCapabilities.close 能力时可用。类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

sessionId

SessionId

必需

要关闭的会话的 ID。

CloseSessionResponse

关闭会话的响应。类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

session/delete

从 session/list 中删除已有会话。此方法仅在 Agent 宣告 sessionCapabilities.delete 能力时可用。

DeleteSessionRequest

从 session/list 中删除已有会话的请求参数。仅在 Agent 支持 sessionCapabilities.delete 能力时可用。类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

sessionId

SessionId

必需

要删除的会话的 ID。

DeleteSessionResponse

删除会话的响应。类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

session/list

列出 Agent 已知的已有会话。此方法仅在 Agent 宣告 sessionCapabilities.list 能力时可用。Agent 应返回会话的元数据，支持可选的过滤和分页。

ListSessionsRequest

列出已有会话的请求参数。仅在 Agent 支持 sessionCapabilities.list 能力时可用。类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

cursor

string | null

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

cwd

string | null

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

ListSessionsResponse

列出会话的响应。类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

nextCursor

string | null

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

sessions

SessionInfo[]

必需

会话信息对象数组

session/load

加载已有会话以恢复之前的对话。此方法仅在 Agent 宣告 loadSession 能力时可用。Agent 应当：

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

参见协议文档：加载会话

LoadSessionRequest

加载已有会话的请求参数。仅在 Agent 支持 loadSession 能力时可用。参见协议文档：加载会话类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

additionalDirectories

“string”[]

要为此会话激活的额外工作区根目录。每个路径必须是绝对路径。省略或为空时，不激活额外根目录。非空时，这是加载会话的完整结果额外根目录列表。只要请求的 cwd 与会话的 cwd 匹配，它可以与任何之前使用或报告的列表不同。

cwd

string

必需

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

mcpServers

McpServer[]

必需

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

sessionId

SessionId

必需

要加载的会话的 ID。

LoadSessionResponse

加载已有会话的响应。类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

configOptions

SessionConfigOption[] | null

如果 Agent 支持的初始会话配置选项。

modes

SessionModeState | null

如果 Agent 支持的初始模式状态。参见协议文档：会话模式

session/new

与 Agent 创建新的对话会话。会话代表具有自己历史和状态的独立对话上下文。Agent 应当：

创建新的会话上下文
连接到任何指定的 MCP 服务器
返回唯一的会话 ID 用于未来请求

如果 Agent 要求认证，可能返回 auth_required 错误。参见协议文档：会话设置

NewSessionRequest

创建新会话的请求参数。参见协议文档：创建会话类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

additionalDirectories

“string”[]

此会话的额外工作区根目录。每个路径必须是绝对路径。这些扩展会话的文件系统范围而不更改 cwd，cwd 仍然是相对路径的基准。省略或为空时，不为新会话激活额外根目录。

cwd

string

必需

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

mcpServers

McpServer[]

必需

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

NewSessionResponse

创建新会话的响应。参见协议文档：创建会话类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

configOptions

SessionConfigOption[] | null

如果 Agent 支持的初始会话配置选项。

modes

SessionModeState | null

如果 Agent 支持的初始模式状态。参见协议文档：会话模式

sessionId

SessionId

必需

创建的会话的唯一标识符。用于此对话的所有后续请求。

session/prompt

在会话中处理用户提示。此方法处理提示的整个生命周期：

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

参见协议文档：提示回合

PromptRequest

向 Agent 发送用户提示的请求参数。包含用户的消息和任何额外的上下文。参见协议文档：用户消息类型： 对象属性：

_meta

object | null

_meta 属性由 ACP 保留，允许客户端和 Agent 在其交互中附加额外的元数据。实现不得对这些键的值做出假设。参见协议文档：可扩展性

prompt

ContentBlock[]

必需

组成用户消息的内容块。作为基线，Agent 必须支持 ContentBlock::Text 和 ContentBlock::ResourceLink，而其他变体通过 PromptCapabilities 可选启用。客户端必须根据 PromptCapabilities 调整其界面。客户端可以以 ContentBlock::Resource 或 ContentBlock::ResourceLink 形式包含引用的上下文片段。当可用时，ContentBlock::Resource 是首选，因为它避免了额外的往返，并允许消息包含来自 Agent 可能无法访问的来源的上下文片段。

sessionId

SessionId

必需

注意：Schema 页面内容较长，以上为通过 WebFetch 获取的主要部分。完整的 Schema 定义（包括所有类型定义如 ClientCapabilities、AgentCapabilities、ContentBlock、SessionInfo 等）请参考官方 Schema 文件或在线 Schema 文档。