Sandbox::https://lab.pollack.ai/docs/acp-java-sdk/tutorial

A progressive, hands-on tutorial. Each module focuses on one concept and includes runnable source code.

Prerequisites

Java 17 or later
Maven 3.8+ (or use the included ./mvnw wrapper)
For client modules (01-11, 21): the Grok CLI, signed in once with grok login. The tutorial uses Grok as a real ACP agent to talk to, launched as grok agent stdio; the SDK runs it as a subprocess and communicates over stdin/stdout. No API key is needed.
For agent modules (12-20, 22, 31): no external dependencies. You build the agent and the tutorial provides a test client that launches it.
For the AI chatbot modules (25-27): an ANTHROPIC_API_KEY, which the agent actually uses to call the model.
For the agent-client module (32): the Claude CLI installed and logged in, run without ANTHROPIC_API_KEY.
For the new-in-0.80.0 modules (33-41): no external dependencies, same as the agent modules. Module 38 requires Java 21+ (Spring Boot 4.x); modules 40 and 41 (Micronaut, Quarkus) each pull in their own framework’s BOM.

Part	Modules	Topics
1. Client Basics	01-11	Connect, sessions, prompts, streaming, updates, file handlers, permissions, resume, cancel, errors
2. Building Agents	12-20	Echo agent, handlers, updates, requests, testing, capabilities, terminal, MCP, session management
3. Advanced	21-24	Async client, async agent (Project Reactor), Spring Boot agent and client
4. AI-Backed Agents	25-27	The echo agent with a real model behind it: Anthropic Java SDK, Spring AI, LangChain4j
5. IDE Integration	28-30	Zed, JetBrains, VS Code
6. Beyond Chat	31-32	Elicitation (structured user input), an agent loop behind an ACP agent
7. New in 0.80.0	33-41	Session config options, extension methods, cancellation and timeouts, terminal auth and logout, Streamable HTTP/WebSocket, Spring Boot over HTTP, forward compatibility, Micronaut, Quarkus

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

Agent modules run locally with no API key:

./mvnw package -pl module-12-echo-agent -q
./mvnw exec:java -pl module-12-echo-agent

Client modules require the Grok CLI on your PATH, signed in once with grok login:

./mvnw exec:java -pl module-01-first-contact

The SDK provides three ways to build agents:

Style	Entry Point	Programming Model
Annotation-based	`@AcpAgent`, `@Prompt`	Declarative, least boilerplate
Sync	`AcpAgent.sync()`	Blocking handlers, plain return values
Async	`AcpAgent.async()`	Reactive, Project Reactor `Mono`

The tutorial uses Sync for agent examples (most accessible to most developers) and introduces annotations and async where relevant.

Begin with Module 01: First Contact to connect to your first ACP agent. Or jump to Module 12: Echo Agent to build an agent without any API key, then give it a brain in Module 25: AI Chatbot Agent.