### Complete AcpAsyncAgent Usage Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpAgent.md

Demonstrates the complete setup and usage of an asynchronous AcpAgent. This includes configuring transport, handlers for initialization, new sessions, and prompts, and starting the agent.

```java
import com.agentclientprotocol.sdk.agent.*;
import com.agentclientprotocol.sdk.agent.transport.*;
import com.agentclientprotocol.sdk.spec.AcpSchema.*;
import reactor.core.publisher.Mono;
import java.util.UUID;

var transport = new StdioAcpAgentTransport();

// Async agent
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) -> {
        return context.sendMessage("Hello from agent!")
            .then(Mono.just(PromptResponse.endTurn()));
    })
    .build();

// Start agent (non-blocking)
agent.start();

// Or run agent (blocking)
// agent.run().block();

```

--------------------------------

### Build and Start Async Agent

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpAgent.md

Example of building and starting an asynchronous ACP agent. This involves setting handlers for initialization, new sessions, and prompts, then starting the agent.

```java
AcpAgentTransport transport = new StdioAcpAgentTransport();

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 from agent!")
            .then(Mono.just(PromptResponse.endTurn())))
    .build();

agent.start().block();
```

--------------------------------

### Agent WebSocket Transport Setup

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/README.md

Set up the agent to use WebSocket transport. This example demonstrates creating a WebSocket transport, configuring the server port and path, and starting the agent's WebSocket server.

```java
import com.agentclientprotocol.sdk.agent.transport.WebSocketAcpAgentTransport;

var transport = new WebSocketAcpAgentTransport(
    8080,                           // port
    "/acp",                         // path
    AcpJsonMapper.createDefault()
);
AcpAsyncAgent agent = AcpAgent.async(transport)
    // ... handlers ...
    .build();

agent.start().block();  // Starts WebSocket server on port 8080
```

--------------------------------

### Complete AcpSyncClient Usage Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpSyncClient.md

Demonstrates the complete lifecycle of using AcpSyncClient, including transport creation, client initialization, session management, sending prompts, and graceful closure. This example requires setting up handlers for file operations and session updates.

```java
import com.agentclientprotocol.sdk.client.*;
import com.agentclientprotocol.sdk.client.transport.*;
import com.agentclientprotocol.sdk.spec.AcpSchema.*;
import java.util.List;
import java.time.Duration;
import java.nio.file.Files;
import java.nio.file.Path;

// Create transport
var params = AgentParameters.builder("gemini")
    .arg("--experimental-acp")
    .build();
var transport = new StdioAcpClientTransport(params, 
    AcpJsonMapper.createDefault());

// Create synchronous client with handlers
AcpSyncClient client = AcpClient.sync(transport)
    .requestTimeout(Duration.ofSeconds(30))
    .readTextFileHandler(req ->
        new ReadTextFileResponse(
            Files.readString(Path.of(req.path()))))
    .writeTextFileHandler(req -> {
        Files.writeString(Path.of(req.path()), req.content());
        return new WriteTextFileResponse();
    })
    .sessionUpdateConsumer(notification -> {
        if (notification.update() instanceof AgentMessageChunk msg) {
            System.out.print(((TextContent) msg.content()).text());
        }
    })
    .build();

try {
    // Initialize
    client.initialize();
    
    // Create session
    var session = client.newSession(
        new NewSessionRequest("/workspace", List.of()));
    
    // Send prompt
    var response = client.prompt(new PromptRequest(
        session.sessionId(),
        List.of(new TextContent("What files are in src/?"))));
    
    System.out.println("\nStop reason: " + response.stopReason());
} catch (AcpProtocolException e) {
    System.err.println("Protocol error: " + e.getMessage());
} finally {
    client.closeGracefully();
}
```

--------------------------------

### StdioAcpAgentTransport Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Transports.md

Demonstrates creating and starting an agent using StdioAcpAgentTransport. This transport is suitable for local agent execution.

```java
import com.agentclientprotocol.sdk.agent.transport.*;
import com.agentclientprotocol.sdk.agent.AcpAgent;

// Create transport
var transport = new StdioAcpAgentTransport(
    AcpJsonMapper.createDefault());

// Create agent
var agent = AcpAgent.async(transport)
    .initializeHandler(req -> Mono.just(InitializeResponse.ok()))
    .build();

agent.start().block();
```

--------------------------------

### Prompt Annotation Examples

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Provides examples for synchronous and asynchronous prompt request handlers using the @Prompt annotation. The sync example processes a file and returns text, while the async example sends a message and ends the turn.

```java
@Prompt
PromptResponse handlePrompt(PromptRequest req, SyncPromptContext ctx) {
    ctx.sendMessage("Processing...");
    String content = ctx.readFile("main.java");
    return PromptResponse.text("Found: " + content);
}

// Async variant
@Prompt
Mono<PromptResponse> handlePromptAsync(PromptRequest req, PromptContext ctx) {
    return ctx.sendMessage("Processing...")
        .then(Mono.just(PromptResponse.endTurn()));
}
```

--------------------------------

### Complete AcpAsyncClient Usage Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpAsyncClient.md

A comprehensive example demonstrating the creation of an AcpAsyncClient, initialization, session creation, sending a prompt, and graceful client closure. It includes necessary imports and configuration.

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

// Create transport
var params = AgentParameters.builder("gemini")
    .arg("--experimental-acp")
    .build();
var transport = new StdioAcpClientTransport(params, 
    AcpJsonMapper.createDefault());

// Create client with streaming updates
AcpAsyncClient client = AcpClient.async(transport)
    .requestTimeout(Duration.ofSeconds(30))
    .sessionUpdateConsumer(notification -> {
        if (notification.update() instanceof AgentMessageChunk msg) {
            System.out.print(((TextContent) msg.content()).text());
        }
        return Mono.empty();
    })
    .build();

try {
    // Initialize
    client.initialize().block();
    
    // Create session
    var session = client.newSession(
        new NewSessionRequest("/workspace", List.of()))
        .block();
    
    // Send prompt
    var response = client.prompt(new PromptRequest(
        session.sessionId(),
        List.of(new TextContent("What is 2+2?"))))
        .block();
    
    System.out.println("\nStop reason: " + response.stopReason());
} finally {
    client.closeGracefully().block();
}
```

--------------------------------

### Client WebSocket Transport Setup

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/README.md

Configure the client to use WebSocket for communication. This example shows how to create a WebSocket transport instance and build a synchronous ACP client.

```java
import com.agentclientprotocol.sdk.client.transport.WebSocketAcpClientTransport;
import java.net.URI;

var transport = new WebSocketAcpClientTransport(
    URI.create("ws://localhost:8080/acp"),
    AcpJsonMapper.createDefault()
);
AcpSyncClient client = AcpClient.sync(transport).build();
```

--------------------------------

### InitializeRequest Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/types.md

Demonstrates how to create an instance of InitializeRequest. Ensure correct protocol version and client capabilities are provided.

```java
var request = new InitializeRequest(1,
    new ClientCapabilities(
        new FileSystemCapability(true, true),
        true,
        null));
```

--------------------------------

### SyncAgentBuilder: Prompt Handler Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpAgent.md

Provides an example of setting a synchronous prompt handler. This handler processes prompts, sends messages, reads files, and returns a response.

```java
.promptHandler((req, context) -> {
    context.sendMessage("Processing your request...");
    String content = context.readFile("file.txt");
    return PromptResponse.text("Found: " + content);
})
```

--------------------------------

### AgentParameters Builder Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Transports.md

Illustrates building AgentParameters for configuring agent processes, including setting command-line arguments and environment variables.

```java
import com.agentclientprotocol.sdk.client.transport.AgentParameters;

// Basic usage
AgentParameters params = AgentParameters.builder("gemini")
    .arg("--experimental-acp")
    .build();

// With environment
AgentParameters params = AgentParameters.builder("python")
    .arg("agent.py")
    .env("API_KEY", "secret-key")
    .env("LOG_LEVEL", "DEBUG")
    .build();

// Multiple arguments
AgentParameters params = AgentParameters.builder("node")
    .arg("--experimental-modules")
    .arg("./agent.js")
    .args("--port", "3000", "--debug")
    .build();
```

--------------------------------

### Hello World Client Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/README.md

Connect to an ACP agent using Stdio transport, send a prompt, and process the response. Ensure the agent is launched as a subprocess.

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

// Launch Gemini CLI as an ACP agent subprocess
var params = AgentParameters.builder("gemini").arg("--experimental-acp").build();
var transport = new StdioAcpClientTransport(params);

// Create client — sessionUpdateConsumer prints the agent's streamed response
AcpSyncClient client = AcpClient.sync(transport)
    .sessionUpdateConsumer(notification -> {
        if (notification.update() instanceof AgentMessageChunk msg) {
            System.out.print(((TextContent) msg.content()).text());
        }
    })
    .build();

// Three-phase lifecycle: initialize → session → prompt
client.initialize();
var session = client.newSession(new NewSessionRequest("/workspace", List.of()));
var response = client.prompt(new PromptRequest(
    session.sessionId(),
    List.of(new TextContent("What is 2+2? Reply with just the number."))
));
// Output: 4
// Stop reason: END_TURN

System.out.println("\nStop reason: " + response.stopReason());
client.close();
```

--------------------------------

### List Sessions Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpAsyncClient.md

Demonstrates how to list all sessions and iterate through their metadata. Use this to retrieve session identifiers and other details.

```java
AcpSchema.ListSessionsResponse response = client
    .listSessions(new AcpSchema.ListSessionsRequest(null, null, null))
    .block();

for (var sessionMeta : response.sessions()) {
    System.out.println(sessionMeta.sessionId());
}
```

--------------------------------

### Initialize Annotation Examples

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Provides examples for synchronous and asynchronous initialize request handlers using the @Initialize annotation. The sync handler returns InitializeResponse directly, while the async handler returns a Mono<InitializeResponse>.

```java
@Initialize
InitializeResponse init(InitializeRequest req) {
    return InitializeResponse.ok();
}

// Async variant
@Initialize
Mono<InitializeResponse> initAsync(InitializeRequest req) {
    return Mono.just(InitializeResponse.ok());
}
```

--------------------------------

### AsyncAgentBuilder Prompt Handler Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpAgent.md

Configures the prompt handler, which is invoked for user prompts. This example demonstrates reading a file and sending a message before ending the turn.

```java
import reactor.core.publisher.Mono;
import com.acp.PromptResponse;
import com.acp.PromptHandler;
import com.acp.AcpSchema.ReadTextFileRequest;

// ... builder configuration
.promptHandler((req, context) -> {
    // Read files from client
    var response = context.readTextFile(
        new ReadTextFileRequest("/path/to/file.txt")).block();
    
    // Send progress update
    context.sendMessage("Processing...").block();
    
    return Mono.just(PromptResponse.endTurn());
})
```

--------------------------------

### Complete Analyzer Agent Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/SyncPromptContext.md

A full example of an agent implementing a code analyzer. It includes initialization, session handling, and prompt handling with file reading and message sending.

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

@AcpAgent(name = "analyzer", version = "1.0")
class AnalyzerAgent {

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

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

    @Prompt
    PromptResponse handlePrompt(PromptRequest req, SyncPromptContext ctx) {
        ctx.sendMessage("Analyzing your code...");
        
        try {
            // Read source file
            String code = ctx.readFile("Main.java");
            
            // Analyze
            int lines = code.split("\n").length;
            ctx.sendMessage("Found " + lines + " lines of code");
            
            // Send response
            return PromptResponse.text("Analysis complete");
        } catch (Exception e) {
            ctx.sendMessage("Error: " + e.getMessage());
            return PromptResponse.endTurn();
        }
    }
}

// Bootstrap and run
public static void main(String[] args) {
    AcpAgentSupport.create(new AnalyzerAgent())
        .transport(new StdioAcpAgentTransport())
        .run();
}
```

--------------------------------

### Complete Chat Agent Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

A full implementation of a chat agent using various ACP annotations and SDK features. This example demonstrates agent bootstrapping, session management, prompt handling, and exception handling.

```java
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.ArrayList;
import java.util.List;
import java.util.UUID;

@AcpAgent(name = "chat-agent", version = "1.0")
class ChatAgent {

    static class SessionData {
        List<String> messages = new ArrayList<>();
    }

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

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

    @Prompt
    PromptResponse handlePrompt(
            PromptRequest req,
            SyncPromptContext ctx,
            @SessionId String sessionId,
            @SessionState SessionData data) {
        try {
            ctx.sendThought("Processing message from session " + sessionId);

            // Extract user message
            String userMessage = req.content().isEmpty() ? "" :
                ((TextContent) req.content().get(0)).text();

            // Store in session history
            data.messages.add("User: " + userMessage);

            // Send response
            ctx.sendMessage("Hello! You said: " + userMessage);
            data.messages.add("Agent: Response sent");

            return PromptResponse.endTurn();
        } catch (Exception e) {
            ctx.sendMessage("Error: " + e.getMessage());
            return PromptResponse.endTurn();
        }
    }

    @AcpExceptionHandler
    PromptResponse handleError(Exception e) {
        return PromptResponse.text("Unexpected error: " + e.getMessage());
    }
}

// Bootstrap and run
public class ChatAgentMain {
    public static void main(String[] args) {
        AcpAgentSupport.create(new ChatAgent())
            .transport(new StdioAcpAgentTransport())
            .run();
    }
}
```

--------------------------------

### Hello World Agent (Annotation-Based)

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/README.md

Build a simple ACP agent using annotations for minimal boilerplate. This example demonstrates the basic structure for an agent with initialization, new session handling, and prompt processing.

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

@AcpAgent
class HelloAgent {

    @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("Hello from the agent!");
        return PromptResponse.endTurn();
    }
}

// Bootstrap and run
AcpAgentSupport.create(new HelloAgent())
    .transport(new StdioAcpAgentTransport())
    .run();
```

--------------------------------

### Complete Agent Implementation with Annotations

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/acp-agent-support/README.md

An example of a complete agent implementation using annotations for defining agent behavior, including initialization, session management, and prompt handling.

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

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

    @Initialize
    InitializeResponse init(InitializeRequest req) {
        // Customize response based on client capabilities
        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());
    }

    @LoadSession
    LoadSessionResponse loadSession(LoadSessionRequest req) {
        if (!sessionHistory.containsKey(req.sessionId())) {
            throw new AcpProtocolException(AcpErrorCodes.SESSION_NOT_FOUND,
                "Session not found: " + req.sessionId());
        }
        return new LoadSessionResponse(List.of(), List.of());
    }

    @Prompt
    PromptResponse prompt(PromptRequest req, SyncPromptContext ctx) {
        String sessionId = ctx.getSessionId();
        sessionHistory.get(sessionId).add(extractText(req));

        ctx.sendThought("Analyzing the code...");

        // Check if we can read files
        if (ctx.getClientCapabilities().readTextFile()) {
            ctx.sendMessage("I can access files if needed.");
        }

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

    @SetSessionMode
    SetSessionModeResponse setMode(SetSessionModeRequest req) {
        return new SetSessionModeResponse();
    }

    @Cancel
    void onCancel(CancelNotification notification, @SessionId String sessionId) {
        // Clean up any long-running operations
        log.info("Cancelled session: {}", sessionId);
    }

    private String extractText(PromptRequest req) {
        return req.prompt().stream()
            .filter(c -> c instanceof TextContent)
            .map(c -> ((TextContent) c).text())
            .collect(Collectors.joining("\n"));
    }
}

public class Main {
    public static void main(String[] args) {
        AcpAgentSupport.create(new CodeAssistant())
            .transport(StdioAcpAgentTransport.create())
            .interceptor(new MetricsInterceptor())
            .run();
    }
}
```

--------------------------------

### Build and Run Sync Agent

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpAgent.md

Example of building and running a synchronous ACP agent. This involves setting handlers for initialization, new sessions, and prompts, then running the agent.

```java
AcpSyncAgent agent = AcpAgent.sync(transport)
    .initializeHandler(req -> InitializeResponse.ok())
    .newSessionHandler(req -> 
        new NewSessionResponse(UUID.randomUUID().toString(), null, null))
    .promptHandler((req, context) -> {
        context.sendMessage("Hello from agent!");
        return PromptResponse.endTurn();
    })
    .build();

agent.run();
```

--------------------------------

### NewSessionResponse Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/types.md

Demonstrates creating a NewSessionResponse with a generated session ID and null values for session state and configuration options. Useful for testing or default responses.

```java
var response = new NewSessionResponse(
    UUID.randomUUID().toString(),
    null,
    null);
```

--------------------------------

### NewSession Annotation Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Example of a new session request handler using the @NewSession annotation. It generates a new session ID and returns a NewSessionResponse.

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

--------------------------------

### Example Usage of @SetSessionConfigOption

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Shows how to use the @SetSessionConfigOption annotation on a method that processes SetSessionConfigOptionRequest and returns SetSessionConfigOptionResponse.

```java
@SetSessionConfigOption
SetSessionConfigOptionResponse setConfig(SetSessionConfigOptionRequest req) {
    return new SetSessionConfigOptionResponse(req.configId(), req.value());
}
```

--------------------------------

### LoadSession Annotation Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Example of a load session request handler using the @LoadSession annotation. It receives the request and the session ID, returning a LoadSessionResponse.

```java
@LoadSession
LoadSessionResponse loadSession(LoadSessionRequest req, @SessionId String id) {
    return new LoadSessionResponse();
}
```

--------------------------------

### WebSocketAcpAgentTransport Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Transports.md

Shows how to set up an agent with WebSocket transport, enabling remote agent connections. Requires the acp-websocket-jetty module.

```java
import com.agentclientprotocol.sdk.agent.transport.*;
import com.agentclientprotocol.sdk.agent.AcpAgent;

// Create transport with WebSocket server on port 8080
var transport = new WebSocketAcpAgentTransport(
    8080,                           // port
    "/acp",                         // path
    AcpJsonMapper.createDefault()
);

// Create agent
var agent = AcpAgent.async(transport)
    .initializeHandler(req -> Mono.just(InitializeResponse.ok()))
    .promptHandler((req, context) ->
        context.sendMessage("Hello via WebSocket!")
            .then(Mono.just(PromptResponse.endTurn())))
    .build();

// Start server (listening on ws://localhost:8080/acp)
agent.start().block();
```

--------------------------------

### Synchronous Agent (Blocking)

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/README.md

This example demonstrates setting up a synchronous ACP agent. It includes handlers for initialization, new session creation, and prompt processing, including reading from a file and sending messages.

```java
var transport = new StdioAcpAgentTransport();

AcpSyncAgent agent = AcpAgent.sync(transport)
    .initializeHandler(req -> InitializeResponse.ok())
    .newSessionHandler(req -> 
        new NewSessionResponse(UUID.randomUUID().toString(), null, null))
    .promptHandler((req, ctx) -> {
        ctx.sendMessage("Processing...");
        String content = ctx.readFile("input.txt");
        return PromptResponse.text("Read: " + content);
    })
    .build();

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

--------------------------------

### Agent: Check Client Capabilities

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/README.md

Before performing operations, check if the client supports them. This example shows how to check for read/write text file capabilities and use 'require' methods for stricter checks.

```java
NegotiatedCapabilities clientCaps = agent.getClientCapabilities();
if (clientCaps.supportsReadTextFile()) {
    agent.readTextFile(...);
} else {
    // Client doesn't support file reading - handle gracefully
}

// Or use require methods (throws AcpCapabilityException if not supported)
clientCaps.requireWriteTextFile();
agent.writeTextFile(...);
```

--------------------------------

### Prompt Agent Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpAsyncClient.md

Shows how to send a text prompt to the agent within a specific session and retrieve the stop reason. This is used for interactive agent communication.

```java
AcpSchema.PromptResponse response = client
    .prompt(new AcpSchema.PromptRequest(
        sessionId,
        List.of(new AcpSchema.TextContent("Fix the failing test"))))
    .block();

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

--------------------------------

### Running an Agent with AcpAgentSupport

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/acp-agent-support/README.md

Configure and run an AcpAgentSupport instance. Supports both non-blocking start with manual close and blocking run until closed.

```java
AcpAgentSupport support = AcpAgentSupport.create(new MyAgent())
    .transport(transport)
    .build();

// Option 1: Non-blocking start
support.start();
// ... do other work ...
support.close();

// Option 2: Blocking run (blocks until closed)
support.run();
```

--------------------------------

### Example Usage of @ResumeSession

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Shows how to use the @ResumeSession annotation on a method that takes ResumeSessionRequest and a session ID, returning ResumeSessionResponse.

```java
@ResumeSession
ResumeSessionResponse resumeSession(ResumeSessionRequest req, @SessionId String id) {
    return new ResumeSessionResponse();
}
```

--------------------------------

### AcpJsonMapper Usage Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Transports.md

Demonstrates how to use AcpJsonMapper for serializing and deserializing ACP requests. Requires importing AcpJsonMapper.

```java
import com.agentclientprotocol.sdk.json.AcpJsonMapper;

AcpJsonMapper mapper = AcpJsonMapper.createDefault();

// Serialize
String json = mapper.serialize(request);

// Deserialize
InitializeRequest req = mapper.deserialize(json, InitializeRequest.class);
```

--------------------------------

### Example of Graceful Close

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpAsyncClient.md

Demonstrates how to call the closeGracefully method and block until the operation is complete.

```java
client.closeGracefully().block();
```

--------------------------------

### Install ACP Agent Support Dependency

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/README.md

Include the acp-agent-support dependency for annotation-based agent development.

```xml
<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-agent-support</artifactId>
    <version>0.12.0</version>
</dependency>
```

--------------------------------

### Example Usage of @SetSessionModel

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Shows how to apply the @SetSessionModel annotation to a method that processes SetSessionModelRequest and returns SetSessionModelResponse.

```java
@SetSessionModel
SetSessionModelResponse setModel(SetSessionModelRequest req) {
    return new SetSessionModelResponse();
}
```

--------------------------------

### Cancel Session Operation Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpAsyncClient.md

Demonstrates how to send a cancellation notification for a session. Use this to halt ongoing operations for a specific session.

```java
client.cancel(new AcpSchema.CancelNotification(sessionId, "User cancelled"))
    .block();
```

--------------------------------

### Install ACP WebSocket Jetty Dependency

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/README.md

Add the acp-websocket-jetty dependency to enable WebSocket server support for agents.

```xml
<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-websocket-jetty</artifactId>
    <version>0.12.0</version>
</dependency>
```

--------------------------------

### Example Usage of @SessionId

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Shows how to inject the session ID using the @SessionId annotation in a method that handles PromptRequest and returns PromptResponse.

```java
@Prompt
PromptResponse handle(PromptRequest req, @SessionId String sessionId) {
    System.out.println("Session: " + sessionId);
    return PromptResponse.endTurn();
}
```

--------------------------------

### Example Usage of UnstableAcpApi

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Demonstrates the usage of the @UnstableAcpApi annotation on a method that utilizes an unstable protocol feature. This highlights the intent to use potentially changing API elements.

```java
@Prompt
@UnstableAcpApi
PromptResponse handleUnstableFeature(PromptRequest req) {
    // This method uses an unstable protocol feature
    return PromptResponse.endTurn();
}
```

--------------------------------

### Using AcpCapabilityException for Capability Checks

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/errors.md

Check client capabilities before performing an action or throw AcpCapabilityException if a required capability is missing. This example demonstrates checking and then using the capability, or checking support first.

```java
// Agent checking client capabilities
NegotiatedCapabilities caps = agent.getClientCapabilities();

try {
    caps.requireReadTextFile();  // Throws if not supported
    var response = context.readTextFile(new ReadTextFileRequest(...))
        .block();
} catch (AcpCapabilityException e) {
    logger.error("Client doesn't support capability: " + e.getCapability());
    // Handle gracefully or inform client
}

// Alternatively, check before using
if (caps.supportsReadTextFile()) {
    var response = context.readTextFile(...).block();
} else {
    logger.info("Client doesn't support file reading, skipping");
}
```

--------------------------------

### SLF4J Configuration for ACP Errors

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/errors.md

Configure Logback to control the logging level for the Agent Client Protocol SDK. This example sets specific levels for SDK-related loggers.

```properties
# logback.xml
<logger name="com.agentclientprotocol.sdk" level="DEBUG"/>
<logger name="com.agentclientprotocol.sdk.error" level="ERROR"/>
```

--------------------------------

### Get Negotiated Client Capabilities

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/PromptContext.md

Retrieves the capabilities that were negotiated with the client during initialization. Use this to check if specific features like file reading are supported.

```java
NegotiatedCapabilities caps = context.getClientCapabilities();
if (caps.supportsReadTextFile()) {
    // Safe to use readTextFile
}
```

--------------------------------

### Testing Agents with In-Memory Transports

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/README.md

Provides an example of setting up tests for ACP agents using `InMemoryTransportPair` for in-memory communication. Includes mocking the client and defining agent behavior.

```java
import com.agentclientprotocol.sdk.test.*;

InMemoryTransportPair pair = InMemoryTransportPair.create();

MockAcpClient client = MockAcpClient.builder(pair.clientTransport())
    .fileContent("/test.txt", "test content")
    .build();

var agent = AcpAgent.sync(pair.agentTransport())
    .promptHandler((req, ctx) ->
        PromptResponse.text(ctx.readFile("/test.txt")))
    .build();
```

--------------------------------

### AcpAgent Annotation Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Example of using the @AcpAgent annotation to define an agent named 'code-analyzer' with version '1.0'.

```java
@AcpAgent(name = "code-analyzer", version = "1.0")
class CodeAnalyzerAgent {
    @Prompt
    PromptResponse analyze(PromptRequest req, SyncPromptContext ctx) {
        // Implementation
    }
}
```

--------------------------------

### Example AcpExceptionHandler Method

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

An example of a method annotated with @AcpExceptionHandler. This method handles exceptions by returning a PromptResponse with an error message.

```java
@AcpExceptionHandler
PromptResponse handleError(Exception e) {
    return PromptResponse.text("Error: " + e.getMessage());
}
```

--------------------------------

### Authenticate Annotation Example

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Example of an authenticate request handler using the @Authenticate annotation. The method accepts an AuthenticateRequest and returns a new AuthenticateResponse.

```java
@Authenticate
AuthenticateResponse authenticate(AuthenticateRequest req) {
    return new AuthenticateResponse();
}
```

--------------------------------

### Hello World Agent (Async)

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/README.md

Demonstrates a basic asynchronous agent using Project Reactor. Suitable for reactive applications.

```java
import com.agentclientprotocol.sdk.agent.*;
import com.agentclientprotocol.sdk.agent.transport.*;
import com.agentclientprotocol.sdk.spec.AcpSchema.*;
import reactor.core.publisher.Mono;
import java.util.UUID;

var transport = new StdioAcpAgentTransport();

// Async agent — handlers return Mono
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 from the agent!")
            .then(Mono.just(PromptResponse.endTurn())))
    .build();

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

```

--------------------------------

### Asynchronous Agent Initialization and Handling

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/README.md

Demonstrates how to create and configure an asynchronous ACP agent using a reactive approach with Mono. Includes setting up initialization and prompt handlers.

```java
var transport = new StdioAcpAgentTransport();

AcpAsyncAgent agent = AcpAgent.async(transport)
    .initializeHandler(req -> Mono.just(InitializeResponse.ok()))
    .promptHandler((req, context) ->
        context.sendMessage("Processing...")
            .then(Mono.just(PromptResponse.endTurn())))
    .build();

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

--------------------------------

### Transport Selection Guide

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Transports.md

A guide to selecting the appropriate ACP transport based on different use cases, detailing the transport type and its corresponding module.

```APIDOC
## Transport Selection Guide

| Use Case | Transport |
|----------|-----------|
| Local agent subprocess | `StdioAcpClientTransport` |
| Remote agent server | `WebSocketAcpClientTransport` |
| Client subprocess | `StdioAcpAgentTransport` |
| Standalone WebSocket server | `WebSocketAcpAgentTransport` |
```

--------------------------------

### Hello World Agent (Sync)

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/README.md

Demonstrates a basic synchronous agent that responds to prompts. Use this for applications not requiring reactive programming.

```java
import com.agentclientprotocol.sdk.agent.*;
import com.agentclientprotocol.sdk.agent.transport.*;
import com.agentclientprotocol.sdk.spec.AcpSchema.*;
import java.util.UUID;

var transport = new StdioAcpAgentTransport();

// Sync agent — plain return values, no Mono
AcpSyncAgent agent = AcpAgent.sync(transport)
    .initializeHandler(req -> InitializeResponse.ok())
    .newSessionHandler(req ->
        new NewSessionResponse(UUID.randomUUID().toString(), null, null))
    .promptHandler((req, context) -> {
        context.sendMessage("Hello from the agent!");  // blocking void method
        return PromptResponse.endTurn();
    })
    .build();

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

```

--------------------------------

### Verify Tutorial Code Compilation

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/plans/DOCS-ROADMAP.md

Command to verify that all tutorial modules compile correctly before generating documentation.

```bash
cd ~/projects/acp-java-tutorial && ./mvnw compile -pl module-01-first-contact,module-05-streaming-updates,module-12-echo-agent,module-13-agent-handlers,module-14-sending-updates,module-15-agent-requests,module-16-in-memory-testing,module-28-zed-integration,module-29-jetbrains-integration,module-30-vscode-integration -q
```

--------------------------------

### build

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpClient.md

Creates an AcpSyncClient instance with the configured settings. This is the final step after setting up all handlers and consumers.

```APIDOC
## build()

### Description
Creates an AcpSyncClient instance with the configured settings.

### Method Signature
```java
AcpSyncClient build()
```

### Returns
* `AcpSyncClient` - The configured sync client instance.

### Example
```java
AcpSyncClient client = AcpClient.sync(transport)
    .requestTimeout(Duration.ofSeconds(30))
    .readTextFileHandler(req ->
        new ReadTextFileResponse(Files.readString(Path.of(req.path()))))
    .sessionUpdateConsumer(notification -> {
        System.out.println(notification);
    })
    .build();
```
```

--------------------------------

### Get Terminal Output

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/SyncPromptContext.md

Retrieves output from a terminal. Use this to get data produced by a running process in a terminal. The request includes the terminal ID and an optional chunk size.

```java
TerminalOutputResponse response = context.terminalOutput(
    new TerminalOutputRequest(terminalId, null));
System.out.println("Output: " + response.outputLine());
if (response.eof()) {
    System.out.println("Terminal finished");
}
```

--------------------------------

### Verify Tutorial Code Compilation

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/plans/DOCS-ROADMAP.md

Command to verify that tutorial code compiles before documenting it.

```bash
./mvnw compile -pl module-XX-* -q
```

--------------------------------

### Initialization Methods

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpAsyncClient.md

Methods for initializing the connection with the agent, including negotiating protocol versions and capabilities.

```APIDOC
## initialize(InitializeRequest)

### Description
Initializes the connection with the agent and negotiates protocol version and capabilities.

### Method
POST (Assumed, as it modifies state and takes a request body)

### Endpoint
/initialize (Assumed)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **initializeRequest** (`InitializeRequest`) - Required - Protocol version and client capabilities

### Request Example
```java
AcpSchema.InitializeResponse response = client
    .initialize(new AcpSchema.InitializeRequest(1, 
        new AcpSchema.ClientCapabilities()))
    .block();
```

### Response
#### Success Response (200)
- **InitializeResponse** (`AcpSchema.InitializeResponse`) - Response with agent capabilities

#### Response Example
(Response structure not provided in source)

**Throws:** `IllegalArgumentException` if request is null
```

```APIDOC
## initialize()

### Description
Initializes the connection with default settings (protocol version 1 and default capabilities).

### Method
POST (Assumed, as it modifies state)

### Endpoint
/initialize (Assumed)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **InitializeResponse** (`AcpSchema.InitializeResponse`) - Response with agent capabilities

#### Response Example
(Response structure not provided in source)

**Example:**
```java
client.initialize().block();
```
```

```APIDOC
## getAgentCapabilities()

### Description
Returns the capabilities negotiated with the agent during initialization.

### Method
GET (Assumed, as it retrieves information)

### Endpoint
/agentCapabilities (Assumed)

### Parameters
None

### Response
#### Success Response (200)
- **NegotiatedCapabilities** (`NegotiatedCapabilities`) - Negotiated capabilities, or null if not initialized

### Response Example
```java
NegotiatedCapabilities caps = client.getAgentCapabilities();
if (caps.supportsLoadSession()) {
    // Agent supports session persistence
}
```
```

--------------------------------

### Capability Negotiation for Client and Agent

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/README.md

Demonstrates how to check if a peer supports specific capabilities before using them, and how to require a capability, which throws an exception if not supported.

```java
// Client checking agent capabilities
NegotiatedCapabilities agentCaps = client.getAgentCapabilities();
if (agentCaps.supportsLoadSession()) {
    // Safe to use loadSession
}

// Agent checking client capabilities
NegotiatedCapabilities clientCaps = agent.getClientCapabilities();
if (clientCaps.supportsReadTextFile()) {
    context.readTextFile(...);
}

// Or require the capability (throws if not supported)
clientCaps.requireReadTextFile();
context.readTextFile(...);
```

--------------------------------

### Install ACP Test Dependency

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/acp-test/README.md

Add this dependency to your Maven project to include the testing utilities.

```xml
<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-test</artifactId>
    <version>0.9.0</version>
    <scope>test</scope>
</dependency>
```

--------------------------------

### Example Usage of @ListSessions

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Illustrates the use of the @ListSessions annotation on a method that handles ListSessionsRequest and returns ListSessionsResponse.

```java
@ListSessions
ListSessionsResponse listSessions(ListSessionsRequest req) {
    return new ListSessionsResponse(List.of(), null);
}
```

--------------------------------

### Example Usage of @SetSessionMode

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Demonstrates how to use the @SetSessionMode annotation on a method that accepts SetSessionModeRequest and returns SetSessionModeResponse.

```java
@SetSessionMode
SetSessionModeResponse setMode(SetSessionModeRequest req) {
    return new SetSessionModeResponse();
}
```

--------------------------------

### Install ACP Core Dependency

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/README.md

Add the acp-core dependency to your Maven project for core ACP functionality.

```xml
<dependency>
    <groupId>com.agentclientprotocol</groupId>
    <artifactId>acp-core</artifactId>
    <version>0.12.0</version>
</dependency>
```

--------------------------------

### Initialize Connection with Custom Settings

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpSyncClient.md

Initializes the connection with a specified protocol version and client capabilities. The call blocks until the agent responds.

```java
AcpSchema.InitializeResponse response = client
    .initialize(new AcpSchema.InitializeRequest(1, 
        new AcpSchema.ClientCapabilities()));
```

--------------------------------

### Annotation-Based Agent Creation and Bootstrap

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/README.md

Shows how to define an ACP agent using annotations for handlers like initialization, new sessions, and prompts. Includes bootstrapping the agent with a transport.

```java
@AcpAgent(name = "my-agent", version = "1.0")
class MyAgent {
    @Initialize
    InitializeResponse init() {
        return InitializeResponse.ok();
    }

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

    @Prompt
    PromptResponse handlePrompt(PromptRequest req, SyncPromptContext ctx) {
        ctx.sendMessage("Hello!");
        return PromptResponse.endTurn();
    }
}

// Bootstrap
AcpAgentSupport.create(new MyAgent())
    .transport(new StdioAcpAgentTransport())
    .run();
```

--------------------------------

### Example Usage of @ForkSession

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Illustrates the @ForkSession annotation on a method that accepts ForkSessionRequest and returns a new session ID.

```java
@ForkSession
ForkSessionResponse forkSession(ForkSessionRequest req) {
    return new ForkSessionResponse(UUID.randomUUID().toString());
}
```

--------------------------------

### initialize()

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpSyncClient.md

Initializes the connection with the agent using default settings (protocol version 1 and default capabilities). This method blocks until initialization is complete.

```APIDOC
## initialize()

### Description
Initializes the connection with default settings (protocol version 1 and default capabilities).

### Method
POST

### Endpoint
/initialize

### Response
#### Success Response (200)
- **InitializeResponse** (InitializeResponse) - Response with agent capabilities

### Request Example
```java
client.initialize();
```
```

--------------------------------

### Get Agent Capabilities

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpAsyncClient.md

Retrieves the capabilities negotiated with the agent during the initialization phase. Returns NegotiatedCapabilities or null if not initialized.

```java
NegotiatedCapabilities getAgentCapabilities()
```

```java
NegotiatedCapabilities caps = client.getAgentCapabilities();
if (caps.supportsLoadSession()) {
    // Agent supports session persistence
}
```

--------------------------------

### Get Agent Capabilities

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpSyncClient.md

Retrieves the capabilities that were negotiated with the agent during the initialization phase. Returns null if the client has not been initialized.

```java
NegotiatedCapabilities caps = client.getAgentCapabilities();
if (caps.supportsLoadSession()) {
    // Agent supports session persistence
}
```

--------------------------------

### Build AcpSyncClient Instance

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpClient.md

Creates an AcpSyncClient instance with the configured settings. This is the final step after configuring all handlers and options.

```java
AcpSyncClient client = AcpClient.sync(transport)
    .requestTimeout(Duration.ofSeconds(30))
    .readTextFileHandler(req ->
        new ReadTextFileResponse(Files.readString(Path.of(req.path()))))
    .sessionUpdateConsumer(notification -> {
        System.out.println(notification);
    })
    .build();
```

```java
AcpSyncClient build()
```

--------------------------------

### Minimal Sync Client Configuration

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/configuration.md

Sets up a basic synchronous ACP client using StdioAcpClientTransport.

```java
var params = AgentParameters.builder("agent").build();
var transport = new StdioAcpClientTransport(params);

AcpSyncClient client = AcpClient.sync(transport).build();
client.initialize();
```

--------------------------------

### Example Usage of @CloseSession

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Demonstrates using the @CloseSession annotation on a method that accepts CloseSessionRequest and a session ID, returning CloseSessionResponse.

```java
@CloseSession
CloseSessionResponse closeSession(CloseSessionRequest req, @SessionId String id) {
    cleanup(id);
    return new CloseSessionResponse();
}
```

--------------------------------

### Minimal Sync Agent Configuration

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/configuration.md

Sets up a basic synchronous ACP agent with a default prompt handler.

```java
var transport = new StdioAcpAgentTransport();

AcpSyncAgent agent = AcpAgent.sync(transport)
    .promptHandler((req, ctx) -> PromptResponse.endTurn())
    .build();

agent.run();
```

--------------------------------

### Initialize Connection with Default Settings

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpSyncClient.md

Initializes the connection to the agent using default protocol version and capabilities. This method blocks until the initialization is complete.

```java
client.initialize();
```

--------------------------------

### Example Usage of @SessionState

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Demonstrates using @SessionState to inject session-scoped state (SessionData) into a handler method, allowing stateful interactions.

```java
static class SessionData {
    private List<String> history = new ArrayList<>();
}

@AcpAgent
class Agent {
    @Prompt
    PromptResponse handle(PromptRequest req, 
                         @SessionState SessionData data) {
        data.history.add(req.content().get(0).toString());
        return PromptResponse.endTurn();
    }
}
```

--------------------------------

### initialize(InitializeRequest)

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpSyncClient.md

Initializes the connection with the agent, negotiating protocol version and capabilities. This method blocks until the initialization is complete.

```APIDOC
## initialize(InitializeRequest)

### Description
Initializes the connection with the agent and negotiates protocol version and capabilities. Blocks until complete.

### Method
POST

### Endpoint
/initialize

### Parameters
#### Request Body
- **initializeRequest** (InitializeRequest) - Required - Protocol version and client capabilities

### Response
#### Success Response (200)
- **InitializeResponse** (InitializeResponse) - Response with agent capabilities

### Throws
- AcpProtocolException on protocol error
- AcpConnectionException on transport error

### Request Example
```java
AcpSchema.InitializeResponse response = client
    .initialize(new AcpSchema.InitializeRequest(1, 
        new AcpSchema.ClientCapabilities()));
```
```

--------------------------------

### Configure Agent Handlers

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/configuration.md

Set up handlers for various agent interactions, including initialization, authentication, session management, and prompt processing. This allows the agent to respond to client requests.

```java
AcpSyncAgent agent = AcpAgent.sync(transport)
    .initializeHandler(req ->
        InitializeResponse.ok())
    .newSessionHandler(req ->
        new NewSessionResponse(UUID.randomUUID().toString(), null, null))
    .promptHandler((req, context) -> {
        context.sendMessage("Processing prompt...");
        String content = context.readFile("input.txt");
        return PromptResponse.text("Read: " + content);
    })
    .build();
```

--------------------------------

### Configure and Run Annotation-Based Agent

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/configuration.md

Shows how to configure and run an agent defined with annotations using AcpAgentSupport.

```java
@AcpAgent(name = "my-agent", version = "1.0")
class MyAgent {
    @Initialize
    InitializeResponse init() {
        return InitializeResponse.ok();
    }
    
    @Prompt
    PromptResponse handlePrompt(PromptRequest req, SyncPromptContext ctx) {
        return PromptResponse.endTurn();
    }
}

// Configure and run
AcpAgentSupport.create(new MyAgent())
    .transport(new StdioAcpAgentTransport())
    .run();
```

--------------------------------

### Example Usage of @Cancel

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/Annotations.md

Demonstrates using the @Cancel annotation on a method that accepts CancelNotification and a session ID, returning void or Mono<Void>.

```java
@Cancel
void cancelOperation(CancelNotification notif, @SessionId String id) {
    cancelWork(id);
}
```

--------------------------------

### build (Async)

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/_autodocs/api-reference/AcpClient.md

Creates an AcpAsyncClient instance with the configured settings. This is the final step in building the asynchronous client.

```APIDOC
## build()

### Description
Creates an AcpAsyncClient instance with the configured settings.

### Method Signature
```java
AcpAsyncClient build()
```

### Returns
`AcpAsyncClient` - The configured async client instance.

### Example
```java
AcpAsyncClient client = AcpClient.async(transport)
    .requestTimeout(Duration.ofSeconds(30))
    .readTextFileHandler(req -> ...)
    .sessionUpdateConsumer(notification -> ...)
    .build();
```
```

--------------------------------

### Define Handler Method Signatures

Source: https://github.com/agentclientprotocol/java-sdk/blob/main/acp-agent-support/README.md

Examples of flexible handler method signatures supported by the runtime, which automatically resolves parameters based on type.

```java
@Initialize
InitializeResponse init() { ... }

@Initialize
InitializeResponse init(InitializeRequest req) { ... }

@Prompt
PromptResponse answer(PromptRequest req) { ... }

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

@Prompt
PromptResponse answer(SyncPromptContext ctx, @SessionId String sessionId) { ... }

@Prompt
String simpleAnswer(PromptRequest req) { ... }  // Converted to PromptResponse

@Prompt
void streamingAnswer(PromptRequest req, SyncPromptContext ctx) { ... }  // Returns endTurn()

@Cancel
void onCancel(CancelNotification notification) { ... }
```