Spring Boot 4.1 autoconfiguration for the ACP Java SDK. It serves your @AcpAgent bean over stdio, Streamable HTTP or WebSocket, and it builds an ACP client from spring.acp.client.*. Two modules:

• acp-spring-boot-starter, the one to depend on. It brings this module, acp-agent-support and spring-boot-starter.
• acp-spring-boot-autoconfigure, this module: the autoconfiguration classes and the spring.acp.* properties, in package com.agentclientprotocol.sdk.spring.boot.autoconfigure (.agent, .client).

<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-spring-boot-starter</artifactId>
    <version>${acp.version}</version>
</dependency>
<!-- Only for an agent served over HTTP (spring.acp.agent.transport.type=http or websocket), one of:
     acp-http-servlet (a servlet web application), acp-http-webflux (a reactive one) or
     acp-streamable-http-jetty (no web server: the SDK's own listener) -->
<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-http-servlet</artifactId>
    <version>${acp.version}</version>
</dependency>

The starter has the SDK's version. Do not pin the other SDK modules to a version of their own: the starter brings the matching ones. The client's stdio, WebSocket and Streamable HTTP transports are in acp-core, so a client needs nothing more. Only an agent served over HTTP needs one more module, by application type: acp-http-servlet in a servlet web application (Spring MVC), acp-http-webflux in a reactive one, acp-streamable-http-jetty in an application without a web server (see Transports below). The SDK's Jackson 3 module is on the classpath, and the SDK chooses it over Jackson 2 (see the root README).

Annotate one bean @AcpAgent. Its handler methods, their parameters and their return types are those of acp-agent-support.

@Component
@AcpAgent(name = "echo", version = "1.0.0")
public class EchoAgent {

    @Prompt
    public PromptResponse prompt(PromptRequest request, SyncPromptContext context) {
        context.sendMessage("Echo: " + request.text());
        return PromptResponse.endTurn();
    }
}

@SpringBootApplication
public class AgentApplication {
    public static void main(String[] args) {
        SpringApplication.run(AgentApplication.class, args);
    }
}

Over stdio (the default), standard output carries the protocol, so nothing else may write to it. The transport's threads are daemon threads, so keep the application alive:

spring.main.keep-alive=true
spring.main.banner-mode=off
# Spring Boot's console logging writes to standard output: turn it off, log to a file,
# or configure a logback-spring.xml whose console appender has <target>System.err</target>
logging.console.enabled=false
logging.file.name=agent.log

When the client closes the agent's standard input and every answer has been written, the agent closes the application context, and the process exits 0 (spring.acp.agent.shutdown-on-transport-end).

• Finding the bean. The autoconfiguration finds the bean by its @AcpAgent annotation. Make the class a bean (@Component, or a @Bean method). The handler methods are read from the bean's own class, so a bean proxied by Spring AOP (CGLIB) is served with its advice. More than one @AcpAgent bean fails the startup with "Found 2 @AcpAgent beans [...]", naming them. An application without one, such as a client, gets no agent and no agent transport.
• One bean for every session. Over HTTP each connection gets its own agent, and every one of them calls the same bean. Make its handler methods thread-safe, and keep per-session state keyed by session ID.
• Extension beans. AcpInterceptor, ArgumentResolver and ReturnValueHandler beans are added to the agent in bean order.
• Your own beans win. An AcpAgentTransport bean of your own replaces stdio, for example the agent side of acp-test's InMemoryTransportPair in a test. An AcpAgentFactory, a StreamableHttpAcpAgentTransport, or a bean named acpServletRegistration of your own replaces the one the autoconfiguration creates.
• Lifecycle. The agent starts with the context and stops with it, waiting at most 30 seconds for a graceful stop.

Set one transport's command or URI, and the application gets an AcpAsyncClient and an AcpSyncClient. The sync client is a facade over the async one, so both share one session on one connection. Inject either.

spring.acp.client.transport.stdio.command=my-agent
spring.acp.client.transport.stdio.args=--acp

@Component
class SessionUpdates implements AcpClientCustomizer {
    @Override
    public void customize(AcpClient.AsyncSpec spec) {
        spec.sessionUpdateHandler(notification -> {
            if (notification.update() instanceof AgentMessageChunk chunk
                    && chunk.content() instanceof TextContent text) {
                System.out.print(text.text());
            }
            return Mono.empty();
        });
    }
}

@Component
class Ask implements CommandLineRunner {
    private final AcpSyncClient client;

    Ask(AcpSyncClient client) {
        this.client = client;
    }

    @Override
    public void run(String... args) {
        client.initialize();
        String sessionId = client.newSession(new NewSessionRequest("/workspace", List.of())).sessionId();
        client.prompt(new PromptRequest(sessionId, List.of(new TextContent("Hello"))));
    }
}

• Connecting. Creating the client bean connects the transport, and for stdio starts the agent process. initialize() then performs the ACP handshake.
• Customizers. AcpClientCustomizer beans (com.agentclientprotocol.sdk.integration, the same type in the Micronaut and Quarkus integrations) are applied to the client's builder in bean order. Register the session-update handler, the permission handler, and the file system, terminal and elicitation handlers there. Without a session-update handler of your own, session updates are logged at DEBUG, content included.
• Logging. DEBUG and TRACE on com.agentclientprotocol.sdk log message payloads in full; do not enable them where logs are shipped. A stdio agent's standard error is logged at INFO, unfiltered, on com.agentclientprotocol.sdk.client.transport.agent-stderr, and can carry sensitive data: set logging.level.com.agentclientprotocol.sdk.client.transport.agent-stderr=WARN to silence it.
• Capabilities. The client advertises none by default. Turn one on with its spring.acp.client.capabilities.* property and register its handler in a customizer. A capability turned on without its handler fails the startup, naming the property.
• Closing. When the context closes, the client is closed once. Pending notifications are delivered, waiting at most the request timeout plus 10 seconds, then the transport is closed.
• Your own beans win. An AcpClientTransport, AcpAsyncClient or AcpSyncClient bean of your own replaces the one the autoconfiguration creates.

The value is read in any case. With http or websocket, the kind of application decides where the endpoint runs:

One HTTP module per application type. A servlet web application adds acp-http-servlet; a reactive (WebFlux) web application adds acp-http-webflux; an application without a web server adds acp-streamable-http-jetty (the SDK's own listener). The starter brings none of them. A servlet web application on Tomcat 11 whose classpath puts a Jakarta WebSocket API older than 2.2 ahead of Tomcat's fails at startup naming the fix, since Tomcat would otherwise fail every WebSocket send.

Securing /acp. The endpoint has no authentication of its own; protect its path in your SecurityFilterChain as any other. ACP clients are not browsers, so exempt the path from CSRF; the endpoint itself refuses browser requests from foreign origins:

@Bean
SecurityFilterChain acpSecurity(HttpSecurity http) throws Exception {
    return http.authorizeHttpRequests(requests -> requests.requestMatchers("/acp").authenticated())
        .httpBasic(Customizer.withDefaults())
        .csrf(csrf -> csrf.ignoringRequestMatchers("/acp"))
        .build();
}

In a reactive application the same goes into a SecurityWebFilterChain; the principal Spring Security authenticated reaches the endpoint (AcpHttpExchange.principal()) there too:

@Bean
SecurityWebFilterChain acpSecurity(ServerHttpSecurity http) {
    return http.authorizeExchange(exchanges -> exchanges.pathMatchers("/acp").authenticated()
            .anyExchange().permitAll())
        .httpBasic(Customizer.withDefaults())
        .csrf(csrf -> csrf.requireCsrfProtectionMatcher(
                new NegatedServerWebExchangeMatcher(ServerWebExchangeMatchers.pathMatchers("/acp"))))
        .build();
}

Shutdown. Each client connection holds an open SSE response or WebSocket, which Spring Boot's graceful shutdown counts as an active request and would wait for, up to spring.lifecycle.timeout-per-shutdown-phase (30 seconds by default). A SmartLifecycle in the default phase therefore drains the endpoint first: SSE streams get a closing comment and complete, WebSockets close with 1001 (going away). It stops before graceful shutdown and the web server do.

Compression. With server.compression.enabled, text/event-stream is taken out of the compressed MIME types, on a servlet and a reactive server alike: a compressed SSE stream is held back until the compressor's buffer fills.

A reactive application. Add acp-http-webflux beside the starter and spring-boot-starter-webflux; the properties are the same spring.acp.agent.transport.* keys:

<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-http-webflux</artifactId>
    <version>${acp.version}</version>
</dependency>

On Reactor Netty the route raises Netty's WebSocket frame limit above spring.acp.agent.transport.http.max-post-body-size, so an oversized message is closed with 1009 by the endpoint. On Tomcat or Jetty as a WebFlux server, the container's own WebSocket message limit applies first (Tomcat 8 KB, Jetty 64 KB), so larger messages close with 1009 there; use Reactor Netty, or a servlet application, for large WebSocket messages. WebFlux reports no completion per WebSocket frame, so the route sends a frame only when the server asks for one: a client that stops reading fills the endpoint's bounded send queue, and the socket closes with 1011, as on every host.

Known issue in 0.80.0: WebFlux on Jetty. Jetty's connection idle timeout, 30 seconds by default, closes an ACP WebSocket after 30 seconds without traffic, well before spring.acp.agent.transport.http.web-socket-idle-timeout. Set server.jetty.connection-idle-timeout (for example 30m), or use Reactor Netty, the default server for WebFlux. A fix is planned for 0.80.1.

The rules for choosing one, the same in every framework integration:

• With none of type, stdio.command, websocket.uri and http.uri set, the application gets no transport and no client.
• type unset: the transport is the one whose command or URI is set. With more than one set, the startup fails, naming them.
• type set: it wins. If its own command or URI is missing, the startup fails, naming that property.

The SDK's listener and an agent mounted as a servlet both take websocket and http clients.

Durations take Spring's forms (30s, 500ms, PT1M), and sizes take DataSize forms (16MB). Most properties have no default of their own: unset, they keep the SDK's default, shown here. A value the SDK refuses, such as a negative duration, fails the startup.

The agent properties map onto AcpAgentSettings in acp-integration, and the transport.http.* limits onto StreamableHttpAcpAgentTransportOptions, which documents each range.

The client properties map onto AcpClientSettings in acp-integration. The Micronaut (acp.*) and Quarkus (quarkus.acp.*) integrations map their own keys onto the same settings, so each property means the same there.

• Agent. spring.acp.agent.enabled=false creates no agent beans: no agent factory, no stdio transport, no HTTP endpoint, and no agent on an AcpAgentTransport bean of your own. Any number of @AcpAgent beans is then allowed.
• Client. The client has no enabled property. It exists only when a spring.acp.client.transport.* property is set: leave them all unset for no client.

spring.acp.agent.handler-executor chooses the threads the agent's handler methods run on:

• Unset (the default). With spring.threads.virtual.enabled=true (JDK 21 and later), the context's applicationTaskExecutor, which starts a virtual thread per handler call. Otherwise the SDK's pool of platform threads, on every JDK: the starter follows Spring Boot's opt-in, not the SDK's own default of virtual threads on JDK 21. Without virtual threads, Spring Boot's applicationTaskExecutor is a pool of 8 threads by default, which would cap the prompts served at once.
• The name of an Executor bean. That bean. A plain Executor, such as a TaskExecutor, is adapted to an ExecutorService, and cancelling a handler still interrupts its thread. Handler methods block, so the executor must allow blocking. A name that matches no bean, or a bean that is no Executor, fails the startup.
• none, in any case. The SDK's pool of platform threads.

The same opt-in decides the threads of the SDK's listener and of the WebSocket and Streamable HTTP client transports: with virtual threads on, they run on the applicationTaskExecutor and create no pool of their own (a JDK HttpClient keeps its one selector thread, Jetty's virtual-thread pool one parked platform thread, and the SDK one JVM-wide timer thread, acp-timeout); otherwise they keep their pools of platform threads. On JDK 21 to 23 a virtual thread that blocks inside a synchronized block pins its carrier thread; JDK 24 removed that (JEP 491).

• One agent per application. A second @AcpAgent bean fails the startup.

The former spring-ai-community/acp-autoconfig project is now these two modules. In short:

• Coordinates: org.springaicommunity:acp-spring-boot-starter becomes com.agentclientprotocol:acp-spring-boot-starter, with the SDK's version. Drop any separate ACP SDK version pin.
• Imports: com.agentclientprotocol.autoconfigure.* becomes com.agentclientprotocol.sdk.spring.boot.autoconfigure.*. AcpClientCustomizer moves to com.agentclientprotocol.sdk.integration.
• The spring.acp.* keys are unchanged, except that the listener-only agent properties move under spring.acp.agent.transport.http.listener.* and the spring.acp.agent.transport.websocket.* properties are removed.

The full list of behaviour changes is in CHANGELOG.md, in the entry "Spring Boot autoconfiguration and starter, now part of the SDK" under Added. The SDK's other breaking changes in that release apply too.

• The root README: the SDK, its modules and its transports.
• acp-agent-support: the annotation programming model.
• acp-micronaut and acp-quarkus: the same integration for Micronaut and Quarkus.
• acp-integration: the framework-neutral half these build on.