{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Agent Client Protocol", "anyOf": [ { "title": "Agent", "description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility", "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": ["2.0"] } }, "required": ["jsonrpc"], "anyOf": [ { "title": "Request", "allOf": [ { "$ref": "#/$defs/AgentRequest" } ] }, { "title": "Response", "allOf": [ { "$ref": "#/$defs/AgentResponse" } ] }, { "title": "Notification", "allOf": [ { "$ref": "#/$defs/AgentNotification" } ] } ] }, { "title": "Client", "description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility", "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": ["2.0"] } }, "required": ["jsonrpc"], "anyOf": [ { "title": "Request", "allOf": [ { "$ref": "#/$defs/ClientRequest" } ] }, { "title": "Response", "allOf": [ { "$ref": "#/$defs/ClientResponse" } ] }, { "title": "Notification", "allOf": [ { "$ref": "#/$defs/ClientNotification" } ] } ] }, { "title": "ProtocolLevel", "description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility", "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": ["2.0"] }, "method": { "description": "The notification method name.", "type": "string" }, "params": { "description": "Method-specific notification parameters.", "anyOf": [ { "description": "General protocol-level notifications that all sides are expected to\nimplement.\n\nNotifications whose methods start with '$/' are messages which\nare protocol implementation dependent and might not be implementable in all\nclients or agents. For example if the implementation uses a single threaded\nsynchronous programming language then there is little it can do to react to\na `$/cancel_request` notification. If an agent or client receives\nnotifications starting with '$/' it is free to ignore the notification.\n\nNotifications do not expect a response.", "anyOf": [ { "title": "CancelRequestNotification", "description": "Cancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MAY cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)", "allOf": [ { "$ref": "#/$defs/CancelRequestNotification" } ] } ] }, { "type": "null" } ] } }, "required": ["jsonrpc", "method"], "x-docs-ignore": true } ], "$defs": { "AgentRequest": { "description": "A JSON-RPC request object.", "type": "object", "properties": { "id": { "description": "The request id used to correlate the matching response.", "allOf": [ { "$ref": "#/$defs/RequestId" } ] }, "method": { "description": "The method name to invoke.", "type": "string" }, "params": { "description": "Method-specific request parameters.", "anyOf": [ { "description": "All possible requests that an agent can send to a client.\n\nThis enum is used internally for routing RPC requests. You typically won't need\nto use this directly.\n\nThis enum encompasses all method calls from agent to client.", "anyOf": [ { "title": "WriteTextFileRequest", "description": "Writes content to a text file in the client's file system.\n\nOnly available if the client advertises the `fs.writeTextFile` capability.\nAllows the agent to create or modify files within the client's environment.\n\nSee protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)", "allOf": [ { "$ref": "#/$defs/WriteTextFileRequest" } ] }, { "title": "ReadTextFileRequest", "description": "Reads content from a text file in the client's file system.\n\nOnly available if the client advertises the `fs.readTextFile` capability.\nAllows the agent to access file contents within the client's environment.\n\nSee protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)", "allOf": [ { "$ref": "#/$defs/ReadTextFileRequest" } ] }, { "title": "RequestPermissionRequest", "description": "Requests permission from the user for a tool call operation.\n\nCalled by the agent when it needs user authorization before executing\na potentially sensitive operation. The client should present the options\nto the user and return their decision.\n\nIf the client cancels the prompt turn via `session/cancel`, it MUST\nrespond to this request with `RequestPermissionOutcome::Cancelled`.\n\nSee protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission)", "allOf": [ { "$ref": "#/$defs/RequestPermissionRequest" } ] }, { "title": "CreateTerminalRequest", "description": "Executes a command in a new terminal\n\nOnly available if the `terminal` Client capability is set to `true`.\n\nReturns a `TerminalId` that can be used with other terminal methods\nto get the current output, wait for exit, and kill the command.\n\nThe `TerminalId` can also be used to embed the terminal in a tool call\nby using the `ToolCallContent::Terminal` variant.\n\nThe Agent is responsible for releasing the terminal by using the `terminal/release`\nmethod.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)", "allOf": [ { "$ref": "#/$defs/CreateTerminalRequest" } ] }, { "title": "TerminalOutputRequest", "description": "Gets the terminal output and exit status\n\nReturns the current content in the terminal without waiting for the command to exit.\nIf the command has already exited, the exit status is included.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)", "allOf": [ { "$ref": "#/$defs/TerminalOutputRequest" } ] }, { "title": "ReleaseTerminalRequest", "description": "Releases a terminal\n\nThe command is killed if it hasn't exited yet. Use `terminal/wait_for_exit`\nto wait for the command to exit before releasing the terminal.\n\nAfter release, the `TerminalId` can no longer be used with other `terminal/*` methods,\nbut tool calls that already contain it, continue to display its output.\n\nThe `terminal/kill` method can be used to terminate the command without releasing\nthe terminal, allowing the Agent to call `terminal/output` and other methods.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)", "allOf": [ { "$ref": "#/$defs/ReleaseTerminalRequest" } ] }, { "title": "WaitForTerminalExitRequest", "description": "Waits for the terminal command to exit and return its exit status\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)", "allOf": [ { "$ref": "#/$defs/WaitForTerminalExitRequest" } ] }, { "title": "KillTerminalRequest", "description": "Kills the terminal command without releasing the terminal\n\nWhile `terminal/release` will also kill the command, this method will keep\nthe `TerminalId` valid so it can be used with other methods.\n\nThis method can be helpful when implementing command timeouts which terminate\nthe command as soon as elapsed, and then get the final output so it can be sent\nto the model.\n\nNote: Call `terminal/release` when `TerminalId` is no longer needed.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)", "allOf": [ { "$ref": "#/$defs/KillTerminalRequest" } ] }, { "title": "CreateElicitationRequest", "description": "Requests structured user input via a form or URL.\n\nSee protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/elicitation)", "allOf": [ { "$ref": "#/$defs/CreateElicitationRequest" } ] }, { "title": "ExtMethodRequest", "description": "Handles extension method requests from the agent.\n\nAllows the Agent to send an arbitrary request that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "allOf": [ { "$ref": "#/$defs/ExtRequest" } ] } ] }, { "type": "null" } ] } }, "required": ["id", "method"], "x-docs-ignore": true }, "RequestId": { "description": "JSON RPC Request Id\n\nAn identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null \\[1\\] and Numbers SHOULD NOT contain fractional parts \\[2\\]\n\nThe Server MUST reply with the same value in the Response object if included. This member is used to correlate the context between the two objects.\n\n\\[1\\] The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling.\n\n\\[2\\] Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions.", "anyOf": [ { "title": "Null", "description": "The JSON-RPC `null` request id.", "type": "null" }, { "title": "Number", "description": "A numeric JSON-RPC request id.", "type": "integer", "format": "int64" }, { "title": "Str", "description": "A string JSON-RPC request id.", "type": "string" } ] }, "WriteTextFileRequest": { "description": "Request to write content to a text file.\n\nOnly available if the client supports the `fs.writeTextFile` capability.", "type": "object", "properties": { "sessionId": { "description": "The session ID for this request.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "path": { "description": "Absolute path to the file to write.", "type": "string" }, "content": { "description": "The text content to write to the file.", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "path", "content"], "x-side": "client", "x-method": "fs/write_text_file" }, "SessionId": { "description": "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)", "type": "string" }, "ReadTextFileRequest": { "description": "Request to read content from a text file.\n\nOnly available if the client supports the `fs.readTextFile` capability.", "type": "object", "properties": { "sessionId": { "description": "The session ID for this request.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "path": { "description": "Absolute path to the file to read.", "type": "string" }, "line": { "description": "Line number to start reading from (1-based).", "type": ["integer", "null"], "format": "uint32", "minimum": 0, "x-deserialize-default-on-error": true }, "limit": { "description": "Maximum number of lines to read.", "type": ["integer", "null"], "format": "uint32", "minimum": 0, "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "path"], "x-side": "client", "x-method": "fs/read_text_file" }, "RequestPermissionRequest": { "description": "Request for user permission to execute a tool call.\n\nSent when the agent needs authorization before performing a sensitive operation.\n\nSee protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission)", "type": "object", "properties": { "sessionId": { "description": "The session ID for this request.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "toolCall": { "description": "Details about the tool call requiring permission.", "allOf": [ { "$ref": "#/$defs/ToolCallUpdate" } ] }, "options": { "description": "Available permission options for the user to choose from.", "type": "array", "items": { "$ref": "#/$defs/PermissionOption" } }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "toolCall", "options"], "x-side": "client", "x-method": "session/request_permission" }, "ToolCallUpdate": { "description": "An update to an existing tool call.\n\nUsed to report progress and results as tools execute. All fields except\nthe tool call ID are optional - only changed fields need to be included.\n\nSee protocol docs: [Updating](https://agentclientprotocol.com/protocol/tool-calls#updating)", "type": "object", "properties": { "toolCallId": { "description": "The ID of the tool call being updated.", "allOf": [ { "$ref": "#/$defs/ToolCallId" } ] }, "kind": { "description": "Update the tool kind.", "anyOf": [ { "$ref": "#/$defs/ToolKind" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "status": { "description": "Update the execution status.", "anyOf": [ { "$ref": "#/$defs/ToolCallStatus" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "title": { "description": "Update the human-readable title.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "content": { "description": "Replace the content collection.", "type": ["array", "null"], "items": { "$ref": "#/$defs/ToolCallContent" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "locations": { "description": "Replace the locations collection.", "type": ["array", "null"], "items": { "$ref": "#/$defs/ToolCallLocation" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "rawInput": { "description": "Update the raw input.", "x-deserialize-default-on-error": true }, "rawOutput": { "description": "Update the raw output.", "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["toolCallId"] }, "ToolCallId": { "description": "Unique identifier for a tool call within a session.", "type": "string" }, "ToolKind": { "description": "Categories of tools that can be invoked.\n\nTool kinds help clients choose appropriate icons and optimize how they\ndisplay tool execution progress.\n\nSee protocol docs: [Creating](https://agentclientprotocol.com/protocol/tool-calls#creating)", "oneOf": [ { "description": "Reading files or data.", "type": "string", "const": "read" }, { "description": "Modifying files or content.", "type": "string", "const": "edit" }, { "description": "Removing files or data.", "type": "string", "const": "delete" }, { "description": "Moving or renaming files.", "type": "string", "const": "move" }, { "description": "Searching for information.", "type": "string", "const": "search" }, { "description": "Running commands or code.", "type": "string", "const": "execute" }, { "description": "Internal reasoning or planning.", "type": "string", "const": "think" }, { "description": "Retrieving external data.", "type": "string", "const": "fetch" }, { "description": "Switching the current session mode.", "type": "string", "const": "switch_mode" }, { "description": "Other tool types (default).", "type": "string", "const": "other" } ] }, "ToolCallStatus": { "description": "Execution status of a tool call.\n\nTool calls progress through different statuses during their lifecycle.\n\nSee protocol docs: [Status](https://agentclientprotocol.com/protocol/tool-calls#status)", "oneOf": [ { "description": "The tool call hasn't started running yet because the input is either\nstreaming or we're awaiting approval.", "type": "string", "const": "pending" }, { "description": "The tool call is currently running.", "type": "string", "const": "in_progress" }, { "description": "The tool call completed successfully.", "type": "string", "const": "completed" }, { "description": "The tool call failed with an error.", "type": "string", "const": "failed" } ] }, "ToolCallContent": { "description": "Content produced by a tool call.\n\nTool calls can produce different types of content including\nstandard content blocks (text, images) or file diffs.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content)", "oneOf": [ { "description": "Standard content block (text, images, resources).", "type": "object", "properties": { "type": { "type": "string", "const": "content" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/Content" } ] }, { "description": "File modification shown as a diff.", "type": "object", "properties": { "type": { "type": "string", "const": "diff" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/Diff" } ] }, { "description": "Embed a terminal created with `terminal/create` by its id.\n\nThe terminal must be added before calling `terminal/release`.\n\nSee protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminals)", "type": "object", "properties": { "type": { "type": "string", "const": "terminal" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/Terminal" } ] } ], "discriminator": { "propertyName": "type" } }, "ContentBlock": { "description": "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)", "oneOf": [ { "description": "Text content. May be plain text or formatted with Markdown.\n\nAll agents MUST support text content blocks in prompts.\nClients SHOULD render this text as Markdown.", "type": "object", "properties": { "type": { "type": "string", "const": "text" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/TextContent" } ] }, { "description": "Images for visual context or analysis.\n\nRequires the `image` prompt capability when included in prompts.", "type": "object", "properties": { "type": { "type": "string", "const": "image" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/ImageContent" } ] }, { "description": "Audio data for transcription or analysis.\n\nRequires the `audio` prompt capability when included in prompts.", "type": "object", "properties": { "type": { "type": "string", "const": "audio" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/AudioContent" } ] }, { "description": "References to resources that the agent can access.\n\nAll agents MUST support resource links in prompts.", "type": "object", "properties": { "type": { "type": "string", "const": "resource_link" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/ResourceLink" } ] }, { "description": "Complete resource contents embedded directly in the message.\n\nPreferred for including context as it avoids extra round-trips.\n\nRequires the `embeddedContext` prompt capability when included in prompts.", "type": "object", "properties": { "type": { "type": "string", "const": "resource" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/EmbeddedResource" } ] } ], "discriminator": { "propertyName": "type" } }, "Annotations": { "description": "Optional annotations for the client. The client can use annotations to inform how objects are used or displayed", "type": "object", "properties": { "audience": { "description": "Intended recipients for this content, such as the user or assistant.", "type": ["array", "null"], "items": { "$ref": "#/$defs/Role" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "lastModified": { "description": "Timestamp indicating when the underlying resource was last modified.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "priority": { "description": "Relative importance of this content when clients choose what to surface.", "type": ["number", "null"], "format": "double", "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "Role": { "description": "The sender or recipient of messages and data in a conversation.", "oneOf": [ { "description": "The assistant side of a conversation.", "type": "string", "const": "assistant" }, { "description": "The user side of a conversation.", "type": "string", "const": "user" } ] }, "TextContent": { "description": "Text provided to or from an LLM.", "type": "object", "properties": { "annotations": { "description": "Optional annotations that help clients decide how to display or route this content.", "anyOf": [ { "$ref": "#/$defs/Annotations" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "text": { "description": "Text payload carried by this content block.", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["text"] }, "ImageContent": { "description": "An image provided to or from an LLM.", "type": "object", "properties": { "annotations": { "description": "Optional annotations that help clients decide how to display or route this content.", "anyOf": [ { "$ref": "#/$defs/Annotations" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "data": { "description": "Base64-encoded media payload.", "type": "string" }, "mimeType": { "description": "MIME type describing the encoded media payload.", "type": "string" }, "uri": { "description": "URI associated with this resource or media payload.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["data", "mimeType"] }, "AudioContent": { "description": "Audio provided to or from an LLM.", "type": "object", "properties": { "annotations": { "description": "Optional annotations that help clients decide how to display or route this content.", "anyOf": [ { "$ref": "#/$defs/Annotations" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "data": { "description": "Base64-encoded media payload.", "type": "string" }, "mimeType": { "description": "MIME type describing the encoded media payload.", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["data", "mimeType"] }, "ResourceLink": { "description": "A resource that the server is capable of reading, included in a prompt or tool call result.", "type": "object", "properties": { "annotations": { "description": "Optional annotations that help clients decide how to display or route this content.", "anyOf": [ { "$ref": "#/$defs/Annotations" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "description": { "description": "Optional human-readable details shown with this protocol object.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "mimeType": { "description": "MIME type describing the encoded media payload.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "name": { "description": "Human-readable name shown for this protocol object.", "type": "string" }, "size": { "description": "Optional size of the linked resource in bytes, if known.", "type": ["integer", "null"], "format": "int64", "x-deserialize-default-on-error": true }, "title": { "description": "Optional display title for end-user UI.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "uri": { "description": "URI associated with this resource or media payload.", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["name", "uri"] }, "EmbeddedResourceResource": { "description": "Resource content that can be embedded in a message.", "anyOf": [ { "title": "TextResourceContents", "description": "Text resource contents embedded directly in the message.", "allOf": [ { "$ref": "#/$defs/TextResourceContents" } ] }, { "title": "BlobResourceContents", "description": "Binary resource contents embedded directly in the message.", "allOf": [ { "$ref": "#/$defs/BlobResourceContents" } ] } ] }, "TextResourceContents": { "description": "Text-based resource contents.", "type": "object", "properties": { "mimeType": { "description": "MIME type describing the encoded media payload.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "text": { "description": "Text payload carried by this content block.", "type": "string" }, "uri": { "description": "URI associated with this resource or media payload.", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["text", "uri"] }, "BlobResourceContents": { "description": "Binary resource contents.", "type": "object", "properties": { "blob": { "description": "Base64-encoded bytes for a binary resource payload.", "type": "string" }, "mimeType": { "description": "MIME type describing the encoded media payload.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "uri": { "description": "URI associated with this resource or media payload.", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["blob", "uri"] }, "EmbeddedResource": { "description": "The contents of a resource, embedded into a prompt or tool call result.", "type": "object", "properties": { "annotations": { "description": "Optional annotations that help clients decide how to display or route this content.", "anyOf": [ { "$ref": "#/$defs/Annotations" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "resource": { "description": "Embedded resource payload, either text or binary data.", "allOf": [ { "$ref": "#/$defs/EmbeddedResourceResource" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["resource"] }, "Content": { "description": "Standard content block (text, images, resources).", "type": "object", "properties": { "content": { "description": "The actual content block.", "allOf": [ { "$ref": "#/$defs/ContentBlock" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["content"] }, "Diff": { "description": "A diff representing file modifications.\n\nShows changes to files in a format suitable for display in the client UI.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content)", "type": "object", "properties": { "path": { "description": "The absolute file path being modified.", "type": "string" }, "oldText": { "description": "The original content (None for new files).", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "newText": { "description": "The new content after modification.", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["path", "newText"] }, "TerminalId": { "description": "Typed identifier used for terminal values on the wire.", "type": "string" }, "Terminal": { "description": "Embed a terminal created with `terminal/create` by its id.\n\nThe terminal must be added before calling `terminal/release`.\n\nSee protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminals)", "type": "object", "properties": { "terminalId": { "description": "Identifier of the terminal instance to embed in the content stream.", "allOf": [ { "$ref": "#/$defs/TerminalId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["terminalId"] }, "ToolCallLocation": { "description": "A file location being accessed or modified by a tool.\n\nEnables clients to implement \"follow-along\" features that track\nwhich files the agent is working with in real-time.\n\nSee protocol docs: [Following the Agent](https://agentclientprotocol.com/protocol/tool-calls#following-the-agent)", "type": "object", "properties": { "path": { "description": "The absolute file path being accessed or modified.", "type": "string" }, "line": { "description": "Optional line number within the file.", "type": ["integer", "null"], "format": "uint32", "minimum": 0, "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["path"] }, "PermissionOption": { "description": "An option presented to the user when requesting permission.", "type": "object", "properties": { "optionId": { "description": "Unique identifier for this permission option.", "allOf": [ { "$ref": "#/$defs/PermissionOptionId" } ] }, "name": { "description": "Human-readable label to display to the user.", "type": "string" }, "kind": { "description": "Hint about the nature of this permission option.", "allOf": [ { "$ref": "#/$defs/PermissionOptionKind" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["optionId", "name", "kind"] }, "PermissionOptionId": { "description": "Unique identifier for a permission option.", "type": "string" }, "PermissionOptionKind": { "description": "The type of permission option being presented to the user.\n\nHelps clients choose appropriate icons and UI treatment.", "oneOf": [ { "description": "Allow this operation only this time.", "type": "string", "const": "allow_once" }, { "description": "Allow this operation and remember the choice.", "type": "string", "const": "allow_always" }, { "description": "Reject this operation only this time.", "type": "string", "const": "reject_once" }, { "description": "Reject this operation and remember the choice.", "type": "string", "const": "reject_always" } ] }, "CreateTerminalRequest": { "description": "Request to create a new terminal and execute a command.", "type": "object", "properties": { "sessionId": { "description": "The session ID for this request.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "command": { "description": "The command to execute.", "type": "string" }, "args": { "description": "Array of command arguments.", "type": "array", "items": { "type": "string" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "env": { "description": "Environment variables for the command.", "type": "array", "items": { "$ref": "#/$defs/EnvVariable" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "cwd": { "description": "Working directory for the command. Must be an absolute path.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "outputByteLimit": { "description": "Maximum number of output bytes to retain.\n\nWhen the limit is exceeded, the Client truncates from the beginning of the output\nto stay within the limit.\n\nThe Client MUST ensure truncation happens at a character boundary to maintain valid\nstring output, even if this means the retained output is slightly less than the\nspecified limit.", "type": ["integer", "null"], "format": "uint64", "minimum": 0, "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "command"], "x-side": "client", "x-method": "terminal/create" }, "EnvVariable": { "description": "An environment variable to set when launching an MCP server.", "type": "object", "properties": { "name": { "description": "The name of the environment variable.", "type": "string" }, "value": { "description": "The value to set for the environment variable.", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["name", "value"] }, "TerminalOutputRequest": { "description": "Request to get the current output and status of a terminal.", "type": "object", "properties": { "sessionId": { "description": "The session ID for this request.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "terminalId": { "description": "The ID of the terminal to get output from.", "allOf": [ { "$ref": "#/$defs/TerminalId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "terminalId"], "x-side": "client", "x-method": "terminal/output" }, "ReleaseTerminalRequest": { "description": "Request to release a terminal and free its resources.", "type": "object", "properties": { "sessionId": { "description": "The session ID for this request.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "terminalId": { "description": "The ID of the terminal to release.", "allOf": [ { "$ref": "#/$defs/TerminalId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "terminalId"], "x-side": "client", "x-method": "terminal/release" }, "WaitForTerminalExitRequest": { "description": "Request to wait for a terminal command to exit.", "type": "object", "properties": { "sessionId": { "description": "The session ID for this request.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "terminalId": { "description": "The ID of the terminal to wait for.", "allOf": [ { "$ref": "#/$defs/TerminalId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "terminalId"], "x-side": "client", "x-method": "terminal/wait_for_exit" }, "KillTerminalRequest": { "description": "Request to kill a terminal without releasing it.", "type": "object", "properties": { "sessionId": { "description": "The session ID for this request.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "terminalId": { "description": "The ID of the terminal to kill.", "allOf": [ { "$ref": "#/$defs/TerminalId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "terminalId"], "x-side": "client", "x-method": "terminal/kill" }, "CreateElicitationRequest": { "description": "Request from the agent to elicit structured user input.\n\nThe agent sends this to the client to request information from the user,\neither via a form or by directing them to a URL.\nElicitations are tied to a session (optionally a tool call) or a request.", "type": "object", "properties": { "message": { "description": "A human-readable message describing what input is needed.", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "anyOf": [ { "description": "Form-based elicitation where the client renders a form from the provided schema.", "type": "object", "properties": { "mode": { "type": "string", "const": "form" } }, "required": ["mode"], "allOf": [ { "$ref": "#/$defs/ElicitationFormMode" } ] }, { "description": "URL-based elicitation where the client directs the user to a URL.", "type": "object", "properties": { "mode": { "type": "string", "const": "url" } }, "required": ["mode"], "allOf": [ { "$ref": "#/$defs/ElicitationUrlMode" } ] }, { "title": "other", "description": "Custom or future elicitation mode.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nClients that do not understand this mode should preserve the raw payload\nwhen storing, replaying, proxying, or forwarding elicitation requests.\nThey MUST NOT render it as a known elicitation mode.", "type": "object", "properties": { "mode": { "description": "Custom or future elicitation mode.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", "type": "string" } }, "required": ["mode"], "anyOf": [ { "title": "Session", "description": "Tied to a session, optionally to a specific tool call within that session.", "allOf": [ { "$ref": "#/$defs/ElicitationSessionScope" } ] }, { "title": "Request", "description": "Tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).", "allOf": [ { "$ref": "#/$defs/ElicitationRequestScope" } ] } ], "unevaluatedProperties": true, "not": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "form" } }, "required": ["mode"] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "url" } }, "required": ["mode"] } ] } } ], "required": ["message"], "x-side": "client", "x-method": "elicitation/create" }, "ElicitationSessionScope": { "description": "Session-scoped elicitation, optionally tied to a specific tool call.\n\nWhen `tool_call_id` is set, the elicitation is tied to a specific tool call.\nThis is useful when an agent receives an elicitation from an MCP server\nduring a tool call and needs to redirect it to the user.", "type": "object", "properties": { "sessionId": { "description": "The session this elicitation is tied to.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "toolCallId": { "description": "Optional tool call within the session.\n\nOptional. Omitted and `null` are equivalent and mean the elicitation is scoped to the\nsession without a specific tool call.", "anyOf": [ { "$ref": "#/$defs/ToolCallId" }, { "type": "null" } ], "x-deserialize-default-on-error": true } }, "required": ["sessionId"] }, "ElicitationRequestScope": { "description": "Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).", "type": "object", "properties": { "requestId": { "description": "The request this elicitation is tied to.", "allOf": [ { "$ref": "#/$defs/RequestId" } ] } }, "required": ["requestId"] }, "ElicitationSchema": { "description": "Type-safe elicitation schema for requesting structured user input.\n\nThis represents a JSON Schema object with primitive-typed properties,\nas required by the elicitation specification.", "type": "object", "properties": { "type": { "description": "Type discriminator. Always `\"object\"`.", "x-deserialize-default-on-error": true, "default": "object", "allOf": [ { "$ref": "#/$defs/ElicitationSchemaType" } ] }, "title": { "description": "Optional title for the schema.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "properties": { "description": "Property definitions (must be primitive types).", "type": "object", "default": {}, "additionalProperties": { "$ref": "#/$defs/ElicitationPropertySchema" } }, "required": { "description": "List of required property names.\n\nOptional. Omitted and `null` are equivalent and mean no property names are required.", "type": ["array", "null"], "items": { "type": "string" } }, "description": { "description": "Optional description of what this schema represents.\n\nOptional. Omitted and `null` are equivalent and mean no schema description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "ElicitationSchemaType": { "description": "Type discriminator for elicitation schemas.", "oneOf": [ { "description": "Object schema type.", "type": "string", "const": "object" } ] }, "ElicitationPropertySchema": { "description": "Property schema for elicitation form fields.\n\nEach variant corresponds to a JSON Schema `\"type\"` value.\nSingle-select enums use the `String` variant with `enum` or `oneOf` set.\nMulti-select enums use the `Array` variant.", "anyOf": [ { "description": "String property (or single-select enum when `enum`/`oneOf` is set).", "type": "object", "properties": { "type": { "type": "string", "const": "string" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/StringPropertySchema" } ] }, { "description": "Number (floating-point) property.", "type": "object", "properties": { "type": { "type": "string", "const": "number" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/NumberPropertySchema" } ] }, { "description": "Integer property.", "type": "object", "properties": { "type": { "type": "string", "const": "integer" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/IntegerPropertySchema" } ] }, { "description": "Boolean property.", "type": "object", "properties": { "type": { "type": "string", "const": "boolean" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/BooleanPropertySchema" } ] }, { "description": "Multi-select array property.", "type": "object", "properties": { "type": { "type": "string", "const": "array" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/MultiSelectPropertySchema" } ] }, { "title": "other", "description": "Custom or future elicitation property schema.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nClients that do not understand this property schema type should preserve\nthe raw schema when storing, replaying, proxying, or forwarding\nelicitation requests. They MUST NOT render it as a known input control.", "type": "object", "properties": { "type": { "description": "Custom or future elicitation property schema type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", "type": "string" } }, "required": ["type"], "not": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "string" } }, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "number" } }, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer" } }, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" } }, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "array" } }, "required": ["type"] } ] }, "additionalProperties": true } ] }, "StringFormat": { "description": "String format types for string properties in elicitation schemas.", "oneOf": [ { "description": "Email address format.", "type": "string", "const": "email" }, { "description": "URI format.", "type": "string", "const": "uri" }, { "description": "Date format (YYYY-MM-DD).", "type": "string", "const": "date" }, { "description": "Date-time format (ISO 8601).", "type": "string", "const": "date-time" } ] }, "EnumOption": { "description": "A titled enum option with a const value, human-readable title, and optional description.", "type": "object", "properties": { "const": { "description": "The constant value for this option.", "type": "string" }, "title": { "description": "Human-readable title for this option.", "type": "string" }, "description": { "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["const", "title"] }, "StringPropertySchema": { "description": "Schema for string properties in an elicitation form.\n\nWhen `enum` or `oneOf` is set, this represents a single-select enum\nwith `\"type\": \"string\"`.", "type": "object", "properties": { "title": { "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "minLength": { "description": "Minimum string length.\n\nOptional. Omitted and `null` are equivalent and mean there is no minimum length constraint.", "type": ["integer", "null"], "format": "uint32", "minimum": 0 }, "maxLength": { "description": "Maximum string length.\n\nOptional. Omitted and `null` are equivalent and mean there is no maximum length constraint.", "type": ["integer", "null"], "format": "uint32", "minimum": 0 }, "pattern": { "description": "Pattern the string must match.\n\nOptional. Omitted and `null` are equivalent and mean there is no pattern constraint.", "type": ["string", "null"] }, "format": { "description": "String format.\n\nOptional. Omitted and `null` are equivalent and mean there is no format constraint.", "anyOf": [ { "$ref": "#/$defs/StringFormat" }, { "type": "null" } ] }, "default": { "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "enum": { "description": "Enum values for untitled single-select enums.\nOptional. Omitted and `null` are equivalent and mean no untitled single-select choices are\ndeclared by `enum`.", "type": ["array", "null"], "items": { "type": "string" } }, "oneOf": { "description": "Titled enum options for titled single-select enums.\nOptional. Omitted and `null` are equivalent and mean no titled single-select choices are\ndeclared by `oneOf`.", "type": ["array", "null"], "items": { "$ref": "#/$defs/EnumOption" } }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "NumberPropertySchema": { "description": "Schema for number (floating-point) properties in an elicitation form.", "type": "object", "properties": { "title": { "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "minimum": { "description": "Minimum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive lower bound.", "type": ["number", "null"], "format": "double" }, "maximum": { "description": "Maximum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive upper bound.", "type": ["number", "null"], "format": "double" }, "default": { "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", "type": ["number", "null"], "format": "double", "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "IntegerPropertySchema": { "description": "Schema for integer properties in an elicitation form.", "type": "object", "properties": { "title": { "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "minimum": { "description": "Minimum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive lower bound.", "type": ["integer", "null"], "format": "int64" }, "maximum": { "description": "Maximum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive upper bound.", "type": ["integer", "null"], "format": "int64" }, "default": { "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", "type": ["integer", "null"], "format": "int64", "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "BooleanPropertySchema": { "description": "Schema for boolean properties in an elicitation form.", "type": "object", "properties": { "title": { "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "default": { "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", "type": ["boolean", "null"], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "MultiSelectItems": { "description": "Items for a multi-select (array) property schema.", "anyOf": [ { "description": "Multi-select string items with plain string values.", "type": "object", "properties": { "type": { "type": "string", "const": "string" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/StringMultiSelectItems" } ] }, { "title": "other", "description": "Custom or future typed multi-select items.", "type": "object", "properties": { "type": { "description": "Custom or future multi-select item type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", "type": "string" } }, "required": ["type"], "not": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "string" } }, "required": ["type"] } ] }, "additionalProperties": true }, { "title": "titled", "description": "Titled multi-select items with human-readable labels.", "allOf": [ { "$ref": "#/$defs/TitledMultiSelectItems" } ] } ] }, "StringMultiSelectItems": { "description": "String item schema for multi-select enum properties.", "type": "object", "properties": { "enum": { "description": "Allowed enum values.", "type": "array", "items": { "type": "string" } }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["enum"] }, "TitledMultiSelectItems": { "description": "Items definition for titled multi-select enum properties.", "type": "object", "properties": { "anyOf": { "description": "Titled enum options.", "type": "array", "items": { "$ref": "#/$defs/EnumOption" } }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["anyOf"] }, "MultiSelectPropertySchema": { "description": "Schema for multi-select (array) properties in an elicitation form.", "type": "object", "properties": { "title": { "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "minItems": { "description": "Minimum number of items to select.\n\nOptional. Omitted and `null` are equivalent and mean there is no minimum selection count.", "type": ["integer", "null"], "format": "uint64", "minimum": 0 }, "maxItems": { "description": "Maximum number of items to select.\n\nOptional. Omitted and `null` are equivalent and mean there is no maximum selection count.", "type": ["integer", "null"], "format": "uint64", "minimum": 0 }, "items": { "description": "The items definition describing allowed values.", "allOf": [ { "$ref": "#/$defs/MultiSelectItems" } ] }, "default": { "description": "Default selected values.\n\nOptional. Omitted and `null` are equivalent and mean no default selections are provided.", "type": ["array", "null"], "items": { "type": "string" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["items"] }, "ElicitationFormMode": { "description": "Form-based elicitation mode where the client renders a form from the provided schema.", "type": "object", "properties": { "requestedSchema": { "description": "A JSON Schema describing the form fields to present to the user.", "allOf": [ { "$ref": "#/$defs/ElicitationSchema" } ] } }, "anyOf": [ { "title": "Session", "description": "Tied to a session, optionally to a specific tool call within that session.", "allOf": [ { "$ref": "#/$defs/ElicitationSessionScope" } ] }, { "title": "Request", "description": "Tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).", "allOf": [ { "$ref": "#/$defs/ElicitationRequestScope" } ] } ], "required": ["requestedSchema"] }, "ElicitationId": { "description": "Unique identifier for an elicitation.", "type": "string" }, "ElicitationUrlMode": { "description": "URL-based elicitation mode where the client directs the user to a URL.", "type": "object", "properties": { "elicitationId": { "description": "The unique identifier for this elicitation.", "allOf": [ { "$ref": "#/$defs/ElicitationId" } ] }, "url": { "description": "The URL to direct the user to.", "type": "string", "format": "uri" } }, "anyOf": [ { "title": "Session", "description": "Tied to a session, optionally to a specific tool call within that session.", "allOf": [ { "$ref": "#/$defs/ElicitationSessionScope" } ] }, { "title": "Request", "description": "Tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).", "allOf": [ { "$ref": "#/$defs/ElicitationRequestScope" } ] } ], "required": ["elicitationId", "url"] }, "ExtRequest": { "description": "Allows for sending an arbitrary request that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)" }, "AgentResponse": { "description": "A JSON-RPC response object.", "anyOf": [ { "title": "Result", "description": "A successful JSON-RPC response.", "type": "object", "properties": { "id": { "description": "The id of the request this response answers.", "allOf": [ { "$ref": "#/$defs/RequestId" } ] }, "result": { "description": "Method-specific response data.", "anyOf": [ { "title": "InitializeResponse", "description": "Successful result returned for a `initialize` request.", "allOf": [ { "$ref": "#/$defs/InitializeResponse" } ] }, { "title": "AuthenticateResponse", "description": "Successful result returned for a `authenticate` request.", "allOf": [ { "$ref": "#/$defs/AuthenticateResponse" } ] }, { "title": "LogoutResponse", "description": "Successful result returned for a `logout` request.", "allOf": [ { "$ref": "#/$defs/LogoutResponse" } ] }, { "title": "NewSessionResponse", "description": "Successful result returned for a `session/new` request.", "allOf": [ { "$ref": "#/$defs/NewSessionResponse" } ] }, { "title": "LoadSessionResponse", "description": "Successful result returned for a `session/load` request.", "allOf": [ { "$ref": "#/$defs/LoadSessionResponse" } ] }, { "title": "ListSessionsResponse", "description": "Successful result returned for a `session/list` request.", "allOf": [ { "$ref": "#/$defs/ListSessionsResponse" } ] }, { "title": "DeleteSessionResponse", "description": "Successful result returned for a `session/delete` request.", "allOf": [ { "$ref": "#/$defs/DeleteSessionResponse" } ] }, { "title": "ResumeSessionResponse", "description": "Successful result returned for a `session/resume` request.", "allOf": [ { "$ref": "#/$defs/ResumeSessionResponse" } ] }, { "title": "CloseSessionResponse", "description": "Successful result returned for a `session/close` request.", "allOf": [ { "$ref": "#/$defs/CloseSessionResponse" } ] }, { "title": "SetSessionModeResponse", "description": "Successful result returned for a `session/set_mode` request.", "allOf": [ { "$ref": "#/$defs/SetSessionModeResponse" } ] }, { "title": "SetSessionConfigOptionResponse", "description": "Successful result returned for a `session/set_config_option` request.", "allOf": [ { "$ref": "#/$defs/SetSessionConfigOptionResponse" } ] }, { "title": "PromptResponse", "description": "Successful result returned for a `session/prompt` request.", "allOf": [ { "$ref": "#/$defs/PromptResponse" } ] }, { "title": "ExtMethodResponse", "description": "Successful result returned by an extension method outside the core ACP method set.", "allOf": [ { "$ref": "#/$defs/ExtResponse" } ] } ] } }, "required": ["id", "result"] }, { "title": "Error", "description": "A failed JSON-RPC response.", "type": "object", "properties": { "id": { "description": "The id of the request this response answers.", "allOf": [ { "$ref": "#/$defs/RequestId" } ] }, "error": { "description": "Method-specific error data.", "allOf": [ { "$ref": "#/$defs/Error" } ] } }, "required": ["id", "error"] } ], "x-docs-ignore": true }, "InitializeResponse": { "description": "Response to the `initialize` method.\n\nContains the negotiated protocol version and agent capabilities.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)", "type": "object", "properties": { "protocolVersion": { "description": "The protocol version the client specified if supported by the agent,\nor the latest protocol version supported by the agent.\n\nThe client should disconnect, if it doesn't support this version.", "allOf": [ { "$ref": "#/$defs/ProtocolVersion" } ] }, "agentCapabilities": { "description": "Capabilities supported by the agent.", "x-deserialize-default-on-error": true, "default": { "loadSession": false, "promptCapabilities": { "image": false, "audio": false, "embeddedContext": false }, "mcpCapabilities": { "http": false, "sse": false }, "sessionCapabilities": {}, "auth": {} }, "allOf": [ { "$ref": "#/$defs/AgentCapabilities" } ] }, "authMethods": { "description": "Authentication methods supported by the agent.", "type": "array", "items": { "$ref": "#/$defs/AuthMethod" }, "default": [], "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "agentInfo": { "description": "Information about the Agent name and version sent to the Client.\n\nNote: in future versions of the protocol, this will be required.", "anyOf": [ { "$ref": "#/$defs/Implementation" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["protocolVersion"], "x-side": "agent", "x-method": "initialize" }, "ProtocolVersion": { "description": "Protocol version identifier.\n\nThis version is only bumped for breaking changes.\nNon-breaking changes should be introduced via capabilities.", "type": "integer", "format": "uint16", "minimum": 0, "maximum": 65535 }, "AgentCapabilities": { "description": "Capabilities supported by the agent.\n\nAdvertised during initialization to inform the client about\navailable features and content types.\n\nSee protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/initialization#agent-capabilities)", "type": "object", "properties": { "loadSession": { "description": "Whether the agent supports `session/load`.", "type": "boolean", "default": false, "x-deserialize-default-on-error": true }, "promptCapabilities": { "description": "Prompt capabilities supported by the agent.", "x-deserialize-default-on-error": true, "default": { "image": false, "audio": false, "embeddedContext": false }, "allOf": [ { "$ref": "#/$defs/PromptCapabilities" } ] }, "mcpCapabilities": { "description": "MCP capabilities supported by the agent.", "x-deserialize-default-on-error": true, "default": { "http": false, "sse": false }, "allOf": [ { "$ref": "#/$defs/McpCapabilities" } ] }, "sessionCapabilities": { "description": "Session lifecycle and prompt capabilities advertised by the agent.", "x-deserialize-default-on-error": true, "default": {}, "allOf": [ { "$ref": "#/$defs/SessionCapabilities" } ] }, "auth": { "description": "Authentication-related capabilities supported by the agent.", "x-deserialize-default-on-error": true, "default": {}, "allOf": [ { "$ref": "#/$defs/AgentAuthCapabilities" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "PromptCapabilities": { "description": "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nBaseline agent functionality requires support for [`ContentBlock::Text`]\nand [`ContentBlock::ResourceLink`] in prompt requests.\n\nOther variants must be explicitly opted in to.\nCapabilities for different types of content in prompt requests.\n\nIndicates which content types beyond the baseline (text and resource links)\nthe agent can process.\n\nSee protocol docs: [Prompt Capabilities](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities)", "type": "object", "properties": { "image": { "description": "Agent supports [`ContentBlock::Image`].", "type": "boolean", "default": false, "x-deserialize-default-on-error": true }, "audio": { "description": "Agent supports [`ContentBlock::Audio`].", "type": "boolean", "default": false, "x-deserialize-default-on-error": true }, "embeddedContext": { "description": "Agent supports embedded context in `session/prompt` requests.\n\nWhen enabled, the Client is allowed to include [`ContentBlock::Resource`]\nin prompt requests for pieces of context that are referenced in the message.", "type": "boolean", "default": false, "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "McpCapabilities": { "description": "MCP capabilities supported by the agent", "type": "object", "properties": { "http": { "description": "Agent supports [`McpServer::Http`].", "type": "boolean", "default": false, "x-deserialize-default-on-error": true }, "sse": { "description": "Agent supports [`McpServer::Sse`].", "type": "boolean", "default": false, "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "SessionCapabilities": { "description": "Session capabilities supported by the agent.\n\nAs a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`.\n\nOptionally, they **MAY** support other session methods and notifications by specifying additional capabilities.\n\nNote: `session/load` is still handled by the top-level `load_session` capability. This will be unified in future versions of the protocol.\n\nSee protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/initialization#session-capabilities)", "type": "object", "properties": { "list": { "description": "Whether the agent supports `session/list`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports listing sessions.", "anyOf": [ { "$ref": "#/$defs/SessionListCapabilities" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "delete": { "description": "Whether the agent supports `session/delete`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports deleting sessions from `session/list`.", "anyOf": [ { "$ref": "#/$defs/SessionDeleteCapabilities" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "additionalDirectories": { "description": "Whether the agent supports `additionalDirectories` on supported session lifecycle requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports `additionalDirectories` on\nsupported session lifecycle requests.\n\nAgents that also support `session/list` may return\n`SessionInfo.additionalDirectories` to report the complete ordered\nadditional-root list associated with a listed session.", "anyOf": [ { "$ref": "#/$defs/SessionAdditionalDirectoriesCapabilities" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "resume": { "description": "Whether the agent supports `session/resume`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports resuming sessions.", "anyOf": [ { "$ref": "#/$defs/SessionResumeCapabilities" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "close": { "description": "Whether the agent supports `session/close`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports closing sessions.", "anyOf": [ { "$ref": "#/$defs/SessionCloseCapabilities" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "SessionListCapabilities": { "description": "Capabilities for the `session/list` method.\n\nSupplying `{}` means the agent supports listing sessions.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "SessionDeleteCapabilities": { "description": "Capabilities for the `session/delete` method.\n\nSupplying `{}` means the agent supports deleting sessions from `session/list`.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "SessionAdditionalDirectoriesCapabilities": { "description": "Capabilities for additional session directories support.\n\nSupplying `{}` means the agent supports the `additionalDirectories` field on\nsupported session lifecycle requests. Agents that also support\n`session/list` may return `SessionInfo.additionalDirectories` to report the\ncomplete ordered additional-root list associated with a listed session.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "SessionResumeCapabilities": { "description": "Capabilities for the `session/resume` method.\n\nSupplying `{}` means the agent supports resuming sessions.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "SessionCloseCapabilities": { "description": "Capabilities for the `session/close` method.\n\nSupplying `{}` means the agent supports closing sessions.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "AgentAuthCapabilities": { "description": "Authentication-related capabilities supported by the agent.", "type": "object", "properties": { "logout": { "description": "Whether the agent supports the logout method.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports the logout method.", "anyOf": [ { "$ref": "#/$defs/LogoutCapabilities" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "LogoutCapabilities": { "description": "Logout capabilities supported by the agent.\n\nSupplying `{}` means the agent supports the logout method.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "AuthMethod": { "description": "Describes an available authentication method.\n\nThe `type` field acts as the discriminator in the serialized JSON form.\nWhen no `type` is present, the method is treated as `agent`.", "anyOf": [ { "description": "Client runs the configured agent program as a separate interactive\nprocess, without passing this method to `authenticate`.", "type": "object", "properties": { "type": { "type": "string", "const": "terminal" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/AuthMethodTerminal" } ] }, { "title": "agent", "description": "Agent handles authentication itself through `authenticate`.\n\nThis is the default when no `type` is specified.", "allOf": [ { "$ref": "#/$defs/AuthMethodAgent" } ] } ] }, "AuthMethodId": { "description": "Typed identifier used for auth method values on the wire.", "type": "string" }, "AuthMethodTerminal": { "description": "Terminal-based authentication method.\n\nThe client runs the configured agent program as a separate interactive\nprocess for the user to authenticate via a TUI. Agents MUST advertise this\nmethod only when the client enabled its terminal authentication capability.\nA zero exit status signals success; any other termination signals failure.\nThe client MUST NOT pass this method to `authenticate`.", "type": "object", "properties": { "id": { "description": "Unique identifier for this authentication method.", "allOf": [ { "$ref": "#/$defs/AuthMethodId" } ] }, "name": { "description": "Human-readable name of the authentication method.", "type": "string" }, "description": { "description": "Optional description providing more details about this authentication method.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "args": { "description": "Additional arguments to append to the configured agent invocation for terminal auth.", "type": "array", "items": { "type": "string" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "env": { "description": "Additional environment variables to set on the configured agent invocation for terminal auth.\nThese values override same-named variables in the base launch configuration.", "type": "object", "x-deserialize-default-on-error": true, "additionalProperties": { "type": "string" } }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["id", "name"] }, "AuthMethodAgent": { "description": "Agent handles authentication itself through `authenticate`.\n\nThis is the default authentication method type.", "type": "object", "properties": { "id": { "description": "Unique identifier for this authentication method.", "allOf": [ { "$ref": "#/$defs/AuthMethodId" } ] }, "name": { "description": "Human-readable name of the authentication method.", "type": "string" }, "description": { "description": "Optional description providing more details about this authentication method.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["id", "name"] }, "Implementation": { "description": "Metadata about the implementation of the client or agent.\nDescribes the name and version of an ACP implementation, with an optional\ntitle for UI representation.", "type": "object", "properties": { "name": { "description": "Intended for programmatic or logical use, but can be used as a display\nname fallback if title isn’t present.", "type": "string" }, "title": { "description": "Intended for UI and end-user contexts — optimized to be human-readable\nand easily understood.\n\nIf not provided, the name should be used for display.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "version": { "description": "Version of the implementation. Can be displayed to the user or used\nfor debugging or metrics purposes. (e.g. \"1.0.0\").", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["name", "version"] }, "AuthenticateResponse": { "description": "Response to the `authenticate` method.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "agent", "x-method": "authenticate" }, "LogoutResponse": { "description": "Response to the `logout` method.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "agent", "x-method": "logout" }, "NewSessionResponse": { "description": "Response from creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)", "type": "object", "properties": { "sessionId": { "description": "Unique identifier for the created session.\n\nUsed in all subsequent requests for this conversation.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "modes": { "description": "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", "anyOf": [ { "$ref": "#/$defs/SessionModeState" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "configOptions": { "description": "Initial session configuration options if supported by the Agent.", "type": ["array", "null"], "items": { "$ref": "#/$defs/SessionConfigOption" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId"], "x-side": "agent", "x-method": "session/new" }, "SessionModeState": { "description": "The set of modes and the one currently active.", "type": "object", "properties": { "currentModeId": { "description": "The current mode the Agent is in.", "allOf": [ { "$ref": "#/$defs/SessionModeId" } ] }, "availableModes": { "description": "The set of modes that the Agent can operate in", "type": "array", "items": { "$ref": "#/$defs/SessionMode" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["currentModeId", "availableModes"] }, "SessionModeId": { "description": "Unique identifier for a Session Mode.", "type": "string" }, "SessionMode": { "description": "A mode the agent can operate in.\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", "type": "object", "properties": { "id": { "description": "Stable identifier used to refer to this protocol object in later messages.", "allOf": [ { "$ref": "#/$defs/SessionModeId" } ] }, "name": { "description": "Human-readable name shown for this protocol object.", "type": "string" }, "description": { "description": "Optional human-readable details shown with this protocol object.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["id", "name"] }, "SessionConfigOption": { "description": "A session configuration option selector and its current state.", "type": "object", "properties": { "id": { "description": "Unique identifier for the configuration option.", "allOf": [ { "$ref": "#/$defs/SessionConfigId" } ] }, "name": { "description": "Human-readable label for the option.", "type": "string" }, "description": { "description": "Optional description for the Client to display to the user.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "category": { "description": "Optional semantic category for this option (UX only).", "anyOf": [ { "$ref": "#/$defs/SessionConfigOptionCategory" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["id", "name"], "oneOf": [ { "description": "Single-value selector (dropdown).", "type": "object", "properties": { "type": { "type": "string", "const": "select" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/SessionConfigSelect" } ] }, { "description": "Boolean on/off toggle.", "type": "object", "properties": { "type": { "type": "string", "const": "boolean" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/SessionConfigBoolean" } ] } ], "discriminator": { "propertyName": "type" } }, "SessionConfigId": { "description": "Unique identifier for a session configuration option.", "type": "string" }, "SessionConfigOptionCategory": { "description": "Semantic category for a session configuration option.\n\nThis is intended to help Clients distinguish broadly common selectors (e.g. model selector vs\nsession mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons,\nplacement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown\ncategories gracefully.\n\nCategory names beginning with `_` are free for custom use, like other ACP extension methods.\nCategory names that do not begin with `_` are reserved for the ACP spec.", "anyOf": [ { "description": "Session mode selector.", "type": "string", "const": "mode" }, { "description": "Model selector.", "type": "string", "const": "model" }, { "description": "Model-related configuration parameter.", "type": "string", "const": "model_config" }, { "description": "Thought/reasoning level selector.", "type": "string", "const": "thought_level" }, { "title": "other", "description": "Unknown / uncategorized selector.", "type": "string" } ] }, "SessionConfigValueId": { "description": "Unique identifier for a session configuration option value.", "type": "string" }, "SessionConfigSelectOptions": { "description": "Possible values for a session configuration option.", "anyOf": [ { "title": "Ungrouped", "description": "A flat list of options with no grouping.", "type": "array", "items": { "$ref": "#/$defs/SessionConfigSelectOption" } }, { "title": "Grouped", "description": "A list of options grouped under headers.", "type": "array", "items": { "$ref": "#/$defs/SessionConfigSelectGroup" } } ] }, "SessionConfigSelectOption": { "description": "A possible value for a session configuration option.", "type": "object", "properties": { "value": { "description": "Unique identifier for this option value.", "allOf": [ { "$ref": "#/$defs/SessionConfigValueId" } ] }, "name": { "description": "Human-readable label for this option value.", "type": "string" }, "description": { "description": "Optional description for this option value.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["value", "name"] }, "SessionConfigSelectGroup": { "description": "A group of possible values for a session configuration option.", "type": "object", "properties": { "group": { "description": "Unique identifier for this group.", "allOf": [ { "$ref": "#/$defs/SessionConfigGroupId" } ] }, "name": { "description": "Human-readable label for this group.", "type": "string" }, "options": { "description": "The set of option values in this group.", "type": "array", "items": { "$ref": "#/$defs/SessionConfigSelectOption" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["group", "name", "options"] }, "SessionConfigGroupId": { "description": "Unique identifier for a session configuration option value group.", "type": "string" }, "SessionConfigSelect": { "description": "A single-value selector (dropdown) session configuration option payload.", "type": "object", "properties": { "currentValue": { "description": "The currently selected value.", "allOf": [ { "$ref": "#/$defs/SessionConfigValueId" } ] }, "options": { "description": "The set of selectable options.", "allOf": [ { "$ref": "#/$defs/SessionConfigSelectOptions" } ] } }, "required": ["currentValue", "options"] }, "SessionConfigBoolean": { "description": "A boolean on/off toggle session configuration option payload.", "type": "object", "properties": { "currentValue": { "description": "The current value of the boolean option.", "type": "boolean" } }, "required": ["currentValue"] }, "LoadSessionResponse": { "description": "Response from loading an existing session.", "type": "object", "properties": { "modes": { "description": "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", "anyOf": [ { "$ref": "#/$defs/SessionModeState" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "configOptions": { "description": "Initial session configuration options if supported by the Agent.", "type": ["array", "null"], "items": { "$ref": "#/$defs/SessionConfigOption" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "agent", "x-method": "session/load" }, "ListSessionsResponse": { "description": "Response from listing sessions.", "type": "object", "properties": { "sessions": { "description": "Array of session information objects", "type": "array", "items": { "$ref": "#/$defs/SessionInfo" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "nextCursor": { "description": "Opaque cursor token. If present, pass this in the next request's cursor parameter\nto fetch the next page. If absent, there are no more results.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessions"], "x-side": "agent", "x-method": "session/list" }, "SessionInfo": { "description": "Information about a session returned by session/list", "type": "object", "properties": { "sessionId": { "description": "Unique identifier for the session", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "cwd": { "description": "The working directory for this session. Must be an absolute path.", "type": "string" }, "additionalDirectories": { "description": "Additional workspace roots reported for this session. Each path must be absolute.\n\nWhen present, this is the complete ordered additional-root list reported\nby the Agent. Omitted and empty values are equivalent: the response\nreports no additional roots.", "type": "array", "items": { "type": "string" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "title": { "description": "Human-readable title for the session", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "updatedAt": { "description": "ISO 8601 timestamp of last activity", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "cwd"] }, "DeleteSessionResponse": { "description": "Response from deleting a session.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "agent", "x-method": "session/delete" }, "ResumeSessionResponse": { "description": "Response from resuming an existing session.", "type": "object", "properties": { "modes": { "description": "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", "anyOf": [ { "$ref": "#/$defs/SessionModeState" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "configOptions": { "description": "Initial session configuration options if supported by the Agent.", "type": ["array", "null"], "items": { "$ref": "#/$defs/SessionConfigOption" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "agent", "x-method": "session/resume" }, "CloseSessionResponse": { "description": "Response from closing a session.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "agent", "x-method": "session/close" }, "SetSessionModeResponse": { "description": "Response to `session/set_mode` method.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "agent", "x-method": "session/set_mode" }, "SetSessionConfigOptionResponse": { "description": "Response to `session/set_config_option` method.", "type": "object", "properties": { "configOptions": { "description": "The full set of configuration options and their current values.", "type": "array", "items": { "$ref": "#/$defs/SessionConfigOption" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["configOptions"], "x-side": "agent", "x-method": "session/set_config_option" }, "PromptResponse": { "description": "Response from processing a user prompt.\n\nSee protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion)", "type": "object", "properties": { "stopReason": { "description": "Indicates why the agent stopped processing the turn.", "allOf": [ { "$ref": "#/$defs/StopReason" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["stopReason"], "x-side": "agent", "x-method": "session/prompt" }, "StopReason": { "description": "Reasons why an agent stops processing a prompt turn.\n\nSee protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons)", "oneOf": [ { "description": "The turn ended successfully.", "type": "string", "const": "end_turn" }, { "description": "The turn ended because the agent reached the maximum number of tokens.", "type": "string", "const": "max_tokens" }, { "description": "The turn ended because the agent reached the maximum number of allowed\nagent requests between user turns.", "type": "string", "const": "max_turn_requests" }, { "description": "The turn ended because the agent refused to continue. The user prompt\nand everything that comes after it won't be included in the next\nprompt, so this should be reflected in the UI.", "type": "string", "const": "refusal" }, { "description": "The turn was cancelled by the client via `session/cancel`.\n\nThis stop reason MUST be returned when the client sends a `session/cancel`\nnotification, even if the cancellation causes exceptions in underlying operations.\nAgents should catch these exceptions and return this semantically meaningful\nresponse to confirm successful cancellation.", "type": "string", "const": "cancelled" } ] }, "ExtResponse": { "description": "Allows for sending an arbitrary response to an [`ExtRequest`] that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)" }, "Error": { "description": "JSON-RPC error object.\n\nRepresents an error that occurred during method execution, following the\nJSON-RPC 2.0 error object specification with optional additional data.\n\nSee protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object)", "type": "object", "properties": { "code": { "description": "A number indicating the error type that occurred.\nThis must be an integer as defined in the JSON-RPC specification.", "allOf": [ { "$ref": "#/$defs/ErrorCode" } ] }, "message": { "description": "A string providing a short description of the error.\nThe message should be limited to a concise single sentence.", "type": "string" }, "data": { "description": "Optional primitive or structured value that contains additional information about the error.\nThis may include debugging information or context-specific details.", "x-deserialize-default-on-error": true } }, "required": ["code", "message"] }, "ErrorCode": { "description": "Predefined error codes for common JSON-RPC and ACP-specific errors.\n\nThese codes follow the JSON-RPC 2.0 specification for standard errors\nand use the reserved range (-32000 to -32099) for protocol-specific errors.", "anyOf": [ { "title": "Parse error", "description": "**Parse error**: Invalid JSON was received by the server.\nAn error occurred on the server while parsing the JSON text.", "type": "integer", "format": "int32", "const": -32700 }, { "title": "Invalid request", "description": "**Invalid request**: The JSON sent is not a valid Request object.", "type": "integer", "format": "int32", "const": -32600 }, { "title": "Method not found", "description": "**Method not found**: The method does not exist or is not available.", "type": "integer", "format": "int32", "const": -32601 }, { "title": "Invalid params", "description": "**Invalid params**: Invalid method parameter(s).", "type": "integer", "format": "int32", "const": -32602 }, { "title": "Internal error", "description": "**Internal error**: Internal JSON-RPC error.\nReserved for implementation-defined server errors.", "type": "integer", "format": "int32", "const": -32603 }, { "title": "Request cancelled", "description": "**Request cancelled**: Execution of the method was aborted either due to a cancellation request from the caller or\nbecause of resource constraints or shutdown.", "type": "integer", "format": "int32", "const": -32800 }, { "title": "Authentication required", "description": "**Authentication required**: Authentication is required before this operation can be performed.", "type": "integer", "format": "int32", "const": -32000 }, { "title": "Resource not found", "description": "**Resource not found**: A given resource, such as a file, was not found.", "type": "integer", "format": "int32", "const": -32002 }, { "title": "Other", "description": "Other undefined error code.", "type": "integer", "format": "int32" } ] }, "AgentNotification": { "description": "A JSON-RPC notification object.", "type": "object", "properties": { "method": { "description": "The notification method name.", "type": "string" }, "params": { "description": "Method-specific notification parameters.", "anyOf": [ { "description": "All possible notifications that an agent can send to a client.\n\nThis enum is used internally for routing RPC notifications. You typically won't need\nto use this directly.\n\nNotifications do not expect a response.", "anyOf": [ { "title": "SessionNotification", "description": "Handles session update notifications from the agent.\n\nThis is a notification endpoint (no response expected) that receives\nreal-time updates about session progress, including message chunks,\ntool calls, and execution plans.\n\nNote: Clients SHOULD continue accepting tool call updates even after\nsending a `session/cancel` notification, as the agent may send final\nupdates before responding with the cancelled stop reason.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)", "allOf": [ { "$ref": "#/$defs/SessionNotification" } ] }, { "title": "CompleteElicitationNotification", "description": "Notification that a URL-based elicitation has completed.\n\nSee protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/elicitation#url-completion)", "allOf": [ { "$ref": "#/$defs/CompleteElicitationNotification" } ] }, { "title": "ExtNotification", "description": "Handles extension notifications from the agent.\n\nAllows the Agent to send an arbitrary notification that is not part of the ACP spec.\nExtension notifications provide a way to send one-way messages for custom functionality\nwhile maintaining protocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "allOf": [ { "$ref": "#/$defs/ExtNotification" } ] } ] }, { "type": "null" } ] } }, "required": ["method"], "x-docs-ignore": true }, "SessionNotification": { "description": "Notification containing a session update from the agent.\n\nUsed to stream real-time progress and results during prompt processing.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)", "type": "object", "properties": { "sessionId": { "description": "The ID of the session this update pertains to.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "update": { "description": "The actual update content.", "allOf": [ { "$ref": "#/$defs/SessionUpdate" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "update"], "x-side": "client", "x-method": "session/update" }, "SessionUpdate": { "description": "Different types of updates that can be sent during session processing.\n\nThese updates provide real-time feedback about the agent's progress.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)", "oneOf": [ { "description": "A chunk of the user's message being streamed.", "type": "object", "properties": { "sessionUpdate": { "type": "string", "const": "user_message_chunk" } }, "required": ["sessionUpdate"], "allOf": [ { "$ref": "#/$defs/ContentChunk" } ] }, { "description": "A chunk of the agent's response being streamed.", "type": "object", "properties": { "sessionUpdate": { "type": "string", "const": "agent_message_chunk" } }, "required": ["sessionUpdate"], "allOf": [ { "$ref": "#/$defs/ContentChunk" } ] }, { "description": "A chunk of the agent's internal reasoning being streamed.", "type": "object", "properties": { "sessionUpdate": { "type": "string", "const": "agent_thought_chunk" } }, "required": ["sessionUpdate"], "allOf": [ { "$ref": "#/$defs/ContentChunk" } ] }, { "description": "Notification that a new tool call has been initiated.", "type": "object", "properties": { "sessionUpdate": { "type": "string", "const": "tool_call" } }, "required": ["sessionUpdate"], "allOf": [ { "$ref": "#/$defs/ToolCall" } ] }, { "description": "Update on the status or results of a tool call.", "type": "object", "properties": { "sessionUpdate": { "type": "string", "const": "tool_call_update" } }, "required": ["sessionUpdate"], "allOf": [ { "$ref": "#/$defs/ToolCallUpdate" } ] }, { "description": "The agent's execution plan for complex tasks.\nSee protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)", "type": "object", "properties": { "sessionUpdate": { "type": "string", "const": "plan" } }, "required": ["sessionUpdate"], "allOf": [ { "$ref": "#/$defs/Plan" } ] }, { "description": "Available commands are ready or have changed", "type": "object", "properties": { "sessionUpdate": { "type": "string", "const": "available_commands_update" } }, "required": ["sessionUpdate"], "allOf": [ { "$ref": "#/$defs/AvailableCommandsUpdate" } ] }, { "description": "The current mode of the session has changed\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", "type": "object", "properties": { "sessionUpdate": { "type": "string", "const": "current_mode_update" } }, "required": ["sessionUpdate"], "allOf": [ { "$ref": "#/$defs/CurrentModeUpdate" } ] }, { "description": "Session configuration options have been updated.", "type": "object", "properties": { "sessionUpdate": { "type": "string", "const": "config_option_update" } }, "required": ["sessionUpdate"], "allOf": [ { "$ref": "#/$defs/ConfigOptionUpdate" } ] }, { "description": "Session metadata has been updated (title, timestamps, custom metadata)", "type": "object", "properties": { "sessionUpdate": { "type": "string", "const": "session_info_update" } }, "required": ["sessionUpdate"], "allOf": [ { "$ref": "#/$defs/SessionInfoUpdate" } ] }, { "description": "Context window and cost update for the session.", "type": "object", "properties": { "sessionUpdate": { "type": "string", "const": "usage_update" } }, "required": ["sessionUpdate"], "allOf": [ { "$ref": "#/$defs/UsageUpdate" } ] } ], "discriminator": { "propertyName": "sessionUpdate" } }, "MessageId": { "description": "Unique identifier for a message within a session.", "type": "string" }, "ContentChunk": { "description": "A streamed item of content", "type": "object", "properties": { "content": { "description": "A single item of content", "allOf": [ { "$ref": "#/$defs/ContentBlock" } ] }, "messageId": { "description": "A unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.", "anyOf": [ { "$ref": "#/$defs/MessageId" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["content"] }, "ToolCall": { "description": "Represents a tool call that the language model has requested.\n\nTool calls are actions that the agent executes on behalf of the language model,\nsuch as reading files, executing code, or fetching data from external sources.\n\nSee protocol docs: [Tool Calls](https://agentclientprotocol.com/protocol/tool-calls)", "type": "object", "properties": { "toolCallId": { "description": "Unique identifier for this tool call within the session.", "allOf": [ { "$ref": "#/$defs/ToolCallId" } ] }, "title": { "description": "Human-readable title describing what the tool is doing.", "type": "string" }, "kind": { "description": "The category of tool being invoked.\nHelps clients choose appropriate icons and UI treatment.", "x-deserialize-default-on-error": true, "allOf": [ { "$ref": "#/$defs/ToolKind" } ] }, "status": { "description": "Current execution status of the tool call.", "x-deserialize-default-on-error": true, "allOf": [ { "$ref": "#/$defs/ToolCallStatus" } ] }, "content": { "description": "Content produced by the tool call.", "type": "array", "items": { "$ref": "#/$defs/ToolCallContent" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "locations": { "description": "File locations affected by this tool call.\nEnables \"follow-along\" features in clients.", "type": "array", "items": { "$ref": "#/$defs/ToolCallLocation" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "rawInput": { "description": "Raw input parameters sent to the tool.", "x-deserialize-default-on-error": true }, "rawOutput": { "description": "Raw output returned by the tool.", "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["toolCallId", "title"] }, "PlanEntry": { "description": "A single entry in the execution plan.\n\nRepresents a task or goal that the assistant intends to accomplish\nas part of fulfilling the user's request.\nSee protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries)", "type": "object", "properties": { "content": { "description": "Human-readable description of what this task aims to accomplish.", "type": "string" }, "priority": { "description": "The relative importance of this task.\nUsed to indicate which tasks are most critical to the overall goal.", "allOf": [ { "$ref": "#/$defs/PlanEntryPriority" } ] }, "status": { "description": "Current execution status of this task.", "allOf": [ { "$ref": "#/$defs/PlanEntryStatus" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["content", "priority", "status"] }, "PlanEntryPriority": { "description": "Priority levels for plan entries.\n\nUsed to indicate the relative importance or urgency of different\ntasks in the execution plan.\nSee protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries)", "oneOf": [ { "description": "High priority task - critical to the overall goal.", "type": "string", "const": "high" }, { "description": "Medium priority task - important but not critical.", "type": "string", "const": "medium" }, { "description": "Low priority task - nice to have but not essential.", "type": "string", "const": "low" } ] }, "PlanEntryStatus": { "description": "Status of a plan entry in the execution flow.\n\nTracks the lifecycle of each task from planning through completion.\nSee protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries)", "oneOf": [ { "description": "The task has not started yet.", "type": "string", "const": "pending" }, { "description": "The task is currently being worked on.", "type": "string", "const": "in_progress" }, { "description": "The task has been successfully completed.", "type": "string", "const": "completed" } ] }, "Plan": { "description": "An execution plan for accomplishing complex tasks.\n\nPlans consist of multiple entries representing individual tasks or goals.\nAgents report plans to clients to provide visibility into their execution strategy.\nPlans can evolve during execution as the agent discovers new requirements or completes tasks.\n\nSee protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)", "type": "object", "properties": { "entries": { "description": "The list of tasks to be accomplished.\n\nWhen updating a plan, the agent must send a complete list of all entries\nwith their current status. The client replaces the entire plan with each update.", "type": "array", "items": { "$ref": "#/$defs/PlanEntry" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["entries"] }, "AvailableCommand": { "description": "Information about a command.", "type": "object", "properties": { "name": { "description": "Command name (e.g., `create_plan`, `research_codebase`).", "type": "string" }, "description": { "description": "Human-readable description of what the command does.", "type": "string" }, "input": { "description": "Input for the command if required", "anyOf": [ { "$ref": "#/$defs/AvailableCommandInput" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["name", "description"] }, "AvailableCommandInput": { "description": "The input specification for a command.", "anyOf": [ { "title": "unstructured", "description": "All text that was typed after the command name is provided as input.", "allOf": [ { "$ref": "#/$defs/UnstructuredCommandInput" } ] } ] }, "UnstructuredCommandInput": { "description": "All text that was typed after the command name is provided as input.", "type": "object", "properties": { "hint": { "description": "A hint to display when the input hasn't been provided yet", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["hint"] }, "AvailableCommandsUpdate": { "description": "Available commands are ready or have changed", "type": "object", "properties": { "availableCommands": { "description": "Commands the agent can execute", "type": "array", "items": { "$ref": "#/$defs/AvailableCommand" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["availableCommands"] }, "CurrentModeUpdate": { "description": "The current mode of the session has changed\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", "type": "object", "properties": { "currentModeId": { "description": "The ID of the current mode", "allOf": [ { "$ref": "#/$defs/SessionModeId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["currentModeId"] }, "ConfigOptionUpdate": { "description": "Session configuration options have been updated.", "type": "object", "properties": { "configOptions": { "description": "The full set of configuration options and their current values.", "type": "array", "items": { "$ref": "#/$defs/SessionConfigOption" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["configOptions"] }, "SessionInfoUpdate": { "description": "Update to session metadata. All fields are optional to support partial updates.\n\nAgents send this notification to update session information like title or custom metadata.\nThis allows clients to display dynamic session names and track session state changes.", "type": "object", "properties": { "title": { "description": "Human-readable title for the session. Set to null to clear.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "updatedAt": { "description": "ISO 8601 timestamp of last activity. Set to null to clear.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "Cost": { "description": "Cost information for a session.", "type": "object", "properties": { "amount": { "description": "Total cumulative cost for session.", "type": "number", "format": "double" }, "currency": { "description": "ISO 4217 currency code (e.g., \"USD\", \"EUR\").", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["amount", "currency"] }, "UsageUpdate": { "description": "Context window and cost update for a session.", "type": "object", "properties": { "used": { "description": "Tokens currently in context.", "type": "integer", "format": "uint64", "minimum": 0 }, "size": { "description": "Total context window size in tokens.", "type": "integer", "format": "uint64", "minimum": 0 }, "cost": { "description": "Cumulative session cost (optional).", "anyOf": [ { "$ref": "#/$defs/Cost" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["used", "size"] }, "CompleteElicitationNotification": { "description": "Notification sent by the agent when a URL-based elicitation is complete.", "type": "object", "properties": { "elicitationId": { "description": "The ID of the elicitation that completed.", "allOf": [ { "$ref": "#/$defs/ElicitationId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["elicitationId"], "x-side": "client", "x-method": "elicitation/complete" }, "ExtNotification": { "description": "Allows the Agent to send an arbitrary notification that is not part of the ACP spec.\nExtension notifications provide a way to send one-way messages for custom functionality\nwhile maintaining protocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)" }, "ClientRequest": { "description": "A JSON-RPC request object.", "type": "object", "properties": { "id": { "description": "The request id used to correlate the matching response.", "allOf": [ { "$ref": "#/$defs/RequestId" } ] }, "method": { "description": "The method name to invoke.", "type": "string" }, "params": { "description": "Method-specific request parameters.", "anyOf": [ { "description": "All possible requests that a client can send to an agent.\n\nThis enum is used internally for routing RPC requests. You typically won't need\nto use this directly.\n\nThis enum encompasses all method calls from client to agent.", "anyOf": [ { "title": "InitializeRequest", "description": "Establishes the connection with a client and negotiates protocol capabilities.\n\nThis method is called once at the beginning of the connection to:\n- Negotiate the protocol version to use\n- Exchange capability information between client and agent\n- Determine available authentication methods\n\nThe agent should respond with its supported protocol version and capabilities.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)", "allOf": [ { "$ref": "#/$defs/InitializeRequest" } ] }, { "title": "AuthenticateRequest", "description": "Authenticates the client using the specified authentication method.\n\nCalled when the agent requires authentication before allowing session creation.\nThe client provides an authentication method ID that was advertised during\ninitialization and whose type defines the `authenticate` flow.\n\nAfter successful authentication, the client can proceed to create sessions with\n`new_session` without receiving an `auth_required` error.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)", "allOf": [ { "$ref": "#/$defs/AuthenticateRequest" } ] }, { "title": "LogoutRequest", "description": "Logs out of the current authenticated state.\n\nAfter a successful logout, all new sessions will require authentication.\nThere is no guarantee about the behavior of already running sessions.", "allOf": [ { "$ref": "#/$defs/LogoutRequest" } ] }, { "title": "NewSessionRequest", "description": "Creates a new conversation session with the agent.\n\nSessions represent independent conversation contexts with their own history and state.\n\nThe agent should:\n- Create a new session context\n- Connect to any specified MCP servers\n- Return a unique session ID for future requests\n\nMay return an `auth_required` error if the agent requires authentication.\n\nSee protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/session-setup)", "allOf": [ { "$ref": "#/$defs/NewSessionRequest" } ] }, { "title": "LoadSessionRequest", "description": "Loads an existing session to resume a previous conversation.\n\nThis method is only available if the agent advertises the `loadSession` capability.\n\nThe agent should:\n- Restore the session context and conversation history\n- Connect to the specified MCP servers\n- Stream the entire conversation history back to the client via notifications\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)", "allOf": [ { "$ref": "#/$defs/LoadSessionRequest" } ] }, { "title": "ListSessionsRequest", "description": "Lists existing sessions known to the agent.\n\nThis method is only available if the agent advertises the `sessionCapabilities.list` capability.\n\nThe agent should return metadata about sessions with optional filtering and pagination support.", "allOf": [ { "$ref": "#/$defs/ListSessionsRequest" } ] }, { "title": "DeleteSessionRequest", "description": "Deletes an existing session from `session/list`.\n\nThis method is only available if the agent advertises the `sessionCapabilities.delete` capability.", "allOf": [ { "$ref": "#/$defs/DeleteSessionRequest" } ] }, { "title": "ResumeSessionRequest", "description": "Resumes an existing session without returning previous messages.\n\nThis method is only available if the agent advertises the `sessionCapabilities.resume` capability.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).", "allOf": [ { "$ref": "#/$defs/ResumeSessionRequest" } ] }, { "title": "CloseSessionRequest", "description": "Closes an active session and frees up any resources associated with it.\n\nThis method is only available if the agent advertises the `sessionCapabilities.close` capability.\n\nThe agent must cancel any ongoing work (as if `session/cancel` was called)\nand then free up any resources associated with the session.", "allOf": [ { "$ref": "#/$defs/CloseSessionRequest" } ] }, { "title": "SetSessionModeRequest", "description": "Sets the current mode for a session.\n\nAllows switching between different agent modes (e.g., \"ask\", \"architect\", \"code\")\nthat affect system prompts, tool availability, and permission behaviors.\n\nThe mode must be one of the modes advertised in `availableModes` during session\ncreation or loading. Agents may also change modes autonomously and notify the\nclient via `current_mode_update` notifications.\n\nThis method can be called at any time during a session, whether the Agent is\nidle or actively generating a response.\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", "allOf": [ { "$ref": "#/$defs/SetSessionModeRequest" } ] }, { "title": "SetSessionConfigOptionRequest", "description": "Sets the current value for a session configuration option.", "allOf": [ { "$ref": "#/$defs/SetSessionConfigOptionRequest" } ] }, { "title": "PromptRequest", "description": "Processes a user prompt within a session.\n\nThis method handles the whole lifecycle of a prompt:\n- Receives user messages with optional context (files, images, etc.)\n- Processes the prompt using language models\n- Reports language model content and tool calls to the Clients\n- Requests permission to run tools\n- Executes any requested tool calls\n- Returns when the turn is complete with a stop reason\n\nSee protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/prompt-turn)", "allOf": [ { "$ref": "#/$defs/PromptRequest" } ] }, { "title": "ExtMethodRequest", "description": "Handles extension method requests from the client.\n\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "allOf": [ { "$ref": "#/$defs/ExtRequest" } ] } ] }, { "type": "null" } ] } }, "required": ["id", "method"], "x-docs-ignore": true }, "InitializeRequest": { "description": "Request parameters for the initialize method.\n\nSent by the client to establish connection and negotiate capabilities.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)", "type": "object", "properties": { "protocolVersion": { "description": "The latest protocol version supported by the client.", "allOf": [ { "$ref": "#/$defs/ProtocolVersion" } ] }, "clientCapabilities": { "description": "Capabilities supported by the client.", "x-deserialize-default-on-error": true, "default": { "fs": { "readTextFile": false, "writeTextFile": false }, "terminal": false, "auth": { "terminal": false } }, "allOf": [ { "$ref": "#/$defs/ClientCapabilities" } ] }, "clientInfo": { "description": "Information about the Client name and version sent to the Agent.\n\nNote: in future versions of the protocol, this will be required.", "anyOf": [ { "$ref": "#/$defs/Implementation" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["protocolVersion"], "x-side": "agent", "x-method": "initialize" }, "ClientCapabilities": { "description": "Capabilities supported by the client.\n\nAdvertised during initialization to inform the agent about\navailable features and methods.\n\nSee protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities)", "type": "object", "properties": { "fs": { "description": "File system capabilities supported by the client.\nDetermines which file operations the agent can request.", "x-deserialize-default-on-error": true, "default": { "readTextFile": false, "writeTextFile": false }, "allOf": [ { "$ref": "#/$defs/FileSystemCapabilities" } ] }, "terminal": { "description": "Whether the Client support all `terminal/*` methods.", "type": "boolean", "default": false, "x-deserialize-default-on-error": true }, "session": { "description": "Session-related capabilities supported by the client.\n\nOptional. Omitted or `null` both mean the client does not advertise any\nsession-related extensions.", "anyOf": [ { "$ref": "#/$defs/ClientSessionCapabilities" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "auth": { "description": "Authentication capabilities supported by the client.\nDetermines which authentication method types the agent may include\nin its `InitializeResponse`.", "x-deserialize-default-on-error": true, "default": { "terminal": false }, "allOf": [ { "$ref": "#/$defs/AuthCapabilities" } ] }, "elicitation": { "description": "Elicitation capabilities supported by the client.\nDetermines which elicitation modes the agent may use.\n\nOptional. Omitted or `null` both mean the client does not advertise\nelicitation support.", "anyOf": [ { "$ref": "#/$defs/ElicitationCapabilities" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "FileSystemCapabilities": { "description": "File system capabilities that a client may support.\n\nSee protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem)", "type": "object", "properties": { "readTextFile": { "description": "Whether the Client supports `fs/read_text_file` requests.", "type": "boolean", "default": false, "x-deserialize-default-on-error": true }, "writeTextFile": { "description": "Whether the Client supports `fs/write_text_file` requests.", "type": "boolean", "default": false, "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "ClientSessionCapabilities": { "description": "Session-related capabilities supported by the client.", "type": "object", "properties": { "configOptions": { "description": "Config option capabilities supported by the client.\n\nOmitted or `null` both mean the client does not advertise support for any\nconfig option extensions.", "anyOf": [ { "$ref": "#/$defs/SessionConfigOptionsCapabilities" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "SessionConfigOptionsCapabilities": { "description": "Session configuration option capabilities supported by the client.", "type": "object", "properties": { "boolean": { "description": "Whether the client supports boolean session configuration options.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means agents may include `type: \"boolean\"` entries in\n`configOptions`, and the client may send `session/set_config_option`\nrequests with `type: \"boolean\"` and a boolean `value`.", "anyOf": [ { "$ref": "#/$defs/BooleanConfigOptionCapabilities" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "BooleanConfigOptionCapabilities": { "description": "Capabilities for boolean session configuration options.\n\nSupplying `{}` means the client supports boolean session configuration options.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "AuthCapabilities": { "description": "Authentication capabilities supported by the client.\n\nAdvertised during initialization to inform the agent which authentication\nmethod types the client can handle. This governs opt-in types that require\nadditional client-side support.", "type": "object", "properties": { "terminal": { "description": "Whether the client supports `terminal` authentication methods.\n\nThe client should set this to `true` only when it can reproduce the\nconfigured agent invocation in an interactive terminal. When `true`, the\nagent may include `terminal` entries in its authentication methods.", "type": "boolean", "default": false, "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "ElicitationCapabilities": { "description": "Elicitation capabilities supported by the client.", "type": "object", "properties": { "form": { "description": "Whether the client supports form-based elicitation.\n\nOptional. Omitted and `null` are equivalent and mean form support is not advertised.\nSupplying `{}` explicitly advertises form support.", "anyOf": [ { "$ref": "#/$defs/ElicitationFormCapabilities" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "url": { "description": "Whether the client supports URL-based elicitation.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client supports URL-based elicitation.", "anyOf": [ { "$ref": "#/$defs/ElicitationUrlCapabilities" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "ElicitationFormCapabilities": { "description": "Form-based elicitation capabilities.\n\nSupplying `{}` means the client supports form-based elicitation.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "ElicitationUrlCapabilities": { "description": "URL-based elicitation capabilities.\n\nSupplying `{}` means the client supports URL-based elicitation.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "AuthenticateRequest": { "description": "Request parameters for the authenticate method.\n\nSpecifies which authentication method to use.", "type": "object", "properties": { "methodId": { "description": "The ID of the authentication method to use.\nMust be one of the methods advertised in the initialize response.", "allOf": [ { "$ref": "#/$defs/AuthMethodId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["methodId"], "x-side": "agent", "x-method": "authenticate" }, "LogoutRequest": { "description": "Request parameters for the logout method.\n\nTerminates the current authenticated session.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "agent", "x-method": "logout" }, "NewSessionRequest": { "description": "Request parameters for creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)", "type": "object", "properties": { "cwd": { "description": "The working directory for this session. Must be an absolute path.", "type": "string" }, "additionalDirectories": { "description": "Additional workspace roots for this session. Each path must be absolute.\n\nThese expand the session's filesystem scope without changing `cwd`, which\nremains the base for relative paths. When omitted or empty, no\nadditional roots are activated for the new session.", "type": "array", "items": { "type": "string" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "mcpServers": { "description": "List of MCP (Model Context Protocol) servers the agent should connect to.", "type": "array", "items": { "$ref": "#/$defs/McpServer" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["cwd", "mcpServers"], "x-side": "agent", "x-method": "session/new" }, "McpServer": { "description": "Configuration for connecting to an MCP (Model Context Protocol) server.\n\nMCP servers provide tools and context that the agent can use when\nprocessing prompts.\n\nSee protocol docs: [MCP Servers](https://agentclientprotocol.com/protocol/session-setup#mcp-servers)", "anyOf": [ { "description": "HTTP transport configuration\n\nOnly available when the Agent capabilities indicate `mcp_capabilities.http` is `true`.", "type": "object", "properties": { "type": { "type": "string", "const": "http" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/McpServerHttp" } ] }, { "description": "SSE transport configuration\n\nOnly available when the Agent capabilities indicate `mcp_capabilities.sse` is `true`.", "type": "object", "properties": { "type": { "type": "string", "const": "sse" } }, "required": ["type"], "allOf": [ { "$ref": "#/$defs/McpServerSse" } ] }, { "title": "stdio", "description": "Stdio transport configuration\n\nAll Agents MUST support this transport.", "allOf": [ { "$ref": "#/$defs/McpServerStdio" } ] } ] }, "HttpHeader": { "description": "An HTTP header to set when making requests to the MCP server.", "type": "object", "properties": { "name": { "description": "The name of the HTTP header.", "type": "string" }, "value": { "description": "The value to set for the HTTP header.", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["name", "value"] }, "McpServerHttp": { "description": "HTTP transport configuration for MCP.", "type": "object", "properties": { "name": { "description": "Human-readable name identifying this MCP server.", "type": "string" }, "url": { "description": "URL to the MCP server.", "type": "string" }, "headers": { "description": "HTTP headers to set when making requests to the MCP server.", "type": "array", "items": { "$ref": "#/$defs/HttpHeader" } }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["name", "url", "headers"] }, "McpServerSse": { "description": "SSE transport configuration for MCP.", "type": "object", "properties": { "name": { "description": "Human-readable name identifying this MCP server.", "type": "string" }, "url": { "description": "URL to the MCP server.", "type": "string" }, "headers": { "description": "HTTP headers to set when making requests to the MCP server.", "type": "array", "items": { "$ref": "#/$defs/HttpHeader" } }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["name", "url", "headers"] }, "McpServerStdio": { "description": "Stdio transport configuration for MCP.", "type": "object", "properties": { "name": { "description": "Human-readable name identifying this MCP server.", "type": "string" }, "command": { "description": "Absolute path to the MCP server executable.", "type": "string" }, "args": { "description": "Command-line arguments to pass to the MCP server.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Environment variables to set when launching the MCP server.", "type": "array", "items": { "$ref": "#/$defs/EnvVariable" } }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["name", "command", "args", "env"] }, "LoadSessionRequest": { "description": "Request parameters for loading an existing session.\n\nOnly available if the Agent supports the `loadSession` capability.\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)", "type": "object", "properties": { "mcpServers": { "description": "List of MCP servers to connect to for this session.", "type": "array", "items": { "$ref": "#/$defs/McpServer" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "cwd": { "description": "The working directory for this session. Must be an absolute path.", "type": "string" }, "additionalDirectories": { "description": "Additional workspace roots to activate for this session. Each path must be absolute.\n\nWhen omitted or empty, no additional roots are activated. When non-empty,\nthis is the complete resulting additional-root list for the loaded\nsession. It may differ from any previously used or reported list as long as\nthe request `cwd` matches the session's `cwd`.", "type": "array", "items": { "type": "string" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "sessionId": { "description": "The ID of the session to load.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["mcpServers", "cwd", "sessionId"], "x-side": "agent", "x-method": "session/load" }, "ListSessionsRequest": { "description": "Request parameters for listing existing sessions.\n\nOnly available if the Agent supports the `sessionCapabilities.list` capability.", "type": "object", "properties": { "cwd": { "description": "Filter sessions by working directory. Must be an absolute path.", "type": ["string", "null"] }, "cursor": { "description": "Opaque cursor token from a previous response's nextCursor field for cursor-based pagination", "type": ["string", "null"] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "agent", "x-method": "session/list" }, "DeleteSessionRequest": { "description": "Request parameters for deleting an existing session from `session/list`.\n\nOnly available if the Agent supports the `sessionCapabilities.delete` capability.", "type": "object", "properties": { "sessionId": { "description": "The ID of the session to delete.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId"], "x-side": "agent", "x-method": "session/delete" }, "ResumeSessionRequest": { "description": "Request parameters for resuming an existing session.\n\nResumes an existing session without returning previous messages (unlike `session/load`).\nThis is useful for agents that can resume sessions but don't implement full session loading.\n\nOnly available if the Agent supports the `sessionCapabilities.resume` capability.", "type": "object", "properties": { "sessionId": { "description": "The ID of the session to resume.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "cwd": { "description": "The working directory for this session. Must be an absolute path.", "type": "string" }, "additionalDirectories": { "description": "Additional workspace roots to activate for this session. Each path must be absolute.\n\nWhen omitted or empty, no additional roots are activated. When non-empty,\nthis is the complete resulting additional-root list for the resumed\nsession. It may differ from any previously used or reported list as long as\nthe request `cwd` matches the session's `cwd`.", "type": "array", "items": { "type": "string" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "mcpServers": { "description": "List of MCP servers to connect to for this session.", "type": "array", "items": { "$ref": "#/$defs/McpServer" }, "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "cwd"], "x-side": "agent", "x-method": "session/resume" }, "CloseSessionRequest": { "description": "Request parameters for closing an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `sessionCapabilities.close` capability.", "type": "object", "properties": { "sessionId": { "description": "The ID of the session to close.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId"], "x-side": "agent", "x-method": "session/close" }, "SetSessionModeRequest": { "description": "Request parameters for setting a session mode.", "type": "object", "properties": { "sessionId": { "description": "The ID of the session to set the mode for.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "modeId": { "description": "The ID of the mode to set.", "allOf": [ { "$ref": "#/$defs/SessionModeId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "modeId"], "x-side": "agent", "x-method": "session/set_mode" }, "SetSessionConfigOptionRequest": { "description": "Request parameters for setting a session configuration option.", "type": "object", "properties": { "sessionId": { "description": "The ID of the session to set the configuration option for.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "configId": { "description": "The ID of the configuration option to set.", "allOf": [ { "$ref": "#/$defs/SessionConfigId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "configId"], "anyOf": [ { "description": "A boolean value (`type: \"boolean\"`).", "type": "object", "properties": { "value": { "description": "The boolean value.", "type": "boolean" }, "type": { "type": "string", "const": "boolean" } }, "required": ["type", "value"] }, { "title": "value_id", "description": "A [`SessionConfigValueId`] string value.\n\nThis is the default when `type` is absent on the wire. Unknown `type`\nvalues with string payloads also gracefully deserialize into this\nvariant.", "type": "object", "properties": { "value": { "description": "The value ID.", "allOf": [ { "$ref": "#/$defs/SessionConfigValueId" } ] } }, "required": ["value"] } ], "x-side": "agent", "x-method": "session/set_config_option" }, "PromptRequest": { "description": "Request parameters for sending a user prompt to the agent.\n\nContains the user's message and any additional context.\n\nSee protocol docs: [User Message](https://agentclientprotocol.com/protocol/prompt-turn#1-user-message)", "type": "object", "properties": { "sessionId": { "description": "The ID of the session to send this user message to", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "prompt": { "description": "The blocks of content that compose the user's message.\n\nAs a baseline, the Agent MUST support [`ContentBlock::Text`] and [`ContentBlock::ResourceLink`],\nwhile other variants are optionally enabled via [`PromptCapabilities`].\n\nThe Client MUST adapt its interface according to [`PromptCapabilities`].\n\nThe client MAY include referenced pieces of context as either\n[`ContentBlock::Resource`] or [`ContentBlock::ResourceLink`].\n\nWhen available, [`ContentBlock::Resource`] is preferred\nas it avoids extra round-trips and allows the message to include\npieces of context from sources the agent may not have access to.", "type": "array", "items": { "$ref": "#/$defs/ContentBlock" } }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId", "prompt"], "x-side": "agent", "x-method": "session/prompt" }, "ClientResponse": { "description": "A JSON-RPC response object.", "anyOf": [ { "title": "Result", "description": "A successful JSON-RPC response.", "type": "object", "properties": { "id": { "description": "The id of the request this response answers.", "allOf": [ { "$ref": "#/$defs/RequestId" } ] }, "result": { "description": "Method-specific response data.", "anyOf": [ { "title": "WriteTextFileResponse", "description": "Successful result returned for a `fs/write_text_file` request.", "allOf": [ { "$ref": "#/$defs/WriteTextFileResponse" } ] }, { "title": "ReadTextFileResponse", "description": "Successful result returned for a `fs/read_text_file` request.", "allOf": [ { "$ref": "#/$defs/ReadTextFileResponse" } ] }, { "title": "RequestPermissionResponse", "description": "Successful result returned for a `session/request_permission` request.", "allOf": [ { "$ref": "#/$defs/RequestPermissionResponse" } ] }, { "title": "CreateTerminalResponse", "description": "Successful result returned for a `terminal/create` request.", "allOf": [ { "$ref": "#/$defs/CreateTerminalResponse" } ] }, { "title": "TerminalOutputResponse", "description": "Successful result returned for a `terminal/output` request.", "allOf": [ { "$ref": "#/$defs/TerminalOutputResponse" } ] }, { "title": "ReleaseTerminalResponse", "description": "Successful result returned for a `terminal/release` request.", "allOf": [ { "$ref": "#/$defs/ReleaseTerminalResponse" } ] }, { "title": "WaitForTerminalExitResponse", "description": "Successful result returned for a `terminal/wait_for_exit` request.", "allOf": [ { "$ref": "#/$defs/WaitForTerminalExitResponse" } ] }, { "title": "KillTerminalResponse", "description": "Successful result returned for a `terminal/kill` request.", "allOf": [ { "$ref": "#/$defs/KillTerminalResponse" } ] }, { "title": "CreateElicitationResponse", "description": "Successful result returned for a `elicitation/create` request.", "allOf": [ { "$ref": "#/$defs/CreateElicitationResponse" } ] }, { "title": "ExtMethodResponse", "description": "Successful result returned by an extension method outside the core ACP method set.", "allOf": [ { "$ref": "#/$defs/ExtResponse" } ] } ] } }, "required": ["id", "result"] }, { "title": "Error", "description": "A failed JSON-RPC response.", "type": "object", "properties": { "id": { "description": "The id of the request this response answers.", "allOf": [ { "$ref": "#/$defs/RequestId" } ] }, "error": { "description": "Method-specific error data.", "allOf": [ { "$ref": "#/$defs/Error" } ] } }, "required": ["id", "error"] } ], "x-docs-ignore": true }, "WriteTextFileResponse": { "description": "Response to `fs/write_text_file`", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "client", "x-method": "fs/write_text_file" }, "ReadTextFileResponse": { "description": "Response containing the contents of a text file.", "type": "object", "properties": { "content": { "description": "Content payload returned by this response.", "type": "string" }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["content"], "x-side": "client", "x-method": "fs/read_text_file" }, "RequestPermissionResponse": { "description": "Response to a permission request.", "type": "object", "properties": { "outcome": { "description": "The user's decision on the permission request.", "allOf": [ { "$ref": "#/$defs/RequestPermissionOutcome" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["outcome"], "x-side": "client", "x-method": "session/request_permission" }, "RequestPermissionOutcome": { "description": "The outcome of a permission request.", "oneOf": [ { "description": "The prompt turn was cancelled before the user responded.\n\nWhen a client sends a `session/cancel` notification to cancel an ongoing\nprompt turn, it MUST respond to all pending `session/request_permission`\nrequests with this `Cancelled` outcome.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)", "type": "object", "properties": { "outcome": { "type": "string", "const": "cancelled" } }, "required": ["outcome"] }, { "description": "The user selected one of the provided options.", "type": "object", "properties": { "outcome": { "type": "string", "const": "selected" } }, "required": ["outcome"], "allOf": [ { "$ref": "#/$defs/SelectedPermissionOutcome" } ] } ], "discriminator": { "propertyName": "outcome" } }, "SelectedPermissionOutcome": { "description": "The user selected one of the provided options.", "type": "object", "properties": { "optionId": { "description": "The ID of the option the user selected.", "allOf": [ { "$ref": "#/$defs/PermissionOptionId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["optionId"] }, "CreateTerminalResponse": { "description": "Response containing the ID of the created terminal.", "type": "object", "properties": { "terminalId": { "description": "The unique identifier for the created terminal.", "allOf": [ { "$ref": "#/$defs/TerminalId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["terminalId"], "x-side": "client", "x-method": "terminal/create" }, "TerminalOutputResponse": { "description": "Response containing the terminal output and exit status.", "type": "object", "properties": { "output": { "description": "The terminal output captured so far.", "type": "string" }, "truncated": { "description": "Whether the output was truncated due to byte limits.", "type": "boolean" }, "exitStatus": { "description": "Exit status if the command has completed.", "anyOf": [ { "$ref": "#/$defs/TerminalExitStatus" }, { "type": "null" } ], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["output", "truncated"], "x-side": "client", "x-method": "terminal/output" }, "TerminalExitStatus": { "description": "Exit status of a terminal command.", "type": "object", "properties": { "exitCode": { "description": "The process exit code (may be null if terminated by signal).", "type": ["integer", "null"], "format": "uint32", "minimum": 0, "x-deserialize-default-on-error": true }, "signal": { "description": "The signal that terminated the process (may be null if exited normally).", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } } }, "ReleaseTerminalResponse": { "description": "Response to terminal/release method", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "client", "x-method": "terminal/release" }, "WaitForTerminalExitResponse": { "description": "Response containing the exit status of a terminal command.", "type": "object", "properties": { "exitCode": { "description": "The process exit code (may be null if terminated by signal).", "type": ["integer", "null"], "format": "uint32", "minimum": 0, "x-deserialize-default-on-error": true }, "signal": { "description": "The signal that terminated the process (may be null if exited normally).", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "client", "x-method": "terminal/wait_for_exit" }, "KillTerminalResponse": { "description": "Response to `terminal/kill` method", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "x-side": "client", "x-method": "terminal/kill" }, "CreateElicitationResponse": { "description": "Response from the client to an elicitation request.", "type": "object", "properties": { "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "anyOf": [ { "description": "The user accepted and provided content.", "type": "object", "properties": { "action": { "type": "string", "const": "accept" } }, "required": ["action"], "allOf": [ { "$ref": "#/$defs/ElicitationAcceptAction" } ] }, { "description": "The user declined the elicitation.", "type": "object", "properties": { "action": { "type": "string", "const": "decline" } }, "required": ["action"] }, { "description": "The elicitation was cancelled.", "type": "object", "properties": { "action": { "type": "string", "const": "cancel" } }, "required": ["action"] }, { "title": "other", "description": "Custom or future elicitation action.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nAgents that do not understand this action should preserve the raw\npayload when storing, replaying, proxying, or forwarding elicitation\nresponses. They MUST NOT treat it as a known elicitation action.", "type": "object", "properties": { "action": { "description": "Custom or future elicitation action.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", "type": "string" } }, "required": ["action"], "not": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "accept" } }, "required": ["action"] }, { "type": "object", "properties": { "action": { "type": "string", "const": "decline" } }, "required": ["action"] }, { "type": "object", "properties": { "action": { "type": "string", "const": "cancel" } }, "required": ["action"] } ] }, "additionalProperties": true } ], "x-side": "client", "x-method": "elicitation/create" }, "ElicitationContentValue": { "description": "Allowed wire representations for [`ElicitationContentValue`].", "anyOf": [ { "title": "String", "description": "String value accepted in elicitation response content.", "type": "string" }, { "title": "Integer", "description": "Integer value accepted in elicitation response content.", "type": "integer", "format": "int64" }, { "title": "Number", "description": "Number value accepted in elicitation response content.", "type": "number", "format": "double" }, { "title": "Boolean", "description": "Boolean value accepted in elicitation response content.", "type": "boolean" }, { "title": "StringArray", "description": "String array value accepted in elicitation response content.", "type": "array", "items": { "type": "string" } } ] }, "ElicitationAcceptAction": { "description": "The user accepted the elicitation and provided content.", "type": "object", "properties": { "content": { "description": "The user-provided content, if any, as an object matching the requested schema.", "type": ["object", "null"], "additionalProperties": { "$ref": "#/$defs/ElicitationContentValue" } } } }, "ClientNotification": { "description": "A JSON-RPC notification object.", "type": "object", "properties": { "method": { "description": "The notification method name.", "type": "string" }, "params": { "description": "Method-specific notification parameters.", "anyOf": [ { "description": "All possible notifications that a client can send to an agent.\n\nThis enum is used internally for routing RPC notifications. You typically won't need\nto use this directly.\n\nNotifications do not expect a response.", "anyOf": [ { "title": "CancelNotification", "description": "Cancels ongoing operations for a session.\n\nThis is a notification sent by the client to cancel an ongoing prompt turn.\n\nUpon receiving this notification, the Agent SHOULD:\n- Stop all language model requests as soon as possible\n- Abort all tool call invocations in progress\n- Send any pending `session/update` notifications\n- Respond to the original `session/prompt` request with `StopReason::Cancelled`\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)", "allOf": [ { "$ref": "#/$defs/CancelNotification" } ] }, { "title": "ExtNotification", "description": "Handles extension notifications from the client.\n\nExtension notifications provide a way to send one-way messages for custom functionality\nwhile maintaining protocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "allOf": [ { "$ref": "#/$defs/ExtNotification" } ] } ] }, { "type": "null" } ] } }, "required": ["method"], "x-docs-ignore": true }, "CancelNotification": { "description": "Notification to cancel ongoing operations for a session.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)", "type": "object", "properties": { "sessionId": { "description": "The ID of the session to cancel operations for.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["sessionId"], "x-side": "agent", "x-method": "session/cancel" }, "CancelRequestNotification": { "description": "Notification to cancel an ongoing request.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)", "type": "object", "properties": { "requestId": { "description": "The ID of the request to cancel.", "allOf": [ { "$ref": "#/$defs/RequestId" } ] }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true } }, "required": ["requestId"], "x-side": "protocol", "x-method": "$/cancel_request" } } }