Elicitation

Elicitation lets an Agent ask a user for structured information through the Client. It is based on the locked MCP 2026-07-28 release-candidate elicitation specification and supports two modes:

Form mode collects non-sensitive data using a restricted JSON Schema.
URL mode opens an out-of-band interaction for sensitive or externally hosted workflows such as OAuth.

User interaction requirements

Clients MUST clearly identify the Agent requesting information, respect user privacy, and provide clear decline and cancel controls. For form mode, Clients MUST let users review and modify responses before sending them. For URL mode, Clients MUST display the target host and obtain consent before navigating to it. Clients SHOULD present the request’s message so users understand what is requested and why.

Checking support

Clients advertise elicitation support in capabilities.elicitation during initialization.

{
  "capabilities": {
    "elicitation": {
      "form": {},
      "url": {}
    }
  }
}

Capability objects have the following semantics:

An omitted or null top-level elicitation field means elicitation is unsupported.
Form support exists only when form is explicitly present and non-null. URL support exists only when url is explicitly present and non-null.
An omitted or null mode field means that mode is not advertised.
A present capability object may advertise zero, one, or both modes. {} and {"form":null,"url":null} advertise no supported modes.

This deliberately differs from the MCP 2026-07-28 release candidate, where an empty elicitation capability retains the original form-only meaning. ACP requires each supported mode to be explicit. Agents MUST NOT request a mode the Client has not advertised. Agents SHOULD provide a graceful fallback when the required mode is unavailable.

Creating an elicitation

The Agent sends an elicitation/create request directly over the ACP connection. This adapts the MCP 2026-07-28 data model. ACP also requires mode explicitly; it does not apply MCP’s omitted-mode form default. Scope is represented with flattened fields:

sessionId for a session-scoped request. It can also include toolCallId to associate the request with a tool call in that session.
requestId for a request-scoped interaction outside a session.

Agents MUST bind each elicitation and related state to the receiving Client connection and, when authentication exists, the verified user identity. A sessionId alone or an unverified Client-provided identity is not sufficient.

Foreground State

A session-scoped elicitation follows the aggregate foreground-state contract. When foreground work cannot progress without user action, the Agent SHOULD report requires_action. Once reported, it MUST report running when progress resumes, or idle if the work ends without resuming. An elicitation does not by itself start foreground work. Requests for independent background activity can be presented while the session remains idle. Request-scoped elicitations outside a session do not change any session’s foreground state. Multiple outstanding requests are tracked individually, but their creation and responses do not each cause state updates. The Agent remains running while other foreground work can progress, and remains requires_action while the foreground workflow is still blocked. In URL mode, accept only means consent to open the URL. If foreground work still needs the user to finish the external interaction, a reported requires_action remains unchanged. The Agent reports running when foreground progress actually resumes. elicitation/complete is not itself a state update.

Form mode

{
  "jsonrpc": "2.0",
  "id": 43,
  "method": "elicitation/create",
  "params": {
    "sessionId": "sess_abc123",
    "mode": "form",
    "message": "How should I approach this refactoring?",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "strategy": {
          "type": "string",
          "enum": ["conservative", "balanced", "aggressive"]
        }
      },
      "required": ["strategy"]
    }
  }
}

Form schemas are flat objects whose properties use the supported primitive and enum schemas. Clients SHOULD validate submitted values before responding, and Agents SHOULD validate them again. Clients that support schema defaults SHOULD pre-populate form fields with their declared default values. Form mode MUST NOT be used to request secrets or credentials that grant access or authorize transactions, such as passwords, API keys, access or refresh tokens, private keys, recovery codes, or payment credentials. Ordinary profile information such as a name, email address, or username is not categorically prohibited. Agents MUST use URL mode for sensitive interactions. If the Client does not support URL mode, the Agent MUST NOT fall back to form mode; it must use another safe flow or fail the operation.

URL mode

{
  "jsonrpc": "2.0",
  "id": 44,
  "method": "elicitation/create",
  "params": {
    "requestId": 12,
    "mode": "url",
    "elicitationId": "github-oauth-001",
    "url": "https://agent.example.com/connect?elicitationId=github-oauth-001",
    "message": "Please authorize access to your repositories."
  }
}

An accept response means the user consented to open the URL. It does not mean the external interaction completed. URL mode is not a substitute for authorizing the Client’s access to the Agent. Agents MUST NOT send credentials or tokens obtained through URL mode back over ACP or place them in Client or model context.

Responses

The Client responds with one of three actions:

accept: the user submitted or consented to the interaction.
decline: the user explicitly declined.
cancel: the user dismissed the interaction without choosing.

The content field is optional on accept; receivers treat omission and null equivalently. It is only meaningful for accept; receivers ignore it for decline and cancel. For an accepted form elicitation, content SHOULD conform to the requested schema. For an accepted URL elicitation, clients normally omit content because the interaction happens out of band. Agents MUST NOT assume an elicitation succeeds. They MUST handle decline, cancel, and failures by safely falling back, retrying, or failing the originating operation as appropriate.

URL completion

Unlike MCP 2026-07-28, ACP retains an elicitationId and completion notification for its direct request flow. The Agent MUST keep each elicitationId unique among outstanding URL elicitations on that Agent-Client connection, and the Client MUST treat it as opaque. The Agent MAY send elicitation/complete after the external interaction finishes. It MUST send that notification only to the same Client that received the original request and include the original elicitationId. Clients MUST ignore unknown or already-completed IDs. Requests using a mode the Client has not advertised produce JSON-RPC -32602 (Invalid params).

Session Cancellation

session/cancel does not automatically cancel every elicitation scoped to the session. sessionId and toolCallId identify context, not a cancellation instruction. When cancelling work makes a pending elicitation no longer relevant, the Agent SHOULD cancel that individual request using $/cancel_request. An elicitation can depend on the affected work with or without a toolCallId. Clients handle individual cancellation using the existing request-cancellation rules rather than infer it from session scope. Request-scoped elicitations outside the session are unaffected by session/cancel. Clients SHOULD dismiss interaction UI they know is no longer relevant. An accepted URL interaction may continue externally after its create request has returned. Cancelling foreground work does not guarantee that an external browser page closes or undo external side effects. A repeated or resume idle snapshot carrying a previous cancelled stop reason does not cancel a current interaction. A response or external completion can race with cancellation. After foreground cancellation completes, the Agent SHOULD NOT use late responses or external completions to resume the cancelled work. An external URL workflow may still complete independently. Cancellation can finish without waiting for it.

URL security

Agents and Clients implementing URL mode MUST follow these requirements: These requirements adapt MCP’s Safe URL Handling rules to ACP.

Agents MUST NOT put credentials, personal data, or pre-authenticated access in the URL and SHOULD use HTTPS outside development.
Agents SHOULD NOT include URLs intended to be clickable in any field of a form-mode request.
Clients MUST NOT prefetch the URL or open it without explicit user consent. They MUST show the full URL before asking for consent.
Clients MUST open the URL in a secure context that prevents the Client or Agent’s language model from inspecting the page or user input.
Clients SHOULD highlight the domain and warn about suspicious or ambiguous URLs, including Punycode domains.
Clients SHOULD NOT render a URL as clickable in any elicitation field except the url field of a URL-mode request, subject to the restrictions above.
The Agent MUST verify that the authenticated user who started the elicitation is the same user who completes the external interaction.

See the schema reference for the complete request and response types.

Get Started

Protocol

Libraries

User interaction requirements

Checking support

Creating an elicitation

Foreground State

Form mode

URL mode

Responses

URL completion

Session Cancellation

URL security

​User interaction requirements

​Checking support

​Creating an elicitation

​Foreground State

​Form mode

​URL mode

​Responses

​URL completion

​Session Cancellation

​URL security

User interaction requirements

Checking support

Creating an elicitation

Foreground State

Form mode

URL mode

Responses

URL completion

Session Cancellation

URL security