### NES Config Options Example

Source: https://agentclientprotocol.com/rfds/next-edit-suggestions

Example of NES-related configuration options exposed by the agent using the configOptions mechanism.

```json
{
  "configOptions": [
    {
      "id": "nes_model",
      "name": "Prediction Model",
      "category": "model",
      "type": "enum",
      "currentValue": "fast",
      "options": [
        { "value": "fast", "label": "Fast" },
        { "value": "accurate", "label": "Accurate" }
      ]
    }
  ]
}
```

--------------------------------

### Initialize Response Example

Source: https://agentclientprotocol.com/rfds/custom-llm-endpoint

Example JSON structure for an initialize RPC response, including protocol version, agent information, and capabilities.

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentInfo": {
      "name": "MyAgent",
      "version": "2.0.0"
    },
    "agentCapabilities": {
      "providers": {},
      "sessionCapabilities": {}
    }
  }
}
```

--------------------------------

### Providers List Request Example

Source: https://agentclientprotocol.com/rfds/custom-llm-endpoint

Example JSON structure for a `providers/list` RPC request.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "providers/list",
  "params": {}
}
```

--------------------------------

### Capability Advertisement Example

Source: https://agentclientprotocol.com/rfds/additional-directories

An example JSON payload demonstrating how an agent advertises its capability to support 'additionalDirectories'.

```APIDOC
## Capability Advertisement Example

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "additionalDirectories": {}
      }
    }
  }
}
```
```

--------------------------------

### Install Python SDK

Source: https://agentclientprotocol.com/libraries/python

Install the agent-client-protocol package using pip. This is the primary method for adding the SDK to your Python project.

```bash
pip install agent-client-protocol
```

--------------------------------

### JSON: Capability Advertisement Example

Source: https://agentclientprotocol.com/rfds/additional-directories

Example of an agent advertising support for additionalDirectories.

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "additionalDirectories": {}
      }
    }
  }
}
```

--------------------------------

### Install Agent Client Protocol SDK

Source: https://agentclientprotocol.com/libraries/typescript

Install the SDK package using npm. This is the first step to using the Agent Client Protocol in your TypeScript project.

```bash
npm install @agentclientprotocol/sdk
```

--------------------------------

### Providers List Response Example

Source: https://agentclientprotocol.com/rfds/custom-llm-endpoint

Example JSON structure for a `providers/list` RPC response, detailing configured providers and their status.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "providers": [
      {
        "id": "main",
        "supported": ["bedrock", "vertex", "azure", "anthropic"],
        "required": true,
        "current": {
          "apiType": "anthropic",
          "baseUrl": "http://localhost/anthropic"
        }
      },
      {
        "id": "openai",
        "supported": ["openai"],
        "required": false,
        "current": null
      }
    ]
  }
}
```

--------------------------------

### Start a Blocking Session

Source: https://agentclientprotocol.com/rfds/rust-sdk-v1

Use `start_session` to get an `ActiveSession` handle for blocking behavior without rightward drift. Requires 'static for closures and MCP servers.

```rust
let mut session = cx.build_session(workspace_path)
    .with_mcp_server(my_mcp_server)?
    .block_task()
    .start_session()
    .await?;

session.send_prompt("Hello")?;
let response = session.read_to_string().await?;
```

--------------------------------

### Example Stdio Transport Configuration

Source: https://agentclientprotocol.com/protocol/session-setup

Use this configuration for the default stdio transport. Ensure the command path is correct and any necessary arguments are provided.

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

--------------------------------

### Providers Set Request Example

Source: https://agentclientprotocol.com/rfds/custom-llm-endpoint

Example JSON structure for a `providers/set` RPC request, used to configure a provider with its API type, base URL, and headers.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "providers/set",
  "params": {
    "id": "main",
    "apiType": "anthropic",
    "baseUrl": "https://llm-gateway.corp.example.com/anthropic/v1",
    "headers": {
      "X-Request-Source": "my-ide"
    }
  }
}
```

--------------------------------

### Session List Request Example

Source: https://agentclientprotocol.com/rfds/session-list

Example of a JSON RPC request to list available sessions. Includes parameters like `cwd`, `createdAfter`, `cursor`, and `search` for filtering and pagination.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/list",
  "params": {
    "cwd": "/home/user/project",
    "createdAfter": "2025-10-20T00:00:00Z",
    "cursor": "eyJwYWdlIjogMn0=",
    "search": "auth"
  }
}
```

--------------------------------

### Client Initialize with Elicitation Capabilities

Source: https://agentclientprotocol.com/rfds/elicitation

Example of a client's `initialize` request, declaring support for both form-based and URL-based elicitations. Clients should include this to inform agents about their capabilities.

```json
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "clientCapabilities": {
      "fs": {
        "readTextFile": true,
        "writeTextFile": true
      },
      "terminal": true,
      "elicitation": {
        "form": {},
        "url": {}
      }
    },
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}
```

--------------------------------

### Start NES Session Request

Source: https://agentclientprotocol.com/rfds/next-edit-suggestions

Client sends workspace metadata to start a new NES session. All fields in params are optional. The repository field is omitted if the workspace is not a git repository or the info is unavailable.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nes/start",
  "params": {
    "workspaceUri": "file:///Users/alice/projects/my-app",
    "workspaceFolders": [
      {
        "uri": "file:///Users/alice/projects/my-app",
        "name": "my-app"
      }
    ],
    "repository": {
      "name": "my-app",
      "owner": "alice",
      "remoteUrl": "https://github.com/alice/my-app.git"
    }
  }
}
```

--------------------------------

### HTTP Request Flow Example

Source: https://agentclientprotocol.com/rfds/streamable-http-websocket-transport

Illustrates a typical sequence of HTTP requests and responses for session management, including initialization, session loading, and receiving notifications.

```text
│<─────────────│─ SSE event ─────────│  { id: 5, result: { sessionId: "sess_abc123", ... } }
  │              │                     │  (response comes on GET stream)
  │              │                     │
  │  ═══ Resume Session Flow ═══       │
  │  (new connection, existing session)│
  │                                    │
  │─── POST /acp ─────────────────────>│  { method: "initialize", id: 1 }
  │    (no Acp-Connection-Id)          │  New connection
  │<────── 200 OK ─────────────────────│  { id: 1, result: { capabilities, connectionId } }
  │    Acp-Connection-Id: <new_conn>   │
  │                                    │
  │─── GET /acp ──────────────────────>│  Open new GET stream
  │    Acp-Connection-Id: <new_conn>   │
  │              ┌─────────────────────│  (SSE stream open)
  │              │                     │
  │─── POST /acp ─────────────────────>│  { method: "session/load", id: 2,
  │    Acp-Connection-Id: <new_conn>   │    params: { sessionId: "sess_abc123", cwd } }
  │    Acp-Session-Id: sess_abc123     │
  │                                    │
  │<────── 202 Accepted ───────────────│
  │              │                     │
  │<─────────────│─ SSE event ─────────│  notification: UserMessageChunk (sessionId: "sess_abc123")
  │<─────────────│─ SSE event ─────────│  notification: AgentMessageChunk (sessionId: "sess_abc123")
  │<─────────────│─ SSE event ─────────│  notification: ToolCall (sessionId: "sess_abc123")
  │<─────────────│─ SSE event ─────────│  notification: ToolCallUpdate (sessionId: "sess_abc123")
  │<─────────────│─ SSE event ─────────│  { id: 2, result: { sessionId: "sess_abc123" } }
  │              │                     │  (response comes on GET stream)
  │              │                     │
  │  ═══ Connection Termination ═══    │
  │                                    │
  │─── DELETE /acp ───────────────────>│  Terminate connection
  │    Acp-Connection-Id: <conn_id>    │
  │<────────── 202 Accepted ───────────│
  │              ▼                     │  (GET stream closes)

```

--------------------------------

### Session List Response Example

Source: https://agentclientprotocol.com/rfds/session-list

Example of a JSON RPC response for `session/list`. It includes a list of sessions and a `nextCursor` for paginating through results. Clients should treat cursors as opaque tokens.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "sessions": [
      /* ... */
    ],
    "nextCursor": "eyJwYWdlIjogM30="
  }
}
```

--------------------------------

### Respond to Permission Request

Source: https://agentclientprotocol.com/protocol/tool-calls

The client responds with the user's decision on the permission request. This example shows the user selecting an option.

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "outcome": {
      "outcome": "selected",
      "optionId": "allow-once"
    }
  }
}
```

--------------------------------

### JSON: session/list Response Example

Source: https://agentclientprotocol.com/rfds/additional-directories

Agent response to session/list, including authoritative additional-root list for each session.

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "sessions": [
      {
        "sessionId": "sess_abc123",
        "cwd": "/home/user/project",
        "additionalDirectories": [
          "/home/user/shared-lib",
          "/home/user/product-docs"
        ],
        "updatedAt": "2026-03-24T12:00:00Z"
      }
    ]
  }
}
```

--------------------------------

### JSON: session/list Request Example

Source: https://agentclientprotocol.com/rfds/additional-directories

Client request to list sessions, filtering by cwd and additionalDirectories.

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "session/list",
  "params": {
    "cwd": "/home/user/project",
    "additionalDirectories": [
      "/home/user/shared-lib",
      "/home/user/product-docs"
    ]
  }
}
```

--------------------------------

### Example HTTP Transport Configuration

Source: https://agentclientprotocol.com/protocol/session-setup

Configure this for HTTP transport when the agent supports mcpCapabilities.http. The URL and headers should be set according to the MCP server's requirements.

```json
{
  "type": "http",
  "name": "api-server",
  "url": "https://api.example.com/mcp",
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer token123"
    },
    {
      "name": "Content-Type",
      "value": "application/json"
    }
  ]
}
```

--------------------------------

### Client Capabilities: Full Elicitation Support

Source: https://agentclientprotocol.com/rfds/elicitation

Example of client capabilities declaring support for both form-based and URL-based elicitations, indicating a full-featured client.

```json
"elicitation": {
  "form": {},
  "url": {}
}
```

--------------------------------

### Example SSE Transport Configuration

Source: https://agentclientprotocol.com/protocol/session-setup

This configuration is for SSE transport, which is deprecated. Use only if the agent supports mcpCapabilities.sse and no other transport is suitable.

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

--------------------------------

### POST /terminal/create

Source: https://agentclientprotocol.com/protocol/terminals

Starts a command in a new terminal session. The Client returns a Terminal ID immediately, allowing the command to run in the background.

```APIDOC
## POST /terminal/create

### Description
Starts a command in a new terminal. The Client returns a Terminal ID immediately, allowing the command to run in the background.

### Method
POST

### Endpoint
/terminal/create

### Parameters
#### Request Body
- **sessionId** (SessionId) - Required - The Session ID for this request.
- **command** (string) - Required - The command to execute.
- **args** (string[]) - Optional - Array of command arguments.
- **env** (EnvVariable[]) - Optional - Environment variables for the command. Each variable has `name` (string) and `value` (string).
- **cwd** (string) - Optional - Working directory for the command (absolute path).
- **outputByteLimit** (number) - Optional - Maximum number of output bytes to retain. Older output is truncated if this limit is exceeded.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "terminal/create",
  "params": {
    "sessionId": "sess_abc123def456",
    "command": "npm",
    "args": ["test", "--coverage"],
    "env": [
      {
        "name": "NODE_ENV",
        "value": "test"
      }
    ],
    "cwd": "/home/user/project",
    "outputByteLimit": 1048576
  }
}
```

### Response
#### Success Response (200)
- **terminalId** (string) - The ID of the newly created terminal.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "terminalId": "term_xyz789"
  }
}
```
```

--------------------------------

### NES Session Start Authentication Error

Source: https://agentclientprotocol.com/rfds/next-edit-suggestions

Agent rejects nes/start with an auth_required error. Clients must handle this by prompting the user to authenticate and retrying the call.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Authentication required",
    "data": {
      "reason": "auth_required"
    }
  }
}
```

--------------------------------

### Define a Custom Extension Request for Workspace Buffers

Source: https://agentclientprotocol.com/protocol/extensibility

Custom extension methods must start with an underscore. This example shows a request to get buffers for a specific language.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "_zed.dev/workspace/buffers",
  "params": {
    "language": "rust"
  }
}
```

--------------------------------

### Elicitation Request - Request Scoped Form Mode

Source: https://agentclientprotocol.com/rfds/elicitation

This example shows a request-scoped elicitation using form mode. Request-scoped requests use `requestId` and are typically used for operations outside of an established session, like initial setup or authentication.

```json
{
  "jsonrpc": "2.0",
  "id": 45,
  "method": "elicitation/create",
  "params": {
    "requestId": 12,
    "mode": "form",
    "message": "Please provide your workspace name to continue setup.",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "workspaceName": {
          "type": "string",
          "title": "Workspace Name",
          "description": "The name of your workspace"
        }
      },
      "required": ["workspaceName"]
    }
  }
}
```

--------------------------------

### Providers Disable Response Example

Source: https://agentclientprotocol.com/rfds/custom-llm-endpoint

Example JSON structure for a `providers/disable` RPC response.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {}
}
```

--------------------------------

### NES Session Start

Source: https://agentclientprotocol.com/rfds/next-edit-suggestions

Initiates a new NES session by providing workspace metadata. All fields in `params` are optional. The `repository` field is omitted if the workspace is not a git repository or the info is unavailable.

```APIDOC
## POST /websites/agentclientprotocol/nes/start

### Description
Starts a new NES session with workspace metadata.

### Method
POST

### Endpoint
/websites/agentclientprotocol/nes/start

### Request Body
- **workspaceUri** (string) - Optional - The URI of the workspace.
- **workspaceFolders** (array) - Optional - An array of workspace folder objects.
  - **uri** (string) - Required - The URI of the workspace folder.
  - **name** (string) - Required - The name of the workspace folder.
- **repository** (object) - Optional - Information about the git repository.
  - **name** (string) - Required - The name of the repository.
  - **owner** (string) - Required - The owner of the repository.
  - **remoteUrl** (string) - Required - The remote URL of the repository.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nes/start",
  "params": {
    "workspaceUri": "file:///Users/alice/projects/my-app",
    "workspaceFolders": [
      {
        "uri": "file:///Users/alice/projects/my-app",
        "name": "my-app"
      }
    ],
    "repository": {
      "name": "my-app",
      "owner": "alice",
      "remoteUrl": "https://github.com/alice/my-app.git"
    }
  }
}
```

### Response
#### Success Response (200)
- **sessionId** (string) - The unique identifier for the NES session.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sessionId": "session_abc123"
  }
}
```

#### Error Handling
- **auth_required** - Indicates that authentication is required. The client should prompt the user to authenticate and retry the `nes/start` call.
```

--------------------------------

### NES Session Start Response

Source: https://agentclientprotocol.com/rfds/next-edit-suggestions

Successful response from the agent after starting an NES session, containing a unique sessionId.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sessionId": "session_abc123"
  }
}
```

--------------------------------

### Providers Disable Request Example

Source: https://agentclientprotocol.com/rfds/custom-llm-endpoint

Example JSON structure for a `providers/disable` RPC request, specifying the provider ID to disable.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "providers/disable",
  "params": {
    "id": "openai"
  }
}
```

--------------------------------

### WebSocket Connection Establishment

Source: https://agentclientprotocol.com/rfds/streamable-http-websocket-transport

Demonstrates the client and server interaction for establishing a WebSocket connection using the HTTP Upgrade header.

```text
Client                                    Server
  │  GET /acp                               │
  │  Upgrade: websocket                     │
  │────────────────────────────────────────►│
  │  HTTP 101 Switching Protocols           │
  │  Acp-Connection-Id: <uuid>              │
  │◄────────────────────────────────────────│
  │  ══════ WebSocket Channel ══════════════│
```

--------------------------------

### Mermaid Sequence Diagram for Proxy Initialization

Source: https://agentclientprotocol.com/rfds/proxy-chains

This diagram illustrates the flow of session initialization and prompt handling between a client, a Sparkle proxy, and an agent, including session notifications.

```mermaid
sequenceDiagram
    participant Client
    participant Sparkle as Sparkle Proxy
    participant Agent

    Note over Client: Client creates new session
    Client->>Sparkle: session/new

    Note over Sparkle: Adds Sparkle MCP server
    Sparkle->>Agent: session/new + sparkle tools
    Agent-->>Sparkle: session created (sessionId: S1)
    Sparkle-->>Client: session/new response (sessionId: S1)

    Note over Client: Client sends first prompt (during embodiment)
    Client->>Sparkle: prompt ('Hello, can you help me?')
    activate Sparkle

    Note over Sparkle: Delays client prompt, runs embodiment first
    Sparkle->>Agent: prompt ('you are sparkle...')

    Note over Agent: Processes embodiment, sends notifications
    Agent->>Sparkle: session/update (S1: thinking...)
    Sparkle->>Client: session/update (S1: thinking...)

    Agent->>Sparkle: session/update (S1: embodiment complete)
    Sparkle->>Client: session/update (S1: embodiment complete)

    Agent-->>Sparkle: embodiment response
    Note over Sparkle: Discards embodiment response, now processes delayed prompt

    Sparkle->>Agent: prompt ('Hello, can you help me?')
    deactivate Sparkle
    Agent-->>Sparkle: response to client
    Sparkle-->>Client: response to client

    Note over Client,Agent: Session ready with Sparkle patterns active
```

--------------------------------

### Agent Initialization API

Source: https://agentclientprotocol.com/protocol/schema

Establishes the connection with a client and negotiates protocol capabilities, including protocol version and authentication methods.

```APIDOC
## POST /agent/initialize

### Description
Establishes the connection with a client and negotiates protocol capabilities. This method is called once at the beginning of the connection to negotiate the protocol version, exchange capability information, and determine available authentication methods.

### Method
POST

### Endpoint
/agent/initialize

### Parameters
#### Request Body
- **_meta** (object | null) - Optional - The _meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions.
- **clientCapabilities** (ClientCapabilities) - Optional - Capabilities supported by the client. Default: `{"fs":{"readTextFile":false,"writeTextFile":false},"terminal":false}`
- **clientInfo** (Implementation | null) - Optional - Information about the Client name and version sent to the Agent. Note: in future versions of the protocol, this will be required.
- **protocolVersion** (ProtocolVersion) - Required - The latest protocol version supported by the client.

### Request Example
{
  "protocolVersion": "1.0.0",
  "clientCapabilities": {
    "fs": {
      "readTextFile": true,
      "writeTextFile": false
    },
    "terminal": true
  },
  "clientInfo": {
    "name": "MyClient",
    "version": "1.2.3"
  }
}

### Response
#### Success Response (200)
- **_meta** (object | null) - The _meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions.

#### Response Example
{
  "_meta": null
}
```

--------------------------------

### JSON-RPC Logout Request Example

Source: https://agentclientprotocol.com/rfds/logout-method

An example of a JSON-RPC request to initiate a logout. It specifies the method as 'logout' and includes an empty parameters object.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "logout",
  "params": {}
}
```

--------------------------------

### Example of future message editing capability

Source: https://agentclientprotocol.com/rfds/message-id

This example demonstrates a potential future capability for editing messages. It uses `messageId` to identify the specific message to be updated.

```json
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "message_update",
      "messageId": "ea87d0e7-beb8-484a-a404-94a30b78a5a8",
      "updateType": "replace",
      "content": {
        "type": "text",
        "text": "Actually, let me correct that analysis..."
      }
    }
  }
}
```

--------------------------------

### InitializeResponse

Source: https://agentclientprotocol.com/protocol/schema

Response to the `initialize` method. Contains the negotiated protocol version and agent capabilities.

```APIDOC
## InitializeResponse

### Description
Response to the `initialize` method. Contains the negotiated protocol version and agent capabilities.

### Response
#### Success Response (200)
- **_meta** (object | null) - The _meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.
- **agentCapabilities** (AgentCapabilities) - Capabilities supported by the agent. Default: `{"loadSession":false,"mcpCapabilities":{"http":false,"sse":false},"promptCapabilities":{"audio":false,"embeddedContext":false,"image":false},"sessionCapabilities":{}}`
- **agentInfo** (Implementation | null) - Information about the Agent name and version sent to the Client. Note: in future versions of the protocol, this will be required.
- **authMethods** (AuthMethod[]) - Authentication methods supported by the agent. Default: `[]`
- **protocolVersion** (ProtocolVersion) - The protocol version the client specified if supported by the agent, or the latest protocol version supported by the agent. The client should disconnect, if it doesn't support this version.

### Response Example
```json
{
  "_meta": null,
  "agentCapabilities": {
    "loadSession": false,
    "mcpCapabilities": {
      "http": false,
      "sse": false
    },
    "promptCapabilities": {
      "audio": false,
      "embeddedContext": false,
      "image": false
    },
    "sessionCapabilities": {}
  },
  "agentInfo": {
    "name": "ExampleAgent",
    "version": "1.0.0"
  },
  "authMethods": [],
  "protocolVersion": {
    "major": 1,
    "minor": 0
  }
}
```
```

--------------------------------

### Initial Session State with Config Options

Source: https://agentclientprotocol.com/protocol/session-config-options

This JSON structure represents the initial state of a session, including a list of available configuration options and their current values. Agents may provide this during session setup to allow clients to offer users customizable selectors.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sessionId": "sess_abc123def456",
    "configOptions": [
      {
        "id": "mode",
        "name": "Session Mode",
        "description": "Controls how the agent requests permission",
        "category": "mode",
        "type": "select",
        "currentValue": "ask",
        "options": [
          {
            "value": "ask",
            "name": "Ask",
            "description": "Request permission before making any changes"
          },
          {
            "value": "code",
            "name": "Code",
            "description": "Write and modify code with full tool access"
          }
        ]
      },
      {
        "id": "model",
        "name": "Model",
        "category": "model",
        "type": "select",
        "currentValue": "model-1",
        "options": [
          {
            "value": "model-1",
            "name": "Model 1",
            "description": "The fastest model"
          },
          {
            "value": "model-2",
            "name": "Model 2",
            "description": "The most powerful model"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### JSON-RPC Logout Response Example

Source: https://agentclientprotocol.com/rfds/logout-method

An example of a successful JSON-RPC response to a logout request. It includes the request ID and an empty result object, indicating the session was terminated.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

--------------------------------

### Advertise Custom Capabilities in Agent Initialization

Source: https://agentclientprotocol.com/protocol/extensibility

Use the `_meta` field within `agentCapabilities` to advertise support for custom extensions, enabling feature negotiation.

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "loadSession": true,
      "_meta": {
        "zed.dev": {
          "workspace": true,
          "fileNotifications": true
        }
      }
    }
  }
}
```

--------------------------------

### Start a Session Proxy with Injected MCP Servers

Source: https://agentclientprotocol.com/rfds/rust-sdk-v1

Use `start_session_proxy` for proxies that inject MCP servers while forwarding all messages. Session messages are automatically proxied between client and agent.

```rust
.on_receive_request(async |req: NewSessionRequest, request_cx, cx| {
    let session_id = cx.build_session_from(req)
        .with_mcp_server(injected_tools)?
        .block_task()
        .start_session_proxy(request_cx)
        .await?;

    // Session messages are automatically proxied between client and agent
    Ok(())
}, acp::on_receive_request!())
```

--------------------------------

### Open GET Stream for Server Messages

Source: https://agentclientprotocol.com/rfds/streamable-http-websocket-transport

The client opens a long-lived Server-Sent Events (SSE) stream by sending a GET request to /acp with the 'Accept: text/event-stream' header. This stream is used for all server-to-client messages.

```http
GET /acp HTTP/1.1
Acp-Connection-Id: <conn_id>
Accept: text/event-stream
```

--------------------------------

### PermissionOptionKind

Source: https://agentclientprotocol.com/protocol/schema

Specifies the type of permission option, guiding UI treatment.

```APIDOC
## PermissionOptionKind

The type of permission option being presented to the user.
Helps clients choose appropriate icons and UI treatment.

**Type:** Union

### Possible Values
- **allow_once** (string) - Allow this operation only this time.
- **allow_always** (string) - Allow this operation and remember the choice.
- **reject_once** (string) - Reject this operation only this time.
- **reject_always** (string) - Reject this operation and remember the choice.
```

--------------------------------

### Build Agent to Client Connection

Source: https://agentclientprotocol.com/rfds/rust-sdk-v1

Use this when acting as an agent serving clients. The `.name()` method is optional and aids in tracing.

```rust
AgentToClient::builder()
    .name("my-agent") // optional, useful for tracing
```

--------------------------------

### Session Update - Agent Message Chunk

Source: https://agentclientprotocol.com/protocol/session-setup

This example shows an agent message chunk being replayed during session loading.

```json
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_789xyz",
    "update": {
      "sessionUpdate": "agent_message_chunk",
      "content": {
        "type": "text",
        "text": "The capital of France is Paris."
      }
    }
  }
}
```

--------------------------------

### GET /acp - WebSocket Connection

Source: https://agentclientprotocol.com/rfds/streamable-http-websocket-transport

Establishes a WebSocket connection for bidirectional messaging. Requires `Upgrade: websocket` header.

```APIDOC
## GET /acp (WebSocket)

### Description
Establishes a WebSocket connection for real-time, bidirectional communication. This is an alternative to the SSE stream.

### Method
GET

### Endpoint
/acp

### Parameters
#### Headers
- **Upgrade** (string) - Required - Must be `websocket`.
- **Acp-Connection-Id** (string) - Optional - If resuming a connection, otherwise omitted for new connections.

### Response
#### Success Response (101 Switching Protocols)
- The server acknowledges the upgrade request and switches to the WebSocket protocol.
- **Acp-Connection-Id** (string) - The ID of the established connection, returned in headers.

#### Response Example
```
HTTP/1.1 101 Switching Protocols
Acp-Connection-Id: <uuid>
Upgrade: websocket
Connection: Upgrade

```

### WebSocket Messaging
All messages over the WebSocket are JSON-RPC frames. The first message must be an `initialize` request.
```

--------------------------------

### Conductor Initializes Agent

Source: https://agentclientprotocol.com/rfds/proxy-chains

Use this method for the conductor to initialize the final agent component in a standard ACP setup.

```json
{"method": "initialize", "params": <INITIALIZE_REQUEST_PARAMS>}
```

--------------------------------

### Check Client Filesystem Support

Source: https://agentclientprotocol.com/protocol/file-system

Verify if the client supports filesystem operations like reading and writing text files before attempting to use them. This check is performed against the 'clientCapabilities.fs' field in the initialize response.

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "clientCapabilities": {
      "fs": {
        "readTextFile": true,
        "writeTextFile": true
      }
    }
  }
}
```

--------------------------------

### Configure Client Sessions with Session Builders

Source: https://agentclientprotocol.com/rfds/rust-sdk-v1

The session builder API offers a fluent interface for session configuration. Start with `cx.build_session()` or `cx.build_session_from()` and chain methods like `with_mcp_server`.

```rust
cx.build_session("/path/to/workspace")
    .with_mcp_server(my_mcp_server)?    // Attach MCP servers (see below)
    // ... additional configuration
```

--------------------------------

### Session Delete JSON-RPC Method Call

Source: https://agentclientprotocol.com/rfds/session-delete

This is an example of a `session/delete` JSON-RPC method call. The `sessionId` parameter specifies the session to be removed.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "session/delete",
  "params": {
    "sessionId": "sess_abc123def456"
  }
}
```

--------------------------------

### Build Client to Agent Connection

Source: https://agentclientprotocol.com/rfds/rust-sdk-v1

Use this when acting as a client connecting to an agent. The `.name()` method is optional and aids in tracing.

```rust
ClientToAgent::builder()
    .name("my-client") // optional, useful for tracing
```

--------------------------------

### Audio Content Block Example

Source: https://agentclientprotocol.com/protocol/content

Contains audio data for transcription or analysis. Requires the 'audio' prompt capability. The data should be Base64-encoded.

```json
{
  "type": "audio",
  "mimeType": "audio/wav",
  "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAAB..."
}
```

--------------------------------

### Binary Distribution Agent Manifest

Source: https://agentclientprotocol.com/rfds/acp-agent-registry

Example of an agent manifest using binary distribution. Ensure builds are provided for all three operating systems (darwin, linux, windows) as CI will reject subsets. Each target requires an archive URL, command, and optional arguments or environment variables.

```json
{
  "id": "someagent",
  "name": "SomeAgent",
  "version": "1.0.0",
  "description": "Agent for code editing",
  "repository": "https://github.com/example/someagent",
  "authors": ["Example Team"],
  "license": "MIT",
  "icon": "icon.svg",
  "distribution": {
    "binary": {
      "darwin-aarch64": {
        "archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-arm64.zip",
        "cmd": "./someagent",
        "args": ["acp"],
      },
      "darwin-x86_64": {
        "archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-x64.zip",
        "cmd": "./someagent",
        "args": ["acp"],
      },
      "linux-aarch64": {
        "archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-arm64.zip",
        "cmd": "./someagent",
        "args": ["acp"],
      },
      "linux-x86_64": {
        "archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-x64.zip",
        "cmd": "./someagent",
        "args": ["acp"],
      },
      "windows-x86_64": {
        "archive": "https://github.com/example/someagent/releases/latest/download/someagent-windows-x64.zip",
        "cmd": "./someagent.exe",
        "args": ["acp"],
        "env": {
          "SOMEAGENT_MODE_KEY": "",
        },
      },
    },
  },
}
```