ACP Java SDK

git clone https://github.com/markpollack/acp-java-tutorial.git
cd acp-java-tutorial

# Client: talk to Grok as an ACP agent
./mvnw exec:java -pl module-01-first-contact

# Agent: build and run your own (no API key needed)
./mvnw package -pl module-12-echo-agent -q
./mvnw exec:java -pl module-12-echo-agent

import com.agentclientprotocol.sdk.client.*;
import com.agentclientprotocol.sdk.client.transport.*;
import com.agentclientprotocol.sdk.spec.AcpSchema.*;
import java.util.List;

// Launch the Grok CLI as an ACP agent subprocess
var params = AgentParameters.builder("grok").arg("agent").arg("stdio").build();
var transport = new StdioAcpClientTransport(params);

AcpSyncClient client = AcpClient.sync(transport)
    .sessionUpdateHandler(notification -> {
        // Print the agent's response as it streams in
        if (notification.update() instanceof AgentMessageChunk msg) {
            System.out.print(((TextContent) msg.content()).text());
        }
    })
    .build();

client.initialize();
// ACP requires cwd to be an absolute path; agents may reject "."
var session = client.newSession(new NewSessionRequest(System.getProperty("user.dir"), List.of()));

var response = client.prompt(new PromptRequest(
    session.sessionId(),
    List.of(new TextContent("What is 2+2? Reply with just the number."))
));

System.out.println("\nStop reason: " + response.stopReason());
client.close();
// Output: 4
// Stop reason: end_turn

import com.agentclientprotocol.sdk.annotation.*;
import com.agentclientprotocol.sdk.agent.SyncPromptContext;
import com.agentclientprotocol.sdk.agent.support.AcpAgentSupport;
import com.agentclientprotocol.sdk.agent.transport.StdioAcpAgentTransport;
import com.agentclientprotocol.sdk.spec.AcpSchema.*;
import java.util.UUID;

@AcpAgent
class EchoAgent {

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

    @NewSession
    NewSessionResponse newSession() {
        return new NewSessionResponse(UUID.randomUUID().toString(), null, null);
    }

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

// Reads JSON-RPC from stdin, writes to stdout — editors connect here
AcpAgentSupport.create(new EchoAgent())
    .transport(new StdioAcpAgentTransport())
    .build()
    .run();

<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 Jackson 3 (tools.jackson.databind), for example alongside Spring Boot 4 -->
<!--
<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-json-jackson3</artifactId>
    <version>0.80.0</version>
</dependency>
-->

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

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

import com.agentclientprotocol.sdk.agent.AcpAgent;
import com.agentclientprotocol.sdk.agent.AcpAgentFactory;
import com.agentclientprotocol.sdk.agent.transport.StreamableHttpAcpAgentTransport;
import com.agentclientprotocol.sdk.json.AcpJsonMapper;
import com.agentclientprotocol.sdk.spec.AcpSchema.*;
import java.util.UUID;

// One fresh agent per remote connection
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();            // serves http://localhost:8080/acp and ws://localhost:8080/acp
server.awaitTermination().block();

import com.agentclientprotocol.sdk.client.AcpClient;
import com.agentclientprotocol.sdk.client.AcpSyncClient;
import com.agentclientprotocol.sdk.client.transport.StreamableHttpAcpClientTransport;
import com.agentclientprotocol.sdk.json.AcpJsonMapper;
import com.agentclientprotocol.sdk.spec.AcpSchema.*;
import java.net.URI;
import java.util.List;

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

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

client.initialize();
var session = client.newSession(new NewSessionRequest(".", List.of()));
var response = client.prompt(new PromptRequest(
    session.sessionId(), List.of(new TextContent("Hello over HTTP!"))));

System.out.println("\nStop reason: " + response.stopReason());
client.close();
// Output: Echo: Hello over HTTP!
// Stop reason: END_TURN

import com.agentclientprotocol.sdk.agent.AcpAgentFactory;
import com.agentclientprotocol.sdk.agent.transport.StreamableHttpAcpServlet;
import com.agentclientprotocol.sdk.json.AcpJsonMapper;
import org.springframework.boot.web.servlet.ServletRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
class AcpServletConfig {

    @Bean
    ServletRegistrationBean<StreamableHttpAcpServlet> acpServlet(AcpAgentFactory agents) {
        var registration = new ServletRegistrationBean<>(
            new StreamableHttpAcpServlet(AcpJsonMapper.createDefault(), agents), "/acp");
        registration.setAsyncSupported(true);
        return registration;
    }
}