Java API Reference - Pollack AI Lab

Complete API reference for the ACP Java SDK, covering client, agent (all three styles), protocol types, transports, errors, and test utilities.

Installation

Maven (0.80.0 — stable)

Core SDK (client + sync/async agent APIs). From 0.18.0, acp-core contains no JSON implementation; add one JSON module next to it:

<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-core</artifactId>
    <version>0.80.0</version>
</dependency>
<!-- Jackson 2 (com.fasterxml.jackson.databind) -->
<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-json-jackson2</artifactId>
    <version>0.80.0</version>
</dependency>

Or, for Jackson 3 (tools.jackson.databind, for example alongside Spring Boot 4), use acp-json-jackson3 in place of acp-json-jackson2. Without either, AcpJsonMapper.createDefault() fails with No AcpJsonMapperSupplier found on the classpath. AcpJsonMapper.createDefault() picks the supplier with the highest AcpJsonMapperSupplier.priority(): with both modules present Jackson 3 wins, and an application’s own supplier wins over both. The system property acp.json.mapper.supplier names a supplier class explicitly. Annotation-based agent support (includes acp-core and acp-json-jackson2 transitively):

<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-agent-support</artifactId>
    <version>0.80.0</version>
</dependency>

Test utilities:

<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-test</artifactId>
    <version>0.80.0</version>
    <scope>test</scope>
</dependency>

Streamable HTTP and WebSocket server transport for remote agents:

<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-streamable-http-jetty</artifactId>
    <version>0.80.0</version>
</dependency>

acp-websocket-jetty (single-client WebSocketAcpAgentTransport) was deprecated for removal in 0.18.0 and is removed in 0.80.0; use acp-streamable-http-jetty. See the 0.80.0 migration guide.

Gradle

// build.gradle
implementation 'com.agentclientprotocol:acp-core:0.80.0'
implementation 'com.agentclientprotocol:acp-json-jackson2:0.80.0' // or acp-json-jackson3

// Optional modules
implementation 'com.agentclientprotocol:acp-agent-support:0.80.0'
implementation 'com.agentclientprotocol:acp-streamable-http-jetty:0.80.0'
testImplementation 'com.agentclientprotocol:acp-test:0.80.0'

// build.gradle.kts
implementation("com.agentclientprotocol:acp-core:0.80.0")
implementation("com.agentclientprotocol:acp-json-jackson2:0.80.0") // or acp-json-jackson3

// Optional modules
implementation("com.agentclientprotocol:acp-agent-support:0.80.0")
implementation("com.agentclientprotocol:acp-streamable-http-jetty:0.80.0")
testImplementation("com.agentclientprotocol:acp-test:0.80.0")

Snapshot (0.81.0-SNAPSHOT)

For unreleased features, add the snapshot repository and use the snapshot version:

<repositories>
    <repository>
        <id>central-snapshots</id>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        <snapshots><enabled>true</enabled></snapshots>
        <releases><enabled>false</enabled></releases>
    </repository>
</repositories>

Then use 0.81.0-SNAPSHOT in place of 0.80.0 in your dependencies.

Three Agent API Styles

Quick Comparison

Feature	Annotation-based	Sync	Async
Entry Point	`@AcpAgent` class	`AcpAgent.sync()`	`AcpAgent.async()`
Handler Style	Annotated methods	Lambda callbacks	Lambda callbacks returning `Mono`
Return Values	Auto-converted (`String` → `PromptResponse`)	Direct protocol types	`Mono<ProtocolType>`
Boilerplate	Lowest	Moderate	Moderate
Best For	Most applications	Simple blocking handlers	Reactive applications
Runtime	`AcpAgentSupport`	`AcpSyncAgent`	`AcpAsyncAgent`

All three produce identical protocol behavior and support the same capabilities.

When to Use Each

Annotation-based — default choice. Least boilerplate, auto-converts return types, supports interceptors and custom argument resolvers.
Sync — when you want explicit control over every handler without annotations. Blocking void methods for sending updates.
Async — when your agent needs non-blocking I/O. Uses Project Reactor Mono for composable async chains.

Client API

`AcpClient` — Factory

Method	Return Type	Description
`sync(transport)`	`AcpSyncClient.Builder`	Create blocking client builder
`async(transport)`	`AcpAsyncClient.Builder`	Create reactive client builder

`AcpSyncClient` — Blocking Client

Method	Return Type	Description
`initialize()`	`InitializeResponse`	Protocol handshake with defaults
`initialize(request)`	`InitializeResponse`	Handshake with custom capabilities
`authenticate(request)`	`AuthenticateResponse`	Authenticate with a method ID
`logout(request)`	`LogoutResponse`	Clear stored credentials (0.14.0)
`newSession(request)`	`NewSessionResponse`	Create a new session
`loadSession(request)`	`LoadSessionResponse`	Resume an existing session (replays history)
`listSessions(request)`	`ListSessionsResponse`	List sessions, optional cwd filter (0.12.0)
`resumeSession(request)`	`ResumeSessionResponse`	Reconnect to session without history replay (0.12.0)
`closeSession(request)`	`CloseSessionResponse`	Close session and free resources (0.12.0)
`deleteSession(request)`	`DeleteSessionResponse`	Permanently delete a stored session (0.14.0)
`forkSession(request)`	`ForkSessionResponse`	Fork a session into a new branch (0.12.0, unstable)
`setSessionConfigOption(request)`	`SetSessionConfigOptionResponse`	Set a session config value (0.12.0)
`listProviders(request)`	`ListProvidersResponse`	List configurable model/backend providers (0.14.0, unstable)
`setProvider(request)`	`SetProviderResponse`	Configure a provider (protocol, base URL, headers) (0.14.0, unstable)
`disableProvider(request)`	`DisableProviderResponse`	Disable a provider by id (0.14.0, unstable)
`prompt(request)`	`PromptResponse`	Send prompt, block until response
`cancel(notification)`	`void`	Cancel current prompt (fire-and-forget)
`getAgentCapabilities()`	`NegotiatedCapabilities`	Capabilities reported by agent
`close()`	`void`	Close connection

Builder Configuration

AcpSyncClient client = AcpClient.sync(transport)
    .sessionUpdateHandler(notification -> {
        // Handle streaming updates during prompt()
    })
    .readTextFileHandler(req -> {
        // Agent requests a file read
        return new ReadTextFileResponse(Files.readString(Path.of(req.path())));
    })
    .writeTextFileHandler(req -> {
        // Agent requests a file write
        Files.writeString(Path.of(req.path()), req.content());
        return new WriteTextFileResponse();
    })
    .requestPermissionHandler(req -> {
        // Agent requests permission
        return new RequestPermissionResponse(req.options().getFirst().id());
    })
    .createElicitationHandler(req -> {
        // Agent requests structured user input (unstable)
        return CreateElicitationResponse.accept(Map.of("choice", "option-a"));
    })
    .build();

Example — Complete client lifecycle

This launches the Grok CLI as an ACP agent subprocess and sends it a prompt. AgentParameters builds the command line; StdioAcpClientTransport spawns the process and handles JSON-RPC framing over stdin/stdout.

// Launch "grok agent stdio" as a subprocess
var params = AgentParameters.builder("grok")
    .arg("agent")
    .arg("stdio")
    .build();

var transport = new StdioAcpClientTransport(params);
AcpSyncClient client = AcpClient.sync(transport)
    .sessionUpdateHandler(notification -> {
        var update = notification.update();
        if (update instanceof AgentMessageChunk msg) {
            System.out.print(((TextContent) msg.content()).text());
        }
    })
    .build();

client.initialize();
var session = client.newSession(new NewSessionRequest("/workspace", List.of()));

var response = client.prompt(new PromptRequest(
    session.sessionId(),
    List.of(new TextContent("Hello, world!"))
));

System.out.println("Stop reason: " + response.stopReason());
client.close();

Agent API — Annotation-Based

The acp-agent-support module provides a declarative programming model using annotations.

Annotations

Class-Level

Annotation	Description
`@AcpAgent`	Marks a class as an ACP agent. Optional `name` and `version` attributes.

Handler Methods

Annotation	JSON-RPC Method	Description
`@Initialize`	`initialize`	Protocol initialization and capability negotiation
`@Logout`	`logout`	Clears stored credentials (0.14.0)
`@NewSession`	`session/new`	Creates a new agent session
`@LoadSession`	`session/load`	Loads an existing session by ID (replays history)
`@ListSessions`	`session/list`	Lists sessions with optional cwd filter (0.12.0)
`@ResumeSession`	`session/resume`	Reconnects to session without history replay (0.12.0)
`@CloseSession`	`session/close`	Closes session and frees resources (0.12.0)
`@DeleteSession`	`session/delete`	Permanently deletes a stored session (0.14.0)
`@ForkSession`	`session/fork`	Forks a session into a new branch (0.12.0, unstable)
`@SetSessionConfigOption`	`session/set_config_option`	Sets a session config value (0.12.0)
`@ListProviders`	`providers/list`	Lists configurable providers (0.14.0, unstable)
`@SetProvider`	`providers/set`	Configures a provider (0.14.0, unstable)
`@DisableProvider`	`providers/disable`	Disables a provider by id (0.14.0, unstable)
`@Prompt`	`session/prompt`	Handles user prompts
`@SetSessionMode`	`session/set_mode`	Changes operational mode
`@Cancel`	`session/cancel`	Cancellation notification (fire-and-forget)
`@Authenticate`	`authenticate`	Runs an authentication attempt (0.80.0; previously unconditionally “method not found”)
`@ExtRequest("_name")`	a custom `_`-prefixed method	Handles an extension request (0.80.0)
`@ExtNotification("_name")`	a custom `_`-prefixed method	Handles an extension notification (0.80.0)

Removed in 0.80.0: the session-model API. session/set_model and the related types (@SetSessionModel, SetSessionModelRequestResolver, SetSessionModelRequest/Response, SessionModelState, ModelInfo, and the models field on session responses) were deprecated for removal in 0.14.0 and are gone in 0.80.0. An agent built on 0.80.0 no longer answers session/set_model; a peer that sends it gets “method not found”. Expose model selection through session/set_config_option instead: advertise a select config option whose category is "model", and switch models with setSessionConfigOption(...). This is the same mechanism used for session modes (category: "mode") and reasoning level (category: "thought_level"). See the 0.80.0 migration guide.

Parameter Annotations

Annotation	Description
`@SessionId`	Injects the current session ID as `String`

Connection-Level Parameters (0.80.0)

Any handler method, not only @Prompt, may also declare a parameter of type AcpSyncAgent/ AcpAsyncAgent (the connection’s own agent facade, to call back into the client) or NegotiatedCapabilities (what the connected client advertised). Resolution is by parameter type, so order and presence are both optional:

@NewSession
NewSessionResponse newSession(NewSessionRequest req, NegotiatedCapabilities caps) {
    boolean canElicit = caps.supportsElicitation();
    // ...
}

@ExtRequest("_example/status")
StatusResult status(AcpSyncAgent agent, NegotiatedCapabilities caps) { ... }

Previously, a handler needing to call back into the client had to capture the agent from an enclosing scope; as of 0.80.0 it’s an ordinary parameter like any other.

Flexible Method Signatures

Handler methods support flexible parameter resolution:

// Minimal
@Initialize
InitializeResponse init() { return InitializeResponse.ok(); }

// With request
@Prompt
PromptResponse answer(PromptRequest req) { ... }

// With context
@Prompt
PromptResponse answer(PromptRequest req, SyncPromptContext ctx) { ... }

// Auto-converted return types
@Prompt
String simpleAnswer(PromptRequest req) { ... }  // sent as an agent message chunk, then endTurn()

@Prompt
void streaming(PromptRequest req, SyncPromptContext ctx) { ... }  // → endTurn()

Return Value Handling

Return Type	Conversion
Protocol response type	Passed through directly
`String`	Sent to the client as an agent message chunk, then `PromptResponse.endTurn()`; `null`/empty sends nothing
`void`	Converted to `PromptResponse.endTurn()`
`Mono`/`CompletionStage`/single-value `Publisher`	Awaited on the handler’s thread, then handled as its value means

`SyncPromptContext`

Available in @Prompt handlers. Provides blocking methods for agent-client interaction:

@Prompt
PromptResponse handle(PromptRequest req, SyncPromptContext ctx) {
    // Session info
    String sessionId = ctx.getSessionId();
    NegotiatedCapabilities caps = ctx.getClientCapabilities();

    // Messages and thoughts
    ctx.sendMessage("Working on it...");
    ctx.sendThought("Let me analyze this...");

    // Tag streamed chunks with a message ID (0.14.0) — chunks sharing an id
    // form one logical message; a new id starts a new message
    ctx.sendMessage("First part...", "msg-1");
    ctx.sendThought("Reasoning...", "msg-1");

    // File operations (requires client capabilities)
    String content = ctx.readFile("/path/to/file.txt");
    ctx.writeFile("/path/to/output.txt", "content");
    Optional<String> maybe = ctx.tryReadFile("/path/to/file.txt");

    // Permissions (each announces a tool_call before asking, and settles it with a
    // tool_call_update after; askPermission(action) alone uses kind "other")
    boolean allowed = ctx.askPermission("Delete files in /tmp?");
    boolean allowedEdit = ctx.askPermission("Rewrite config.yaml", ToolKind.EDIT);
    Optional<String> choice = ctx.askChoice("Which format?", "JSON", "XML", "YAML");  // empty() if the client cancelled

    // Terminal execution (requires client capabilities)
    CommandResult result = ctx.execute("ls", "-la");

    return PromptResponse.endTurn();
}

ctx.async() (0.80.0) returns the same turn’s PromptContext (the async, Reactor-based view), for the rare case where a sync handler needs to compose one of the async-only APIs. If you implement SyncPromptContext yourself, for a test double, async() is an abstract method you must provide too; it’s not a default method.

`AcpAgentSupport` — Bootstrap

For a single stdio agent, .run() blocks until the client disconnects:

AcpAgentSupport.create(new MyAgent())
    .transport(StdioAcpAgentTransport.create())
    .requestTimeout(Duration.ofSeconds(60))   // Optional
    .interceptor(new LoggingInterceptor())     // Optional
    .argumentResolver(new UserResolver())      // Optional
    .returnValueHandler(new FutureHandler())   // Optional
    .run();  // Blocks until client disconnects

For Streamable HTTP or WebSocket, where one JVM serves many remote connections, buildFactory() (0.80.0) hands back an AcpAgentFactory instead of running one agent directly; the server creates a fresh agent per connection from it, sharing the same handler bean (which must be thread-safe) across all of them:

AcpAgentFactory agents = AcpAgentSupport.create(new MyAgent())
    .requestTimeout(Duration.ofSeconds(60))
    .buildFactory();

new StreamableHttpAcpAgentTransport(0, AcpJsonMapper.createDefault(), agents).start().block();

The builder is safely reusable across multiple buildFactory() calls, if you need more than one listener sharing the same configuration. See Transports for the full connection lifecycle.

Interceptors

Cross-cutting concerns like logging, metrics, or error handling:

public class LoggingInterceptor implements AcpInterceptor {

    @Override
    public boolean preInvoke(AcpInvocationContext context) {
        log.info("Invoking: {}", context.getAcpMethod());
        return true;  // Continue processing
    }

    @Override
    public Object postInvoke(AcpInvocationContext context, Object result) {
        log.info("Result: {}", result);
        return result;
    }

    @Override
    public int getOrder() { return 0; }  // Lower values execute first
}

Example — Complete annotation-based agent

@AcpAgent(name = "code-assistant", version = "1.0.0")
class CodeAssistant {

    private final Map<String, List<String>> sessionHistory = new ConcurrentHashMap<>();

    @Initialize
    InitializeResponse init() { return InitializeResponse.ok(); }

    @NewSession
    NewSessionResponse newSession(NewSessionRequest req) {
        String sessionId = UUID.randomUUID().toString();
        sessionHistory.put(sessionId, new ArrayList<>());
        return new NewSessionResponse(sessionId, List.of(), List.of());
    }

    @Prompt
    PromptResponse prompt(PromptRequest req, SyncPromptContext ctx) {
        ctx.sendThought("Analyzing the code...");

        if (ctx.getClientCapabilities().supportsReadTextFile()) {
            ctx.sendMessage("I can access files if needed.");
        }

        ctx.sendMessage("Here's my analysis...");
        return PromptResponse.endTurn();
    }

    @Cancel
    void onCancel(CancelNotification notification, @SessionId String sessionId) {
        sessionHistory.remove(sessionId);
    }
}

Agent API — Sync (Builder)

Blocking handlers with plain return values. No annotations.

Builder Methods

Method	Description
`initializeHandler(handler)`	Handle `initialize` requests
`authenticateHandler(handler)`	Handle `authenticate` requests
`logoutHandler(handler)`	Handle `logout` requests (0.14.0)
`newSessionHandler(handler)`	Handle `session/new` requests
`loadSessionHandler(handler)`	Handle `session/load` requests
`listSessionsHandler(handler)`	Handle `session/list` requests (0.12.0)
`resumeSessionHandler(handler)`	Handle `session/resume` requests (0.12.0)
`closeSessionHandler(handler)`	Handle `session/close` requests (0.12.0)
`deleteSessionHandler(handler)`	Handle `session/delete` requests (0.14.0)
`forkSessionHandler(handler)`	Handle `session/fork` requests (0.12.0, unstable)
`setSessionConfigOptionHandler(handler)`	Handle `session/set_config_option` requests (0.12.0)
`listProvidersHandler(handler)`	Handle `providers/list` requests (0.14.0, unstable)
`setProviderHandler(handler)`	Handle `providers/set` requests (0.14.0, unstable)
`disableProviderHandler(handler)`	Handle `providers/disable` requests (0.14.0, unstable)
`promptHandler(handler)`	Handle `session/prompt` requests
`cancelHandler(handler)`	Handle `session/cancel` notifications

Example

AcpSyncAgent agent = AcpAgent.sync(transport)
    .initializeHandler(req -> InitializeResponse.ok())

    .newSessionHandler(req ->
        new NewSessionResponse(UUID.randomUUID().toString(), null, null))

    .promptHandler((req, context) -> {
        context.sendMessage("Hello!");
        return PromptResponse.endTurn();
    })
    .build();

agent.run();  // Blocks until client disconnects

Prompt Handler Context

The context parameter in promptHandler provides:

Method	Description
`getSessionId()`	Current session ID
`sendMessage(text)`	Send `AgentMessageChunk`
`sendThought(text)`	Send `AgentThoughtChunk`
`sendSessionUpdate(update)`	Send any `SessionUpdate`, to this handler’s own session
`readFile(path, offset, limit)`	Read file from client
`writeFile(path, content)`	Write file on client
`askPermission(action)` / `askChoice(prompt, options)`	Ask client for permission, the convenience form
`client().requestPermission(request)`	Ask client for permission, the full request/response form
`getClientCapabilities()`	Check client capabilities

Agent API — Async (Builder)

Reactive handlers returning Mono. Uses Project Reactor.

Example

AcpAsyncAgent agent = AcpAgent.async(transport)
    .initializeHandler(req ->
        Mono.just(InitializeResponse.ok()))

    .newSessionHandler(req ->
        Mono.just(new NewSessionResponse(
            UUID.randomUUID().toString(), null, null)))

    .promptHandler((req, context) ->
        context.sendMessage("Hello!")
            .then(Mono.just(PromptResponse.endTurn())))
    .build();

agent.start().then(agent.awaitTermination()).block();

The async context’s sendMessage(), sendSessionUpdate(), etc. return Mono<Void>, composable with .then() and .flatMap().

Convenience Methods vs Full API

The SDK provides convenience methods that cover the most common operations. Use these by default — they produce cleaner code and handle the protocol details for you.

When convenience methods are enough (~80% of cases)

// Response factories
InitializeResponse.ok()                        // default capabilities
InitializeResponse.ok(customCapabilities)      // custom capabilities
PromptResponse.endTurn()                       // stop reason END_TURN
PromptResponse.cancelled()                     // stop reason CANCELLED

// Sending updates (on SyncPromptContext or async equivalent)
context.sendMessage("Hello");                  // AgentMessageChunk with TextContent
context.sendThought("Analyzing...");           // AgentThoughtChunk with TextContent

// File operations
String content = context.readFile("pom.xml");  // read with defaults
context.writeFile("output.txt", "content");    // write file

// Terminal
CommandResult result = context.execute("ls", "-la");

// Permissions
boolean ok = context.askPermission("Delete temp files?");
Optional<String> choice = context.askChoice("Format?", "JSON", "XML", "YAML");

When to use the full API (~20% of cases)

Drop to the full API when you need control that convenience methods don’t expose:

// Custom AgentCapabilities with specific MCP and prompt settings
var caps = AgentCapabilities.builder()
    .loadSession()
    .mcpHttp().mcpSse()
    .promptAudio().promptImage()                  // promptEmbeddedContext left off
    .build();
return InitializeResponse.ok(caps);

// Send non-text update types (Plan, ToolCall, AvailableCommandsUpdate, etc.)
// Plan's short constructor no longer takes the discriminator (0.80.0): it can
// only be the variant's own name, so writing it was noise.
context.sendSessionUpdate(new Plan(List.of(
    new PlanEntry("Analyze code", PlanEntryPriority.HIGH, PlanEntryStatus.IN_PROGRESS),
    new PlanEntry("Generate tests", PlanEntryPriority.MEDIUM, PlanEntryStatus.PENDING)
)));

context.sendSessionUpdate(new ToolCall("tool_call",
    "search-1",
    "code-search",   // title: what the user sees
    "code_search",   // name: the tool's own identifier (may be null)
    ToolKind.SEARCH, ToolCallStatus.IN_PROGRESS,
    null, null, null, null, null));

// Read file with offset and line limit
var response = context.client().readTextFile(
    new ReadTextFileRequest(sessionId, "large-file.txt", 100, 50));

// Request permission with custom options
var permResponse = context.client().requestPermission(new RequestPermissionRequest(
    sessionId, "Run deployment script?", List.of(
        new PermissionOption("allow-once", "Allow once", PermissionOptionKind.ALLOW_ONCE),
        new PermissionOption("always", "Always allow", PermissionOptionKind.ALLOW_ALWAYS),
        new PermissionOption("reject", "Reject", PermissionOptionKind.REJECT_ONCE)
    )));

// Call a custom extension method on the client, from a prompt handler (0.80.0)
context.client().sendExtRequest("_example.com/ping", params, PONG);
context.client().sendExtNotification("_example/event", event);

The convenience methods are wrappers around the full API — they call the same underlying protocol methods. You can mix and match freely within a single handler.

Protocol Types

All protocol types are defined in AcpSchema as Java records.

Request/Response Types

Type	Fields
`InitializeRequest`	`protocolVersion`, `clientCapabilities`
`InitializeResponse`	`protocolVersion`, `agentCapabilities`, `authMethods`, `agentInfo`
`AuthenticateRequest`	`methodId`
`AuthenticateResponse`	(empty)
`LogoutRequest`	(empty) (0.14.0)
`LogoutResponse`	(empty) (0.14.0)
`NewSessionRequest`	`cwd`, `mcpServers`, `additionalDirectories` (`additionalDirectories` 0.14.0)
`NewSessionResponse`	`sessionId`, `modes`, `configOptions` (`models` removed in 0.80.0; see migration guide)
`LoadSessionRequest`	`sessionId`, `cwd`, `mcpServers`, `additionalDirectories` (`additionalDirectories` 0.14.0)
`LoadSessionResponse`	`modes`, `configOptions` (`models` removed in 0.80.0)
`ListSessionsRequest`	`cwd` (optional filter), `cursor` (pagination) (0.12.0)
`ListSessionsResponse`	`sessions` (list of `SessionInfo`), `nextCursor` (0.12.0)
`ResumeSessionRequest`	`sessionId`, `cwd`, `mcpServers`, `additionalDirectories` (0.12.0; `additionalDirectories` 0.14.0)
`ResumeSessionResponse`	`modes`, `configOptions` (0.12.0; `models` removed in 0.80.0)
`CloseSessionRequest`	`sessionId` (0.12.0)
`CloseSessionResponse`	(empty) (0.12.0)
`DeleteSessionRequest`	`sessionId` (0.14.0)
`DeleteSessionResponse`	(empty) (0.14.0)
`ForkSessionRequest`	`sessionId`, `cwd`, `mcpServers`, `additionalDirectories` (0.12.0, unstable)
`ForkSessionResponse`	`sessionId`, `modes`, `configOptions` (0.12.0, unstable; `models` removed in 0.80.0)
`SetSessionConfigOptionRequest`	`sessionId`, `configId`, `value`, `type` (0.12.0)
`SetSessionConfigOptionResponse`	`configOptions` (full config state) (0.12.0)
`ListProvidersRequest`	(empty) (0.14.0, unstable)
`ListProvidersResponse`	`providers` (list of `ProviderInfo`) (0.14.0, unstable)
`SetProviderRequest`	`id`, `apiType`, `baseUrl`, `headers` (0.14.0, unstable)
`SetProviderResponse`	(empty) (0.14.0, unstable)
`DisableProviderRequest`	`id` (0.14.0, unstable)
`DisableProviderResponse`	(empty) (0.14.0, unstable)
`CreateElicitationRequest`	`sessionId`, `message`, `mode`, `requestedSchema` (0.12.0, unstable)
`CreateElicitationResponse`	`action` (accept/decline/cancel), `content` (0.12.0, unstable)
`CompleteElicitationNotification`	`elicitationId` (0.12.0, unstable)
`PromptRequest`	`sessionId`, `prompt` (list of `ContentBlock`)
`PromptResponse`	`stopReason`
`CancelNotification`	`sessionId`

Session Types (0.12.0)

Type	Fields	Description
`SessionInfo`	`sessionId`, `cwd`, `title`, `updatedAt`, `additionalDirectories`	Session metadata returned by `session/list` (`additionalDirectories` 0.14.0)
`SessionCapabilities`	`list`, `close`, `resume`, `delete`, `additionalDirectories`, `fork`	Nested capability flags on `AgentCapabilities` (`delete`, `additionalDirectories` 0.14.0; `fork` unstable)

Config Option Types (0.12.0)

session/set_config_option is stable. The select variant is the stable shape; boolean is an SDK extension.

Type	Description
`SessionConfigOption`	Polymorphic: `SessionConfigSelect` or `SessionConfigBoolean`
`SessionConfigSelect`	Select-type config with `currentValue`, `category`, and `options` list
`SessionConfigBoolean`	Boolean toggle with `currentValue` (unstable extension)
`SessionConfigSelectOption`	A named value within a select config (`value`, `name`)
`ConfigOptionUpdate`	SessionUpdate variant for agent-pushed config changes

Provider Types (0.14.0, unstable)

Model/backend routing configuration. The agent advertises support with a providers capability; the client manages providers via listProviders / setProvider / disableProvider.

Type	Description
`ProviderInfo`	A configurable provider: `id`, `supported` (protocol ids), `required`, `current`
`ProviderCurrentConfig`	Current effective routing: `apiType`, `baseUrl`
`ProvidersCapabilities`	Agent capability marker (presence = supported), on `AgentCapabilities`

apiType / supported use well-known LlmProtocol ids (anthropic, openai, azure, vertex, bedrock) or a custom string, modeled as String in the SDK.

Elicitation Types (0.12.0, unstable)

Type	Description
`ElicitationSchema`	JSON Schema describing form fields (`properties`, `required`)
`ElicitationPropertySchema`	Polymorphic: `StringPropertySchema`, `NumberPropertySchema`, `IntegerPropertySchema`, `BooleanPropertySchema`, `MultiSelectPropertySchema`
`EnumOption`	Named value for select/multi-select (`const`, `title`)
`ElicitationCapabilities`	Client capability for form and/or URL elicitation
`ElicitationAction`	Enum: `ACCEPT`, `DECLINE`, `CANCEL`

Content Types

Type	Description
`TextContent`	Text content with `text` field
`ImageContent`	Image content (base64 or URL)

Session Update Types

Type	Description
`UserMessageChunk`	Incremental user message text (optional `messageId`)
`AgentMessageChunk`	Incremental response text (optional `messageId` — 0.14.0)
`AgentThoughtChunk`	Agent thinking process (optional `messageId` — 0.14.0)
`ToolCall`	Tool execution start
`ToolCallUpdateNotification`	Tool progress update
`Plan`	Agent’s planned steps
`AvailableCommandsUpdate`	Advertised slash commands
`CurrentModeUpdate`	Agent mode change
`UsageUpdate`	Context window and cost usage
`ConfigOptionUpdate`	Session config option changes

Content chunks (UserMessageChunk, AgentMessageChunk, AgentThoughtChunk) carry an optional messageId: chunks sharing the same id belong to one logical message, and a change in id starts a new message (0.14.0).

Stop Reasons

Value	Description
`END_TURN`	Agent finished responding
`MAX_TOKENS`	Token limit reached
`REFUSAL`	Agent refused the request
`CANCELLED`	Prompt was cancelled

Convenience Methods

// Static factory methods
InitializeResponse.ok()
PromptResponse.endTurn()
PromptResponse.cancelled()

Capabilities

Client Capabilities

Advertised on the client builder, before initialize() is called. As of 0.80.0, initialize(InitializeRequest) is removed; capabilities are set only this way. See the 0.80.0 migration guide. A client built with the matching handlers (readTextFileHandler, writeTextFileHandler, the five terminal handlers) advertises these capabilities automatically as of 0.80.0; setting clientCapabilities(..) explicitly, as below, always wins over what the handlers would derive. See Client builders derive capabilities from handlers.

AcpSyncClient client = AcpClient.sync(transport)
    .clientCapabilities(ClientCapabilities.builder()
        .readTextFile().writeTextFile()
        .terminal()
        .build())
    .clientInfo(new Implementation("my-client", "1.0.0"))  // optional; name and version sent to the agent
    .build();

client.initialize();

For session, auth, and elicitation support too, add their builder calls; these aren’t derived from handlers, so set them explicitly whenever you need them:

.clientCapabilities(ClientCapabilities.builder()
    .readTextFile().writeTextFile()
    .terminal()
    .session(ClientSessionCapabilities.withBooleanConfigOptions())
    .auth(new AuthCapabilities(true))           // terminal auth
    .elicitation(ElicitationCapabilities.formAndUrl())
    .build())

The setters that take the nested records directly (.fs(new FileSystemCapability(true, true)), .terminal(true)) still work, for a capability shape the one-flag setters don’t cover. initialize(int protocolVersion, Map<String, Object> meta) is still available for the rare case of pinning a specific protocol version or attaching _meta to the handshake; plain initialize() is what nearly every client should call.

`NegotiatedCapabilities`

Check capabilities before using them:

NegotiatedCapabilities caps = context.getClientCapabilities();
if (caps.supportsReadTextFile()) {
    String content = context.readFile("file.txt");
}
if (caps.supportsWriteTextFile()) {
    context.writeFile("output.txt", "content");
}

Or use require methods that throw AcpCapabilityException if unsupported:

caps.requireWriteTextFile();
context.writeFile("output.txt", "content");

Session Capabilities (0.12.0)

Agents advertise session management support via SessionCapabilities. The NegotiatedCapabilities accessors are: supportsListSessions(), supportsCloseSession(), supportsResumeSession(), supportsDeleteSession() (0.14.0), supportsAdditionalDirectories() (0.14.0), and supportsForkSession() (unstable) — each with a matching require*() that throws AcpCapabilityException.

NegotiatedCapabilities caps = client.getAgentCapabilities();
if (caps.supportsListSessions()) {
    client.listSessions(new ListSessionsRequest(null));
}
if (caps.supportsDeleteSession()) {
    client.deleteSession(new DeleteSessionRequest(sessionId));
}
if (caps.supportsAdditionalDirectories()) {
    client.newSession(new NewSessionRequest(cwd, List.of(), List.of("/extra/dir")));
}

Elicitation Capabilities (stable since 0.80.0; added 0.12.0 as unstable)

Clients advertise elicitation support during initialization. The capability’s modes are typed (ElicitationFormCapabilities, ElicitationUrlCapabilities); the no-argument ElicitationCapabilities() constructor is removed in 0.80.0 in favor of formOnly(), urlOnly(), and formAndUrl(). A client built with a createElicitationHandler and no explicit clientCapabilities(..) advertises form-mode elicitation automatically (0.80.0):

// Client: a registered handler is enough; no capability call needed
AcpSyncClient client = AcpClient.sync(transport)
    .createElicitationHandler(req -> CreateElicitationResponse.accept(Map.of("choice", "option-a")))
    .build();
client.initialize();

Set it explicitly with the capability builder to advertise without a handler, or to combine with other capabilities:

var caps = ClientCapabilities.builder().elicitationForm().readTextFile().build();
AcpSyncClient client = AcpClient.sync(transport)
    .clientCapabilities(caps)
    .createElicitationHandler(req -> CreateElicitationResponse.accept(Map.of("choice", "option-a")))
    .build();

// Agent: check before sending elicitation
if (context.getClientCapabilities().supportsElicitation()) {
    var response = context.client().createElicitation(
        CreateElicitationRequest.form(sessionId, "Pick one:", schema));
}

`@UnstableAcpApi`

APIs marked @UnstableAcpApi correspond to protocol elements in schema.unstable.json. They are public and functional but may change in any minor release. When the protocol element stabilizes, the annotation is removed (compatible change). See Stable vs Unstable for the full policy. IntelliJ users can configure the Unstable API Usage inspection (Settings > Inspections > JVM languages) to flag usages.

Transports

Transport	Client Class	Agent Class	Module
Stdio	`StdioAcpClientTransport`	`StdioAcpAgentTransport`	acp-core
Streamable HTTP	`StreamableHttpAcpClientTransport`	`StreamableHttpAcpAgentTransport` or `StreamableHttpAcpServlet`	acp-core / acp-streamable-http-jetty
WebSocket	`WebSocketAcpClientTransport`	`StreamableHttpAcpAgentTransport` (upgrade on the same path)	acp-core / acp-streamable-http-jetty
In-Memory	via `InMemoryTransportPair`	via `InMemoryTransportPair`	acp-test

Stdio Transport

The default transport. The client launches the agent as a subprocess and communicates via JSON-RPC over stdin/stdout. This is the same mechanism Zed, JetBrains, and VS Code use to talk to agents. Client side — AgentParameters specifies the command to launch. Any executable that speaks ACP over stdin/stdout works (Grok CLI, your own agent JAR, etc.):

var params = AgentParameters.builder("grok")
    .arg("agent")
    .arg("stdio")
    .build();
var transport = new StdioAcpClientTransport(params);

Agent side — reads JSON-RPC from stdin, writes responses to stdout. The agent doesn’t need to know what launched it:

var transport = new StdioAcpAgentTransport();

Streamable HTTP and WebSocket Transport

For remote agents, per the ACP Streamable HTTP and WebSocket transport RFD. One endpoint serves HTTP POST with Server-Sent Event streams and a WebSocket upgrade on the same path. Plain http:// is supported: against a server that speaks h2c, every request runs on HTTP/2. Agent (requires acp-streamable-http-jetty): StreamableHttpAcpAgentTransport is a listener, not a per-session transport. It creates one fresh agent per remote connection through an AcpAgentFactory:

AcpAgentFactory agents = AcpAgentFactory.sync(transport -> AcpAgent.sync(transport)
    .initializeHandler(req -> InitializeResponse.ok())
    .newSessionHandler(req -> new NewSessionResponse(UUID.randomUUID().toString(), null, null))
    .promptHandler((req, ctx) -> {
        ctx.sendMessage("Echo: " + req.text());
        return PromptResponse.endTurn();
    })
    .build());

var server = new StreamableHttpAcpAgentTransport(8080, AcpJsonMapper.createDefault(), agents);
server.start().block();  // http://localhost:8080/acp and ws://localhost:8080/acp

Use AcpAgentFactory.async(...) for an AcpAgent.async(...) agent. Other constructors take a custom path and StreamableHttpAcpAgentTransportOptions (POST body cap, SSE mailbox and backpressure limits, keep-alive, HTTP/2 stream limit). Agent in your own Servlet 6 container: StreamableHttpAcpServlet(jsonMapper, agentFactory) serves the HTTP/SSE profile at a path you choose; register it with async support. It does not serve the WebSocket upgrade. See Remote agents for a Spring Boot registration. Client, Streamable HTTP (in acp-core):

var transport = new StreamableHttpAcpClientTransport(
    URI.create("http://localhost:8080/acp"),
    AcpJsonMapper.createDefault()
);

Client, WebSocket (JDK-native, in acp-core):

var transport = new WebSocketAcpClientTransport(
    URI.create("ws://localhost:8080/acp"),
    AcpJsonMapper.createDefault()
);

WebSocketAcpAgentTransport (acp-websocket-jetty) was deprecated for removal in 0.18.0 and is removed in 0.80.0. It served a single WebSocket client. WebSocketAcpClientTransport clients connect to StreamableHttpAcpAgentTransport unchanged.

In-Memory Transport

For testing. No subprocess or network I/O.

var pair = InMemoryTransportPair.create();
// pair.clientTransport() — for client
// pair.agentTransport() — for agent
// pair.closeGracefully() — cleanup

Errors

Exception Hierarchy

Exception	Description
`AcpProtocolException`	JSON-RPC protocol error with code and message
`AcpCapabilityException`	Tried to use an unsupported capability
`AcpConnectionException`	Transport-level connection failure

Error Codes

try {
    client.prompt(request);
} catch (AcpProtocolException e) {
    if (e.isAuthenticationRequired()) {
        // Client must authenticate (session/authenticate) before this will work
    } else if (e.isMethodNotFound()) {
        // Agent doesn't support this method
    }
    System.err.println("Error " + e.getCode() + ": " + e.getMessage());
} catch (AcpCapabilityException e) {
    System.err.println("Not supported: " + e.getCapability());
}

isConcurrentPrompt() is removed in 0.80.0: a prompt sent while one is already running on the session is now a generic INVALID_REQUEST (-32600), not its own code. isAuthenticationRequired() is new. See the 0.80.0 migration guide.

Agent-Side Error Handling

Throw AcpProtocolException from handlers to send structured errors to clients:

.promptHandler((req, context) -> {
    if (req.prompt().isEmpty()) {
        throw new AcpProtocolException(
            AcpErrorCodes.INVALID_PARAMS, "Empty prompt");
    }
    // ...
})

Test Utilities

The acp-test module provides utilities for testing without subprocesses.

`InMemoryTransportPair`

var pair = InMemoryTransportPair.create();

// Wire up agent
AcpAsyncAgent agent = AcpAgent.async(pair.agentTransport())
    .initializeHandler(req -> Mono.just(InitializeResponse.ok()))
    .newSessionHandler(req -> Mono.just(
        new NewSessionResponse(UUID.randomUUID().toString(), null, null)))
    .promptHandler((req, context) ->
        context.sendMessage("response")
            .then(Mono.just(PromptResponse.endTurn())))
    .build();

agent.start().subscribe();

// Wire up client
AcpSyncClient client = AcpClient.sync(pair.clientTransport()).build();
client.initialize();
// ... test ...

pair.closeGracefully().block();

Packages

Package	Description
`com.agentclientprotocol.sdk.spec`	Protocol types (`AcpSchema.*`)
`com.agentclientprotocol.sdk.client`	Client SDK (`AcpClient`, `AcpAsyncClient`, `AcpSyncClient`)
`com.agentclientprotocol.sdk.agent`	Agent SDK (`AcpAgent`, `AcpAsyncAgent`, `AcpSyncAgent`)
`com.agentclientprotocol.sdk.agent.support`	Annotation-based agent runtime (`AcpAgentSupport`)
`com.agentclientprotocol.sdk.annotation`	Agent annotations (`@AcpAgent`, `@Prompt`, etc.)
`com.agentclientprotocol.sdk.capabilities`	Capability negotiation (`NegotiatedCapabilities`)
`com.agentclientprotocol.sdk.error`	Exceptions (`AcpProtocolException`, `AcpCapabilityException`)
`com.agentclientprotocol.sdk.test`	Test utilities (`InMemoryTransportPair`)

Maven Artifacts

Artifact	Description
`acp-core`	Client and Agent SDKs, stdio, WebSocket, and Streamable HTTP client transports; needs one JSON module
`acp-json-jackson2`	JSON implementation on Jackson 2 (`JacksonAcpJsonMapper`); brought in by the transport and agent-support modules
`acp-json-jackson3`	JSON implementation on Jackson 3 (`Jackson3AcpJsonMapper`)
`acp-annotations`	`@AcpAgent`, `@Prompt`, and other annotations
`acp-agent-support`	Annotation-based agent runtime (includes acp-annotations + acp-core)
`acp-test`	In-memory transport and test utilities
`acp-streamable-http-jetty`	Jetty-based Streamable HTTP and WebSocket agent transport, and the mountable `StreamableHttpAcpServlet`

acp-websocket-jetty (single-client WebSocket agent transport) is removed in 0.80.0; it is not a dependable artifact as of this release. See the 0.80.0 migration guide.

​Installation

​Maven (0.80.0 — stable)

​Gradle

​Snapshot (0.81.0-SNAPSHOT)

​Three Agent API Styles

​Quick Comparison

​When to Use Each

​Client API

​AcpClient — Factory

​AcpSyncClient — Blocking Client

​Builder Configuration

​Example — Complete client lifecycle

​Agent API — Annotation-Based

​Annotations

​Class-Level

​Handler Methods

​Parameter Annotations

​Connection-Level Parameters (0.80.0)

​Flexible Method Signatures

​Return Value Handling

​SyncPromptContext

​AcpAgentSupport — Bootstrap

​Interceptors

​Example — Complete annotation-based agent

​Agent API — Sync (Builder)

​Builder Methods

​Example

​Prompt Handler Context

​Agent API — Async (Builder)

​Example

​Convenience Methods vs Full API

​When convenience methods are enough (~80% of cases)

​When to use the full API (~20% of cases)

​Protocol Types

​Request/Response Types

​Session Types (0.12.0)

​Config Option Types (0.12.0)

​Provider Types (0.14.0, unstable)

​Elicitation Types (0.12.0, unstable)

​Content Types

​Session Update Types

​Stop Reasons

​Convenience Methods

​Capabilities

​Client Capabilities

​NegotiatedCapabilities

​Session Capabilities (0.12.0)

​Elicitation Capabilities (stable since 0.80.0; added 0.12.0 as unstable)

​@UnstableAcpApi

​Transports

​Stdio Transport

​Streamable HTTP and WebSocket Transport

​In-Memory Transport

​Errors

​Exception Hierarchy

​Error Codes

​Agent-Side Error Handling

​Test Utilities

​InMemoryTransportPair

​Packages

​Maven Artifacts

​See Also

Installation

Maven (0.80.0 — stable)

Gradle

Snapshot (0.81.0-SNAPSHOT)

Three Agent API Styles

Quick Comparison

When to Use Each

Client API

`AcpClient` — Factory

`AcpSyncClient` — Blocking Client

Builder Configuration

Example — Complete client lifecycle

Agent API — Annotation-Based

Annotations

Class-Level

Handler Methods

Parameter Annotations

Connection-Level Parameters (0.80.0)

Flexible Method Signatures

Return Value Handling

`SyncPromptContext`

`AcpAgentSupport` — Bootstrap

Interceptors

Example — Complete annotation-based agent

Agent API — Sync (Builder)

Builder Methods

Example

Prompt Handler Context

Agent API — Async (Builder)

Example

Convenience Methods vs Full API

When convenience methods are enough (~80% of cases)

When to use the full API (~20% of cases)

Protocol Types

Request/Response Types

Session Types (0.12.0)

Config Option Types (0.12.0)

Provider Types (0.14.0, unstable)

Elicitation Types (0.12.0, unstable)

Content Types

Session Update Types

Stop Reasons

Convenience Methods

Capabilities

Client Capabilities

`NegotiatedCapabilities`

Session Capabilities (0.12.0)

Elicitation Capabilities (stable since 0.80.0; added 0.12.0 as unstable)

`@UnstableAcpApi`

Transports

Stdio Transport

Streamable HTTP and WebSocket Transport

In-Memory Transport

Errors

Exception Hierarchy

Error Codes

Agent-Side Error Handling

Test Utilities

`InMemoryTransportPair`

Packages

Maven Artifacts

See Also