Documentation Index

Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt Use this file to discover all available pages before exploring further.

Session List

Discovering existing sessions

The session/list method allows Clients to discover sessions known to an Agent. Clients can use this to display session history and switch between sessions.

Agents can also push session metadata updates to Clients in real-time via the session_info_update notification, keeping session titles and metadata in sync without polling.

Before listing sessions, Clients MUST first complete the initialization phase. Agents that support the session method surface MUST support session/list.

sequenceDiagram
    participant Client
    participant Agent

    Note over Agent,Client: Initialized

    Client->>Agent: session/list
    Agent-->>Client: session/list response (sessions)

    alt User selects a session
        Client->>Agent: session/resume (sessionId, replayFrom)
        Note over Agent,Client: Replay conversation history...
        Agent-->>Client: session/resume response
    end

    Note over Client,Agent: Ready for prompts

Agents that also advertise session.additionalDirectories may include additionalDirectories in returned SessionInfo objects to report additional workspace roots for listed sessions.

<Note> If the Agent advertises the session.delete capability, Clients can remove sessions from future session/list results with session/delete.

Listing Sessions

Clients discover existing sessions by calling the session/list method with optional filtering and pagination parameters:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/list",
  "params": {
    "cwd": "/home/user/project",
    "cursor": "eyJwYWdlIjogMn0="
  }
}

All parameters are optional. A request with an empty params object returns the first page of sessions.

The Agent MUST respond with a list of sessions and optional pagination metadata:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "sessions": [
      {
        "sessionId": "sess_abc123def456",
        "cwd": "/home/user/project",
        "title": "Implement session list API",
        "updatedAt": "2025-10-29T14:22:15Z",
        "_meta": {
          "messageCount": 12,
          "hasErrors": false
        }
      },
      {
        "sessionId": "sess_xyz789ghi012",
        "cwd": "/home/user/another-project",
        "title": "Debug authentication flow",
        "updatedAt": "2025-10-28T16:45:30Z"
      },
      {
        "sessionId": "sess_uvw345rst678",
        "cwd": "/home/user/project",
        "updatedAt": "2025-10-27T15:30:00Z"
      }
    ],
    "nextCursor": "eyJwYWdlIjogM30="
  }
}

<ResponseField name="cwd" type="string" required>
  Working directory for the session. Always an absolute path.
</ResponseField>

<ResponseField name="additionalDirectories" type="string[]">
  If the Agent advertises `session.additionalDirectories`, it
  MAY include this field to report the complete ordered additional-root list
  associated with the listed session. Omitted and empty values are
  equivalent: this `SessionInfo` response reports no additional roots.
  Clients MUST NOT merge this field with prior values or infer additional
  roots from agent-specific state.
</ResponseField>

<ResponseField name="title" type="string">
  Human-readable title for the session. May be auto-generated from the first prompt.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  RFC 3339 timestamp of the last activity in the session.
</ResponseField>

<ResponseField name="_meta" type="object">
  Agent-specific metadata. See [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility).
</ResponseField>

When no sessions match the criteria, the Agent MUST return an empty sessions array.

Pagination

session/list uses cursor-based pagination. The request includes an optional cursor, and the response includes nextCursor when more results are available.

• Clients MUST treat a missing nextCursor as the end of results
• Clients MUST treat cursors as opaque tokens — do not parse, modify, or persist them
• Agents SHOULD return an error if the cursor is invalid
• Agents SHOULD enforce reasonable page sizes internally

Updating Session Metadata

Agents can update session metadata in real-time by sending a session_info_update notification via session/update. This follows the same pattern as other session notifications like available_commands_update and config_option_update.

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "session_info_update",
      "title": "Implement user authentication",
      "_meta": {
        "tags": ["feature", "auth"],
        "priority": "high"
      }
    }
  }
}

All fields are optional. Only include fields that have changed; omitted fields are left unchanged. Set a nullable field to null to clear it.

The sessionId, cwd, and additionalDirectories fields are not included in the update. sessionId is already in the notification’s params, cwd is immutable after session setup, and ACP does not currently define mid-session mutation for additionalDirectories. Agents typically send this notification after the first meaningful exchange to auto-generate a title.

Interaction with Other Session Methods

session/list is a discovery mechanism only — it does not restore or modify sessions:

1. Client calls session/list to discover available sessions
2. User selects a session from the list
3. Client calls session/resume with the chosen sessionId to resume the conversation, optionally setting replayFrom to request history replay

Last updated Oct 08, 2026