### Start Session Example

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

Code snippet for initiating a session, possibly requiring an await.

```rust
.start_session()?
```

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

### Session Setup Request Example

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

This snippet shows a typical session setup request, including the agent's capabilities and the initial prompt. It's used to establish a new conversation context with the agent.

```json
{
  "jsonrpc": "2.0",
  "method": "session/new",
  "id": 1,
  "params": {
    "agentId": "my-agent",
    "capabilities": {
      "sessionCapabilities.resume": true,
      "sessionCapabilities.additionalDirectories": true
    },
    "prompt": "Hello!",
    "additionalDirectories": {
      "/home/user/shared-lib": "",
      "/home/user/product-docs": ""
    }
  }
}
```

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

### Session Setup with Config Options

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

An example JSON response during Session Setup where an Agent provides a list of configuration options. This includes 'mode' and 'model' with their respective settings and available choices.

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

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

### Session Setup Request Example

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

This JSON snippet demonstrates a typical request for setting up a session. It includes the JSONRPC version and a unique identifier for the request.

```json
{
 "jsonrpc": "2.0",
 "id": 2,
 "result": 
```

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

### Example API Key Authentication

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

Illustrates the JSON structure for API key authentication during session setup. Ensure the 'X-API-Key' header is correctly formatted.

```json
{
  "jsonrpc": "2.0",
  "method": "agent_register",
  "params": {
    "apiKey": "apikey456"
  }
}
```

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

### Session Setup Request Example

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

This JSON structure represents a request to establish a new session. It includes the method, parameters like cwd, and configuration for MCP servers.

```json
{
  "id": 1,
  "method": "session/new",
  "params": {
    "cwd": "/home/user/project",
    "mcpServers": [
      {
        "name": "filesystem",
        "command": "/path/to/mcp-server",
        "args": [
          "--stdio"
        ],
        "env": {
          "MY_VAR": "my_value"
        }
      }
    ]
  }
}
```

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

### Building a Proxy with ACP

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

This example illustrates how to construct a proxy using the ACP Rust SDK. It shows the setup for a proxy that can receive notifications from an agent.

```rust
ProxyToConductor::builder()
 .on_receive_notification_from(
 acp::Agent::new(),
 |notification| async {
 // Handle notification here
 Ok(())
 },
 );

```

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

### Send Prompt Example

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

Example of sending a prompt within a session.

```rust
session.send_prompt("Hello")?
```

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

### Handle Session Start Event

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

This snippet demonstrates how to handle the `on_session_start` event. It shows the asynchronous nature of session handling and the initial setup for interacting with the session.

```rust
.on_session_start(async |session| {
  {

```

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

### With MCP Server Example

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

Example of using the 'with_mcp_server' function, likely for establishing a connection or context.

```rust
.with_mcp_server(my_mcp_server)?
```

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

### Example Agent Manifest

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

An example of a complete agent manifest file, demonstrating the structure and typical values for agent registration.

```json
{
  "name": "agent-integrations-settings",
  "enabled": true,
  "variant": {
    "name": "disabled",
    "enabled": false,
    "feature_enabled": true
  },
  "impressionData": false
}
```

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

### Session Configuration Example

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

Example of a session configuration object, specifying model, category, type, current value, and options.

```json
{
  "name": "Model",
  "category": "model",
  "type": "select",
  "currentValue": "model-1",
  "options": [
 {
 "value": "model-1",
 "name": "Model 1",
 "description": ""
 }
 ]
}
```

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

### Session Configuration Example

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

Example of a session configuration object, specifying a model group, its options, and details for a specific model.

```json
_jsx(_components.span, {
 style: {
 color: "#1F2328",
 "--shiki-dark": "#D4D4D4"
 },
 children: " ]"
 }), "\n" }), "\n", _jsx(_components.span, {
 className: "line",
 children: _jsx(_components.span, {
 style: {
 color: "#1F2328",
 "--shiki-dark": "#D4D4D4"
 },
 children: " }"
 }), "\n" }), "\n", _jsx(_components.span, {
 className: "line",
 children: _jsx(_components.span, {
 style: {
 color: "#1F2328",
 "--shiki-dark": "#D4D4D4"
 },
 children: " ]"
 }), "\n" }), "\n", _jsx(_components.span, {
 className: "line",
 children: _jsx(_components.span, {
 style: {
 color: "#1F2328",
 "--shiki-dark": "#D4D4D4"
 },
 children: "}"
 }), "\n"
 }), "\n"]
 }), "\n" }), "\n", _jsx(_components.p, {
 children: "We use a list of objects for all of these, to "
```

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

### Agent Prompting Example

Source: https://agentclientprotocol.com/rfds/v2/prompt

Example of sending a prompt to an agent, specifying the session ID, the update type, and the desired state.

```json
{
  "sessionId": "sess_789xyz",
  "update": {
    "sessionUpdate": "state_update",
    "state": "running"
  }
}
```

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

### Custom JSON-RPC Request Example

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

This example demonstrates the structure of a custom JSON-RPC request. Custom method names must start with an underscore. This is useful for invoking non-standard functionality.

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

```

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

### Example Session Mode Configuration

Source: https://agentclientprotocol.com/protocol/v1/session-modes

Demonstrates the structure for configuring session modes, including option IDs, names, and kinds.

```json
{
 "options": [
  {
   "optionId": "code",
   "name": "Yes, and auto-accept all actions",
   "kind": "allow_always"
  },
  {
   "optionId": "ask",
   "name": "Yes, and manually accept actions",
   "kind": "allow_once"
  }
 ]
}
```

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

### Define Refactoring Strategy

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

Example of defining a 'Refactoring Strategy' for elicitation. This strategy is used to guide information gathering.

```json
{
  "title": "Refactoring Strategy"
}
```

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

### Rust Atomic Handler Example

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

Demonstrates an atomic handler in Rust. Handlers starting with 'on_' execute sequentially, ensuring one completes before the next message is processed. This example shows a notification being sent after receiving a request.

```rust
.on_receive_request(async |req: PromptRequest, request_cx, cx|
 // No other messages will be processed while this runs
 cx.send_notification(StatusNotification::new("processing"))
)
```

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

### Build Session Example

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

This snippet demonstrates how to build a session with a specified workspace path.

```rust
.build_session("workspace_path")
```

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

### Client Initialization Request Example

Source: https://agentclientprotocol.com/protocol/v1/initialization

This snippet shows a client sending an initialization request to an agent. It includes the client's supported protocol version and a list of its capabilities.

```json
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "capabilities": {
      "workspaceFolders": true
    }
  }
}
```

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

### Proxy Chain Structure Example

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

Illustrates a hierarchical structure of proxy chains managed by conductors. This setup allows for complex routing and message forwarding.

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

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

### Client Initialize Request Example

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

Example excerpt of a client's 'initialize' request, showing the structure for declaring position encoding capabilities.

```json
{
 "clientCapabilities": {
 
 }
}
```

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

### Session Setup - Initial State with Modes

Source: https://agentclientprotocol.com/protocol/v1/session-modes

During session setup, an Agent MAY return a list of its available operating modes and specify the currently active mode. This JSON structure illustrates the expected format for communicating session mode information.

```APIDOC
## Initial State

During [Session Setup](/protocol/v1/session-setup) the Agent **MAY** return a list of modes it can operate in and the currently active mode:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sessionId": "sess_abc123def456",
    "modes": {
      "currentModeId": "ask",
      "availableModes": [
        {
          "id": "ask",
          "name": "Ask",
          "description": "Request permission before making any changes"
        },
        {
          "id": "architect",
          "name": "Architect",
          "description": "Design and plan software systems without implementation"
        },
        {
          "id": "code",
          "name": "Code",
          "description": "Write and modify code with full tool access"
        }
      ]
    }
  }
}
```

### Parameters

#### modes (SessionModeState)

The current mode state for the session

- **currentModeId** (SessionModeId) - required - The ID of the mode that is currently active
- **availableModes** (SessionMode[]) - required - The set of modes that the Agent can operate in
```

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

### Build Session with MCP Server

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

Example of building an MCP server session using the SDK. This snippet demonstrates how to configure the server path and specify tool functions.

```rust
cx.build_session(workspace_path)
 .with_mcp_server(McpServer::builder("tools"))
 .tool_fn("get_path", "Returns the path", async move |move |
```

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

### Custom JSON-RPC Request Example

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

Demonstrates a custom JSON-RPC request with a method name starting with an underscore, adhering to the protocol's extension method convention.

```json
{
  "jsonrpc": "2.0",
  "method": "_my_custom_method",
  "params": [
    1,
    "hello"
  ],
  "id": 1
}
```

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

### JSON-RPC Initialize Request Example

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

Demonstrates the structure of an 'initialize' request in JSON-RPC, including protocol version and client capabilities.

```json
{
 "jsonrpc": "2.0",
 "method": "initialize",
 "params": {
  "protocolVersion": "2025-11-25",
  "clientCapabilities": {
   "fs": {
    "readTextFile": true,
    "writeTextFile": true
   }
  }
 }
}
```

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

### Negotiating Custom Features

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

This example demonstrates how to define custom features and their values during initialization. It shows the structure for specifying features like 'zed.dev', 'workspace', and 'fileNotifications'.

```json
{
  "custom": {
    "zed.dev": {
      "workspace": true,
      "fileNotifications": true
    }
  }
}
```

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

### Get Terminal Output Request

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

Use the `terminal/output` method to retrieve the current terminal output without waiting for the command to complete. This is a JSON-RPC request example.

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

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

### Session Setup with Config Options

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

During Session Setup, the Agent MAY return a list of configuration options and their current values. This allows clients to present users with customizable selectors for session parameters.

```APIDOC
## Session Setup with Config Options

During [Session Setup](/protocol/v1/session-setup) the Agent **MAY** return a list of configuration options and their current values:

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

### `configOptions` Field

- **id** (string) - Required - A unique identifier for the configuration option.
- **name** (string) - Required - The display name for the configuration option.
- **description** (string) - Optional - A description of the configuration option.
- **category** (string) - Optional - A category to group configuration options.
- **type** (string) - Required - The type of the configuration option (e.g., "select").
- **currentValue** (string) - Required - The current selected value for this option.
- **options** (array) - Required - A list of available options for this configuration.
  - **value** (string) - Required - The value of the option.
  - **name** (string) - Required - The display name of the option.
  - **description** (string) - Optional - A description of the option.
```

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

### Agent Rejection of 'nes/start' with 'auth_required' Error

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

An example of an error response when an agent requires authentication to start a new session. The error code 'auth_required' indicates that authentication credentials are missing or invalid.

```json
{
 "jsonrpc": "2.0",
 "id": 1,
 "error": {
  "code": "auth_required",
  "message": "Authentication is required to start a new session."
 }
}

```

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

### Connection Establishment (GET with Upgrade)

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

Illustrates the HTTP GET request with an Upgrade header to establish a WebSocket connection. The server responds with HTTP 101 Switching Protocols and provides an Acp-Connection-Id.

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

```

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

### Agent Session Mode State Example

Source: https://agentclientprotocol.com/protocol/v1/session-modes

This JSON structure represents the initial state of session modes returned by an agent during session setup. It includes the currently active mode and a list of all available modes with their descriptions.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sessionId": "sess_abc123def456",
    "modes": {
      "currentModeId": "ask",
      "availableModes": [
        {
          "id": "ask",
          "name": "Ask",
          "description": "Request permission before making any changes"
        },
        {
          "id": "architect",
          "name": "Architect",
          "description": "Design and plan software systems without implementation"
        },
        {
          "id": "code",
          "name": "Code",
          "description": "Write and modify code with full tool access"
        }
      ]
    }
  }
}
```

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

### Agent Task and Message Routing Example

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

Illustrates how agent tasks are spawned per connection and how server-to-client messages are routed to either connection-scoped or session-scoped GET streams based on the sessionId field in JSON-RPC messages.

```javascript
_jsx(_components.span, {
 children: "Session {"
 })
 }), "\n", _jsx(_components.span, {
 className: "line",
 children: _jsx(_components.span, {
 children: " session_id: String, // sessionId (JSON-RPC field)"
 })
 }), "\n", _jsx(_components.span, {
 className: "line",
 children: _jsx(_components.span, {
 children: " get_stream: Option<SseStream>, // Session-scoped GET stream"
 })
 }), "\n", _jsx(_components.span, {
 className: "line",
 children: _jsx(_components.span, {
 children: " // session-specific state"
 })
 }), "\n", _jsx(_components.span, {
 className: "line",
 children: _jsx(_components.span, {
 children: "}"
 })
 }), "\n", _jsx(_components.span, {
 className: "line",
 children: _jsx(_components.span, {})
 })]
 })
 }), "\n", _jsxs(_components.p, {
 children: ["The agent task is spawned once per connection. Server→client messages are routed to either the connection-scoped GET stream or the appropriate session-scoped GET stream based on whether the message is tied to a specific session. Sessions are identified by the ", _jsx(_components.code, {
 children: "sessionId"
 }), " field in JSON-RPC messages. " ]
 })

```

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

### Starting a Session with Rust SDK

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

Demonstrates how to start a session and obtain an `ActiveSession` handle directly. This is useful for blocking behavior without using `run_until`.

```rust
let mut session = cx.start_session()

```

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

### Initialization Methods

Source: https://agentclientprotocol.com/llms-full.txt

Methods for initializing the Conductor and its proxies. Both use the same parameters and expect the same response.

```APIDOC
## proxy/initialize

### Description
Initializes a proxy component within the Conductor. This method is used when the Conductor knows it has a successor.

### Method
POST (implied by JSON-RPC)

### Endpoint
`/proxy/initialize`

### Parameters
#### Request Body
- **params** (<INITIALIZE_REQUEST_PARAMS>) - Required - Initialization parameters for the proxy.

### Response
#### Success Response (200)
- **InitializeResponse** - Standard ACP InitializeResponse.

## initialize

### Description
Initializes the agent using the standard ACP. This is typically called by the Conductor for the final agent in a chain.

### Method
POST (implied by JSON-RPC)

### Endpoint
`/initialize`

### Parameters
#### Request Body
- **params** (<INITIALIZE_REQUEST_PARAMS>) - Required - Initialization parameters for the agent.

### Response
#### Success Response (200)
- **InitializeResponse** - Standard ACP InitializeResponse.
```

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

### Initialization of a 4-Component Proxy Chain

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

Illustrates the initialization flow for a proxy chain starting from a Terminal Client to a Terminal Agent, involving Conductor and multiple proxy layers. This sequence diagram is non-normative and serves as an implementation guide.

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

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

### initialize

Source: https://agentclientprotocol.com/llms-full.txt

Negotiate versions and exchange capabilities to establish a connection with the agent.

```APIDOC
## initialize

### Description
Negotiate versions and exchange capabilities to establish a connection with the agent.

### Method
Client → Agent

### Endpoint
initialize

### Parameters
None explicitly documented.

### Response
None explicitly documented.
```

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

### SessionUpdate Example

Source: https://agentclientprotocol.com/rfds/session-info-update

An example of a SessionUpdate object, demonstrating the structure for updating session details.

```json
{
  "updatedAt": "2023-10-26T10:00:00Z",
  "description": "User session activity",
  "type": "session"
}
```

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

### Example Session Configuration

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

Illustrates a typical session configuration structure, defining prompt types, model options, and provider groupings. This format is used for setting up interactive AI sessions.

```json
{
  "ask": "What is the weather today?",
  "type": "select",
  "options": [
    {
      "group": "Provider A",
      "options": [
        {
          "value": "model-1",
          "name": "Model 1",
          "description": "The fastest model"
        }
      ]
    }
  ]
}
```

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

### initialize

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

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. The agent should respond with its supported protocol version and capabilities.

```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, exchange capability information, and determine available authentication methods. The agent should respond with its supported protocol version and capabilities.

See protocol docs: https://agentclientprotocol.com/protocol/v1/draft/initialization

### Method
(Not explicitly specified, assumed to be part of an RPC or SDK interface)

### Endpoint
(Not applicable for RPC/SDK)

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

See protocol docs: https://agentclientprotocol.com/protocol/v1/draft/initialization

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

### Request Example
(Not provided in source)

### Response
#### Success Response (200)
(Response details not explicitly provided for the `initialize` method itself, but related to `InitializeRequest` properties)

#### Response Example
(Not provided in source)
```

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

### Agent Idle Response Example

Source: https://agentclientprotocol.com/rfds/v2/prompt

Example of an agent response indicating it is idle, with optional data.

```json
{
  "jsonrpc": "2.0",
  "method": "state"
}
```

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

### Response Field Schema Example

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

Example of defining a response field with nested properties and descriptions.

```javascript
children: \
```

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

### Agent Initialization Response Example (Version Match)

Source: https://agentclientprotocol.com/protocol/v1/initialization

An agent's successful response to an initialize request, indicating it supports the client's protocol version and listing its own capabilities.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": 1,
    "capabilities": {
      "textDocumentSync": 1,
      "completionProvider": {
        "resolveProvider": true
      }
    }
  }
}
```

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

### String Schema Example

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

Example of a JSON schema for a string type. Used for text values.

```json
{
 "type": "string",
 "title": "Display Name",
 "description": "Description text",
 "default": ""
}
```