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): Gemini CLI with --experimental-acp flag, and a GEMINI_API_KEY. The tutorial uses Gemini as a real ACP agent to talk to — the SDK launches it as a subprocess and communicates over stdin/stdout.
For agent modules (12-19, 22): no external dependencies. You build the agent and the tutorial provides a test client that launches it.

Part	Modules	Topics
1. Client Basics	01-11	Connect, sessions, prompts, streaming, updates, file handlers, permissions, resume, cancel, errors
2. Building Agents	12-19	Echo agent, handlers, updates, requests, testing, capabilities, terminal, MCP
3. Advanced	21-22	Async client, async agent (Project Reactor)
4. IDE Integration	28-30	Zed, JetBrains, VS Code

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 GEMINI_API_KEY:

export GEMINI_API_KEY=your-key-here
./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.