### Initialize Response Example

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/custom-llm-endpoint.mdx

Example JSON response after initializing the agent, indicating protocol version and agent capabilities.

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

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

### New Session with Additional Directories

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/additional-directories.mdx

Example of initiating a new session with specified `additionalDirectories`.

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

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

### NES Config Options Example

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/next-edit-suggestions.mdx

Example of NES-related configuration options exposed via the configOptions mechanism. This allows agents to expose settings like prediction models.

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

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

### Load Session with Additional Directories

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/additional-directories.mdx

Example of loading an existing session, including its `additionalDirectories`.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/load",
  "params": {
    "sessionId": "sess_abc123",
    "cwd": "/home/user/project",
    "additionalDirectories": [
      "/home/user/shared-lib",
      "/home/user/product-docs"
    ],
    "mcpServers": []
  }
}
```

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

### Starting a Session

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/rust-sdk-v1.mdx

Starts a new session and returns an `ActiveSession` handle for blocking behavior. This is useful to avoid the rightward drift of `run_until`.

```APIDOC
## `start_session`

### Description
Starts a new session and returns an `ActiveSession` handle, enabling blocking behavior.

### Method
```rust
.start_session()
```

### Usage Example
```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?;
```
```

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

### List Providers Response Example

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/custom-llm-endpoint.mdx

Example JSON response from a providers/list request, detailing available LLM providers, their supported types, and current configurations.

```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
      }
    ]
  }
}
```

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

### Agent Connection Builder

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/rust-sdk-v1.mdx

Use this to start serving clients as an agent. The `.name()` method is optional and useful for tracing.

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

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

### Patchwork Tool Definition Example

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/rust-sdk-v1.mdx

This example demonstrates how to define and use a custom tool within the Patchwork project, showcasing asynchronous execution and capturing results.

```rust
let mut results = Vec::new();

let _: () = patchwork.think()
    .text("Process each item and record it using the `record` tool")
    .tool(
        "record",
        "Record a processed item",
        async |input: RecordInput, _cx| {
            results.push(input.item);
            Ok(RecordOutput { success: true })
        },
        acp::tool_fn_mut!(),
    )
    .await?;

// After the think block, `results` contains all recorded items
println!("Recorded: {:?}", results);
```

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

### Resume Session with Additional Directories

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/additional-directories.mdx

Example of resuming a session, re-establishing its `additionalDirectories`.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "session/resume",
  "params": {
    "sessionId": "sess_abc123",
    "cwd": "/home/user/project",
    "additionalDirectories": [
      "/home/user/shared-lib",
      "/home/user/product-docs"
    ],
    "mcpServers": []
  }
}
```

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

### List Providers Request Example

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/custom-llm-endpoint.mdx

JSON-RPC request to list available LLM providers supported by the agent.

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

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

### Client Capabilities: Full-Featured Client (JSON)

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/elicitation.mdx

Example of `clientCapabilities` for a full-featured client supporting both form and URL-based elicitations.

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

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

### Fork Session with Additional Directories

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/additional-directories.mdx

Example of forking a session, inheriting `additionalDirectories`.

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "session/fork",
  "params": {
    "sessionId": "sess_abc123",
    "cwd": "/home/user/project",
    "additionalDirectories": [
      "/home/user/shared-lib",
      "/home/user/product-docs"
    ],
    "mcpServers": []
  }
}
```

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

### nes/start

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v1/draft/schema.mdx

Starts an NES session. This capability is not part of the spec yet, and may be removed or changed at any point.

```APIDOC
## POST /nes/start

### Description
Starts an NES session.

### Method
POST

### Endpoint
/nes/start

### Request Body
#### StartNesRequest

**Type:** Object

**Properties:**
- **_meta** (object | null) - Optional - Reserved by ACP for metadata.
- **repository** (NesRepository | null) - Optional - Repository metadata, if the workspace is a git repository.
- **workspaceFolders** (WorkspaceFolder[] | null) - Optional - The workspace folders.
- **workspaceUri** (string | null) - Optional - The root URI of the workspace.
```

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

### Client Capabilities: Headless Client (JSON)

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/elicitation.mdx

Example of `clientCapabilities` for a headless client that only supports form-based elicitation.

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

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

### Client Capabilities: Terminal with URL Support (JSON)

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/elicitation.mdx

Example of `clientCapabilities` for a simple terminal client that only supports URL-based elicitation.

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

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

### Elicitation Request: Request Scope Example

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/elicitation.mdx

This example demonstrates a request-scoped elicitation, typically used for setup or authentication phases before a session is established. It uses `requestId` instead of `sessionId`.

```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"]
    }
  }
}
```

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

### Start a Blocking Session

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/rust-sdk-v1.mdx

Use `start_session` to get an `ActiveSession` handle directly 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?;
```

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

### initialize

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v2/schema.mdx

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

```APIDOC
## 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 to use
- Exchange capability information between client and agent
- Determine available authentication methods

The agent should respond with its supported protocol version and capabilities.

### Request Body
#### InitializeRequest

Request parameters for the initialize method. Sent by the client to establish connection and negotiate capabilities.

**Type:** Object

**Properties:**
- **_meta** (object | null) - Optional - 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.
- **capabilities** (ClientCapabilities) - Optional - Capabilities supported by the client. Default: `{}`
- **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.

### Response
#### InitializeResponse

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

**Type:** Object

**Properties:**
- **_meta** (object | null) - Optional - 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.
- **agentInfo** (Implementation | null) - Optional - Information about the Agent name and version sent to the Client. Note: in future versions of the protocol, this will be required.
- **authMethods** (AuthMethod[]) - Optional - Authentication methods supported by the agent. Default: `[]`
- **capabilities** (AgentCapabilities) - Optional - Capabilities supported by the agent. Default: `{"auth":{}}`
- **protocolVersion** (ProtocolVersion) - Required - 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.
```

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

### Hierarchical Conductor Structure Example

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/proxy-chains.mdx

Visual representation of a nested conductor setup where one conductor manages other proxies, forming a tree-like structure for complex agent interactions.

```text
client → conductor1 → final-agent
         ↓ manages
     proxy-a → conductor2 → proxy-d
                  ↓ manages
              proxy-b → proxy-c
```

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

### initialize

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v1/overview.mdx

Negotiate versions and exchange capabilities to establish a connection.

```APIDOC
## POST /initialize

### Description
Negotiate versions and exchange capabilities.

### Method
POST

### Endpoint
/initialize

### Request Body
(Schema defined at /protocol/v1/schema#initialize)

### Response
#### Success Response (200)
(Schema defined at /protocol/v1/schema#initialize)
```

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

### Install Mintlify CLI

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/README.md

Installs the Mintlify CLI globally via npm. This is a prerequisite for running and previewing the documentation locally.

```bash
npm i -g mint
```

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

### Session Setup Sequence Diagram

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v1/draft/session-setup.mdx

Illustrates the different flows for creating, loading, or resuming a session between a Client and an Agent, including potential authentication requirements.

```mermaid
sequenceDiagram
    participant Client
    participant Agent

    Note over Agent,Client: Initialized

    alt
        Client->>Agent: session/new
        Note over Agent: Create session context
        Note over Agent: Connect to MCP servers
        Agent-->>Client: session/new response (sessionId)
    else
        Client->>Agent: session/load (sessionId)
        Note over Agent: Restore session context
        Note over Agent: Connect to MCP servers
        Note over Agent,Client: Replay conversation history...
        Agent->>Client: session/update
        Agent->>Client: session/update
        Note over Agent,Client: All content streamed
        Agent-->>Client: session/load response
    else
        Client->>Agent: session/resume (sessionId)
        Note over Agent: Restore session context
        Note over Agent: Connect to MCP servers
        Agent-->>Client: session/resume response
    end

    Note over Client,Agent: Ready for prompts
```

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

### Agent Session Initial State with Config Options

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v1/draft/session-config-options.mdx

During Session Setup, the Agent may return a list of configuration options and their current values. Clients SHOULD use these options instead of the 'modes' field.

```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"
          }
        ]
      },
      {
        "id": "context_size",
        "name": "Context Size",
        "category": "model_config",
        "type": "select",
        "currentValue": "200k",
        "options": [
          {
            "value": "200k",
            "name": "200K"
          },
          {
            "value": "1m",
            "name": "1M"
          }
        ]
      }
    ]
  }
}
```

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

### Get Terminal Output

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v1/draft/terminals.mdx

Retrieves the current output of a terminal. This method can be called to get the latest output without waiting for the command to complete.

```APIDOC
## terminal/output

### Description
Retrieves the current output and exit status of a terminal.

### Method
POST

### Endpoint
/terminal/output

### Parameters
#### Request Body
- **sessionId** (string) - Required - The ID of the session the terminal belongs to.
- **terminalId** (string) - Required - The ID of the terminal to retrieve output from.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "terminal/output",
  "params": {
    "sessionId": "sess_abc123def456",
    "terminalId": "term_xyz789"
  }
}
```

### Response
#### Success Response (200)
- **output** (string) - Required - The terminal output captured so far.
- **truncated** (boolean) - Required - Whether the output was truncated due to byte limits.
- **exitStatus** (object) - Optional - Present only if the command has exited.
  - **exitCode** (integer) - The process exit code (may be null).
  - **signal** (integer) - The signal that terminated the process (may be null).

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "output": "Running tests...\n✓ All tests passed (42 total)\n",
    "truncated": false,
    "exitStatus": {
      "exitCode": 0,
      "signal": null
    }
  }
}
```
```

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

### Agent Initialize Response with Auth Methods

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v1/authentication.mdx

This JSON shows an example of an Agent's initialize response, advertising supported authentication methods and the capability to log out.

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "auth": {
        "logout": {}
      }
    },
    "authMethods": [
      {
        "id": "agent-login",
        "name": "Agent login",
        "description": "Sign in using the agent's login flow"
      }
    ]
  }
}
```

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

### Session Setup Sequence Diagram

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v2/draft/session-setup.mdx

Illustrates the flow for creating, loading, or resuming a session between a Client and an Agent. This diagram covers the initial session establishment and subsequent interactions.

```mermaid
sequenceDiagram
    participant Client
    participant Agent

    Note over Agent,Client: Initialized

    alt
        Client->>Agent: session/new
        Note over Agent: Create session context
        Note over Agent: Connect to MCP servers
        Agent-->>Client: session/new response (sessionId)
    else
        Client->>Agent: session/load (sessionId)
        Note over Agent: Restore session context
        Note over Agent: Connect to MCP servers
        Note over Agent,Client: Replay conversation history...
        Agent->>Client: session/update
        Agent->>Client: session/update
        Note over Agent,Client: All content reported
        Agent-->>Client: session/load response
    else
        Client->>Agent: session/resume (sessionId)
        Note over Agent: Restore session context
        Note over Agent: Connect to MCP servers
        Agent-->>Client: session/resume response
    end

    Note over Client,Agent: Ready for prompts
```

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

### initialize

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v1/initialization.mdx

Clients MUST initialize the connection by calling the `initialize` method with the latest protocol version supported and the capabilities supported. They SHOULD also provide a name and version to the Agent.

```APIDOC
## POST /initialize

### Description
Initiates the Agent Client Protocol connection by negotiating protocol versions, capabilities, and optional client information.

### Method
POST

### Endpoint
/initialize

### Parameters
#### Request Body
- **protocolVersion** (integer) - Required - The latest protocol version supported by the client.
- **clientCapabilities** (object) - Required - The capabilities supported by the client.
  - **fs** (object) - Optional - File system capabilities.
    - **readTextFile** (boolean) - Optional - Whether the client supports reading text files.
    - **writeTextFile** (boolean) - Optional - Whether the client supports writing text files.
  - **terminal** (boolean) - Optional - Whether the client supports terminal interaction.
- **clientInfo** (object) - Optional - Information about the client.
  - **name** (string) - Optional - The name of the client.
  - **title** (string) - Optional - The title of the client.
  - **version** (string) - Optional - The version of the client.

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

### Response
#### Success Response (200)
- **protocolVersion** (integer) - The protocol version chosen for the connection.
- **agentCapabilities** (object) - The capabilities supported by the agent.
  - **loadSession** (boolean) - Whether the agent supports loading sessions.
  - **promptCapabilities** (object) - Capabilities related to prompting.
    - **image** (boolean) - Whether the agent supports image prompts.
    - **audio** (boolean) - Whether the agent supports audio prompts.
    - **embeddedContext** (boolean) - Whether the agent supports embedded context in prompts.
  - **mcpCapabilities** (object) - Capabilities related to the Message Communication Protocol.
    - **http** (boolean) - Whether the agent supports HTTP communication.
    - **sse** (boolean) - Whether the agent supports Server-Sent Events (SSE).
- **agentInfo** (object) - Information about the agent.
  - **name** (string) - The name of the agent.
  - **title** (string) - The title of the agent.
  - **version** (string) - The version of the agent.
- **authMethods** (array) - A list of supported authentication methods.

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

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

### Starting a Session Proxy

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/rust-sdk-v1.mdx

Starts a session proxy, allowing injection of MCP servers while forwarding all messages. This is useful for proxies that need to intercept or modify messages.

```APIDOC
## `start_session_proxy`

### Description
Starts a session proxy, forwarding all messages and allowing injection of MCP servers.

### Method
```rust
.start_session_proxy(request_cx)
```

### Usage Example
```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!())
```
```

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

### Initialization Sequence Diagram

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/proxy-chains.mdx

Illustrates the initialization flow for a 4-component proxy chain, showing the interaction between the Terminal Client, Conductor, Proxies, and Terminal Agent.

```APIDOC
## Initialization Sequence Diagram

This shows the initialization flow for: Terminal Client → Conductor → Context Proxy → Tool Filter Proxy → Terminal Agent

```mermaid
sequenceDiagram
    participant TC as Terminal Client
    participant C as Conductor
    participant P1 as Context Proxy
    participant P2 as Tool Filter Proxy
    participant TA as Terminal Agent

    Note over TC,TA: === Initialization Phase ===

    TC->>C: initialize

    Note over C: Conductor spawns proxy components
    C->>P1: proxy/initialize

    Note over P1: Proxy forwards to successor
    P1->>C: proxy/successor (initialize)

    Note over C: Conductor sends proxy/initialize to next proxy
    C->>P2: proxy/initialize

    Note over P2: Proxy forwards to successor
    P2->>C: proxy/successor (initialize)

    Note over C: Conductor sends initialize to final agent
    C->>TA: initialize

    TA-->>C: InitializeResponse (mcpCapabilities.acp: true/false)
    C-->>P2: proxy/successor (InitializeResponse)

    P2-->>C: InitializeResponse
    C-->>P1: proxy/successor (InitializeResponse)

    P1-->>C: InitializeResponse

    Note over C: Conductor acts as terminal agent to client
    C-->>TC: InitializeResponse

    Note over TC,TA: Proxy chain initialized and ready
```
```

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

### Client Capabilities Initialization (JSON)

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/elicitation.mdx

Example JSON payload for the `initialize` request, declaring client capabilities including URL elicitation support.

```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"
    }
  }
}
```

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

### NES Session Start Authentication Error

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/next-edit-suggestions.mdx

Handle this error response if authentication is required to start an NES session. Clients must prompt the user to authenticate and retry.

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

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

### Streamable HTTP Message Flow: Open Session-Scoped GET Stream

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/streamable-http-websocket-transport.mdx

The client opens a long-lived, session-scoped SSE stream for a specific session by sending a GET request to /acp, including both 'Acp-Connection-Id' and 'Acp-Session-Id'.

```HTTP
GET /acp HTTP/1.1
Host: example.com
Acp-Connection-Id: <conn_id>
Acp-Session-Id: sess_abc123
Accept: text/event-stream
```

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

### Streamable HTTP Message Flow: Open Connection-Scoped GET Stream

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/streamable-http-websocket-transport.mdx

After connection initialization, the client opens a long-lived, connection-scoped Server-Sent Events (SSE) stream by sending a GET request to /acp. This stream is used for connection-level server-to-client messages.

```HTTP
GET /acp HTTP/1.1
Host: example.com
Acp-Connection-Id: <conn_id>
Accept: text/event-stream
```

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

### Proxy and Agent Initialization Methods

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/proxy-chains.mdx

Demonstrates the JSON-RPC methods used by a conductor to initialize components. 'proxy/initialize' is used for components with successors (proxies), while 'initialize' is for terminal components (agents). Both expect standard ACP InitializeRequest parameters and return InitializeResponse.

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

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

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

### Client Connection Builder

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/rust-sdk-v1.mdx

Use this to initiate a connection as a client to an agent. The `.name()` method is optional and useful for tracing.

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

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

### Disable Provider Request Example

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/custom-llm-endpoint.mdx

JSON-RPC request to disable a specific LLM provider.

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

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

### Client Initialization Request

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v2/draft/initialization.mdx

Clients must send an 'initialize' request to the Agent. Include the latest protocol version supported and desired capabilities. Optionally, provide client name and version.

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": 2,
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "title": "My Client",
      "version": "1.0.0"
    }
  }
}
```

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

### Start NES Session Request

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/next-edit-suggestions.mdx

Send this JSON to initiate a new NES session, providing workspace and repository metadata. All fields in params are optional.

```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"
    }
  }
}
```

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

### Range

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v1/draft/schema.mdx

Represents a range within a text document, defined by start and end positions.

```APIDOC
## Range

A range in a text document, expressed as start and end positions.

**Type:** Object

**Properties:**

<ResponseField name="_meta" type={"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.

See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)

</ResponseField>
<ResponseField name="end" type={<a href="#position">Position</a>} required>
  The end position (exclusive).
</ResponseField>
<ResponseField name="start" type={<a href="#position">Position</a>} required>
  The start position (inclusive).
</ResponseField>
```

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

### Elicitation Complete Notification (JSON)

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/elicitation.mdx

Example JSON payload for an `elicitation/complete` notification sent by an agent.

```json
{
  "jsonrpc": "2.0",
  "method": "elicitation/complete",
  "params": {
    "elicitationId": "github-oauth-001"
  }
}
```

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

### Session List Request Example

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/session-list.mdx

This JSON object demonstrates a typical request to the session/list method, including parameters for current working directory, creation time, cursor for pagination, and a search term.

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

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

### state_update

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v2/schema.mdx

Indicates a change in the agent's session state, such as work starting, completing, or pausing.

```APIDOC
## state_update

The agent's session state has changed.

Agents send this to report when work starts, completes, or pauses while
waiting for user action. Completion of active work is reported here instead
of in the `session/prompt` response.

### Properties

- **sessionUpdate** (string) - Required - The discriminator value. Must be `"state_update"`.
```

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

### Client Initialization Request (Advertising Terminal Auth Support)

Source: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/protocol/v1/draft/authentication.mdx

Clients can advertise support for terminal-based authentication methods during initialization by setting `clientCapabilities.auth.terminal` to `true`.

```APIDOC
## Client Initialization Request (Advertising Terminal Auth Support)

Clients advertise this during initialization with `clientCapabilities.auth.terminal`.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientCapabilities": {
      "auth": {
        "terminal": true
      }
    }
  }
}
```
```