Skip to main content
Sessions represent a specific conversation or thread between the Client and Agent. Each session has its own context, conversation history, and state, so one Agent can run several independent sessions. Before creating a session, Clients MUST first complete the initialization phase to establish protocol compatibility and capabilities. If the Agent requires authentication, session/new may fail with an auth_required error until the Client completes the authentication flow.

Creating a session

Clients create a new session by calling the session/new method with:
The Agent MUST respond with a unique Session ID that identifies this conversation:

Loading sessions

Agents that support the loadSession capability allow Clients to resume previous conversations with history replay. This feature enables persistence across restarts and sharing sessions between different Client instances.

Checking support

Before attempting to load a session, Clients MUST verify that the Agent supports this capability by checking the loadSession field in the initialize response:
If loadSession is false or not present, the Agent does not support loading sessions and Clients MUST NOT attempt to call session/load.

Loading a session

To load an existing session, Clients MUST call the session/load method with:
The Agent MUST replay the entire conversation to the Client in the form of session/update notifications (like session/prompt). Session compactions are replayed using the same update, chunk, and patch semantics as live delivery. The Client’s session.compaction capability is required for replay as well as live delivery. Live-only notices are not conversation history and SHOULD NOT be replayed. If the underlying condition is still relevant after loading finishes, the Agent may emit a new notice as a new live event, subject to the Client’s session.notices capability. Prompt suggestions are not conversation history and SHOULD NOT be replayed. A loaded session starts with an empty list of suggestions. After loading finishes, the Agent may send a new prompt_suggestions_update, subject to the Client’s session.promptSuggestions capability. Unstable session cursors are part of the replayed history, subject to the Client’s session.cursors capability:
  • The Agent SHOULD send a cursor_update for each cursor in the loaded history that it still accepts. A replayed update carries the cursor’s capabilities and anchor, like a first update, and follows the replayed entity it is anchored to.
  • Agents SHOULD use the same cursorId for the same position in every load.
  • A load rebuilds the session’s cursors. The Client SHOULD discard the cursors it held for the session and build them again from the replayed cursor_update notifications.
  • Message IDs need not stay the same across a load, so the Client does not match a replayed anchor to an entity it held before.
For example, a user message from the conversation history:
Followed by the agent’s response:
If the Agent provides message IDs during replay, each messageId is an opaque, unique identifier for the replayed message. When all the conversation entries have been streamed to the Client, the Agent MUST respond to the original session/load request.
The response MAY also include initial mode, model, or session configuration state when those features are supported by the Agent. The Client can then continue sending prompts as if the session was never interrupted.

Resuming sessions

Agents that advertise sessionCapabilities.resume allow Clients to reconnect to an existing session without replaying the conversation history.

Checking support

Before attempting to resume a session, Clients MUST verify that the Agent supports this capability by checking for the sessionCapabilities.resume field in the initialize response:
If sessionCapabilities.resume is not present, the Agent does not support resuming sessions and Clients MUST NOT attempt to call session/resume.

Resuming a session

To resume an existing session without replaying prior messages, Clients MUST call the session/resume method with:
Unlike session/load, the Agent MUST NOT replay the conversation history via session/update notifications before responding. Instead, it restores the session context, reconnects to the requested MCP servers, and returns once the session is ready to continue.
The response MAY also include initial mode, model, or session configuration state when those features are supported by the Agent.

Closing active sessions

Agents that advertise sessionCapabilities.close allow Clients to tell the Agent to cancel any ongoing work for a session and free any resources associated with that active session.

Checking support

Before attempting to close a session, Clients MUST verify that the Agent supports this capability by checking the sessionCapabilities.close field in the initialize response:
If sessionCapabilities.close is not present, the Agent does not support closing sessions and Clients MUST NOT attempt to call session/close.

Closing a session

To close an active session, Clients MUST call the session/close method with the session ID:
SessionId
required
The ID of the active session to close.
The Agent MUST cancel any ongoing work for that session as if session/cancel had been called, then free the resources associated with the session. On success, the Agent responds with an empty result object:
Closing is idempotent. If the session does not exist or is not active, for example because it was already closed, the Agent SHOULD respond with the same empty result. Clients SHOULD treat a -32002 response to session/close as a successful close. See Unknown Sessions.

Additional workspace roots

Agents that advertise sessionCapabilities.additionalDirectories allow Clients to include additionalDirectories on supported session lifecycle requests to expand the session’s effective filesystem root set. Supported stable lifecycle requests include session/new, session/load, and session/resume.
When present, additionalDirectories has the following behavior:
  • cwd remains the primary working directory and the base for relative paths
  • each additionalDirectories entry MUST be an absolute path
  • omitting the field or providing an empty array activates no additional roots for the resulting session
  • on session/load and session/resume, Clients must send the full intended additional-root list again. That list may differ from any previous or reported list as long as the request cwd matches the session’s cwd, and omitting the field or providing an empty array does not restore stored roots implicitly
Clients MUST only send additionalDirectories when the Agent advertises sessionCapabilities.additionalDirectories.

System prompt

Agents that advertise sessionCapabilities.systemPrompt allow Clients to include system-level instructions on session/new, session/load, session/resume, and, when the Agent supports it, session/fork.
systemPrompt has the following behavior:
  • mode is required and selects how the Agent combines content with its own instructions
  • mode values beginning with _ are reserved for implementation-specific modes, and other unknown values for future ACP modes. Clients MUST only use a mode the Agent advertised. An Agent that receives a mode it does not support MUST return an error rather than treating it as append or override
  • append adds content to the Agent’s own instructions rather than replacing them. The Agent SHOULD give it system-level precedence, for example in the model’s system prompt or developer instructions rather than in user-turn content. Where it is placed and how it is formatted is up to the Agent
  • override replaces the Agent’s built-in default instructions. It does not change tool availability, MCP servers, permissions, or session configuration. Context the Agent supplies from the workspace or environment, such as AGENTS.md files or skill listings, MAY still be included, and Agents SHOULD document what they keep. Clients that use override take responsibility for any tool guidance or safety instructions the Agent’s default instructions provided
  • only text content blocks are supported for now: Agents MUST accept them, and Clients MUST NOT send other content block types until a future capability allows them
  • Clients MUST NOT send an empty content array. Agents MAY reject one with -32602 without creating, loading, resuming, or forking the session
  • omitting the field or setting it to null on session/new means the Agent uses its default instructions
  • on session/load, session/resume, and session/fork, Clients SHOULD send the same systemPrompt they used when the session was created. When it is omitted, the Agent may keep a prompt it stored with the session or use its default. When it differs, the Agent SHOULD apply it, and MAY defer the change until it next rebuilds its prompt (for example, after compaction) when applying it immediately would discard prompt caches or preserved reasoning
  • if the Agent cannot apply a supplied systemPrompt, for example because of an unadvertised mode, an unsupported content block type, or content that exceeds its limits, it MUST return an error and MUST NOT create, load, resume, or fork the session. JSON-RPC -32602 (Invalid params) is the RECOMMENDED error for malformed or unsupported values
Clients MUST only send systemPrompt when the Agent advertises sessionCapabilities.systemPrompt, and MUST only use override mode when the Agent also advertises sessionCapabilities.systemPrompt.mode.override:
Content delivered at system level carries more weight with the model than user turns or tool output. Clients SHOULD only send content they trust at that level.

Initial config option values (unstable)

Agents that advertise sessionCapabilities.options accept a configOptions list on session/new, session/load, session/resume, and, when supported, session/fork. The Agent applies the entries in order, as if the Client had called session/set_config_option for each one after setup, and returns the resulting values in the response. Clients can get the options and allowed values before setup with session/options. See Options before a session exists.

Session ID

The session ID returned by session/new is a unique identifier for the conversation context. Clients use this ID to:
  • Send prompt requests via session/prompt
  • Cancel ongoing operations via session/cancel
  • Load previous sessions via session/load (if the Agent supports the loadSession capability)
  • Resume previous sessions via session/resume (if the Agent supports the sessionCapabilities.resume capability)
  • Close active sessions via session/close (if the Agent supports the sessionCapabilities.close capability)

Working directory

The cwd (current working directory) parameter establishes the primary file system context for the session. This directory:
  • MUST be an absolute path
  • MUST be used for the session regardless of where the Agent subprocess was spawned
  • MUST remain the base for relative-path resolution
  • MUST be part of the session’s effective root set
When sessionCapabilities.additionalDirectories is in use, the session’s effective root set is [cwd, ...additionalDirectories]. This root set SHOULD serve as a boundary for tool operations on the file system.

Workspace root security

The root set declares the session’s scope. It confines shell commands only when a sandbox enforces it.
  • Clients SHOULD only include directories the user expects the Agent to access, such as the workspace or directories the Client provides, like skills.
  • Agents SHOULD NOT treat model output, Agent content, or replayed history as granting access outside the root set. Access outside it goes through a permission request.
  • Implementations that enforce the root set SHOULD check the resolved path at the time of use, compare paths by component, and fail closed.

MCP servers

The Model Context Protocol (MCP) allows Agents to access external tools and data sources. When creating a session, Clients MAY include connection details for MCP servers that the Agent should connect to. MCP servers can be connected to using different transports. All Agents MUST support the stdio transport, while HTTP and SSE transports are optional capabilities that can be checked during initialization. While they are not required to by the spec, new Agents SHOULD support the HTTP transport to ensure compatibility with modern MCP servers.

Transport types

Stdio transport

All Agents MUST support connecting to MCP servers via stdio (standard input/output). This is the default transport mechanism.
string
required
A human-readable identifier for the server
string
required
The absolute path to the MCP server executable
array
required
Command-line arguments to pass to the server
EnvVariable[]
Environment variables to set when launching the server
Example stdio transport configuration:

HTTP transport

When the Agent supports mcpCapabilities.http, Clients can specify MCP servers configurations using the HTTP transport.
string
required
Must be "http" to indicate HTTP transport
string
required
A human-readable identifier for the server
string
required
The URL of the MCP server
HttpHeader[]
required
HTTP headers to include in requests to the server
Example HTTP transport configuration:

SSE transport

When the Agent supports mcpCapabilities.sse, Clients can specify MCP servers configurations using the SSE transport.
This transport was deprecated by the MCP spec.
string
required
Must be "sse" to indicate SSE transport
string
required
A human-readable identifier for the server
string
required
The URL of the SSE endpoint
HttpHeader[]
required
HTTP headers to include when establishing the SSE connection
Example SSE transport configuration:

Checking transport support

Before using HTTP or SSE transports, Clients MUST verify the Agent’s capabilities during initialization:
If mcpCapabilities.http is false or not present, the Agent does not support HTTP transport. If mcpCapabilities.sse is false or not present, the Agent does not support SSE transport. Agents SHOULD connect to all MCP servers specified by the Client. Clients MAY use this ability to provide tools directly to the underlying language model by including their own MCP server.

Security

MCP server configurations can launch processes, and their env and headers values are credentials.
  • Agents SHOULD launch command with args as separate arguments, without a shell.
  • Clients SHOULD NOT send a stdio server from workspace files or Agent output until the user has approved its exact command, arguments, and environment variable names.
  • Agents SHOULD NOT include env or headers values in session updates, errors, _meta, session/list results, replayed history, model context, or command lines, and SHOULD NOT log or persist them.
  • Agents SHOULD send headers only to the configured origin.
  • Clients that persist mcpServers SHOULD keep credentials in operating-system secret storage and SHOULD NOT log them.