@AcpAgent(name = "my-agent", version = "1.0.0")
class MyAgent {

    @NewSession
    NewSessionResponse newSession(NewSessionRequest req) {
        return new NewSessionResponse("session-" + UUID.randomUUID(), null, null);
    }

    @Prompt
    PromptResponse prompt(PromptRequest req, SyncPromptContext ctx) {
        ctx.sendMessage("Processing your request...");
        ctx.sendMessage("Done!");
        return PromptResponse.endTurn();
    }
}

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

@AcpAgent(name = "notes-agent", version = "1.2.0", mcpHttp = true,
        authMethods = {
            @AuthMethod(id = "api-key", name = "API key", description = "Uses NOTES_API_KEY"),
            @AuthMethod(id = "login", name = "Log in", type = AuthMethod.Type.TERMINAL, args = "--login") })
class NotesAgent {

    @Authenticate AuthenticateResponse authenticate(AuthenticateRequest req) { ... }
    @Logout LogoutResponse logout() { ... }
    @LoadSession LoadSessionResponse load(LoadSessionRequest req) { ... }
    @ListSessions ListSessionsResponse list(ListSessionsRequest req) { ... }

    @Prompt(image = true, embeddedContext = true)
    PromptResponse prompt(PromptRequest req, SyncPromptContext ctx) { ... }
}

@ExtNotification("_example.com/models_changed")
void modelsChanged(ModelsChanged event, AcpSyncAgent agent) {
    agent.sendSessionUpdate(event.sessionId(),
            new ConfigOptionUpdate(configOptions(event.models())));
}

@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) { ... }  // Sent as an agent message chunk; the turn ends end_turn

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

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

@Prompt
PromptResponse handle(PromptRequest req, SyncPromptContext ctx) {
    // Get session info
    String sessionId = ctx.getSessionId();
    NegotiatedCapabilities caps = ctx.getClientCapabilities();

    // Send messages and thoughts
    ctx.sendMessage("Working on it...");
    ctx.sendThought("Let me analyze this...");

    // File operations (requires client capabilities)
    String content = ctx.readFile("/path/to/file.txt");
    ctx.writeFile("/path/to/output.txt", "content");

    // Optional file read (returns Optional)
    Optional<String> maybeContent = ctx.tryReadFile("/path/to/file.txt");

    // Ask for user permission
    boolean allowed = ctx.askPermission("Delete all files in /tmp?");

    // Multiple choice (empty if the user cancelled)
    Optional<String> choice = ctx.askChoice("Which format?", "JSON", "XML", "YAML");

    // Execute terminal commands (requires client capabilities)
    CommandResult result = ctx.execute("ls", "-la");
    if (result.success()) {
        ctx.sendMessage("Output: " + result.output());
    }

    return PromptResponse.endTurn();
}

String head = ctx.client()
    .readTextFile(new ReadTextFileRequest(ctx.getSessionId(), "/path/to/file.txt", 1, 20))
    .content();

@Prompt
PromptResponse handle(PromptRequest req, SyncPromptContext ctx) {
    for (Step step : plan(req)) {
        if (ctx.isCancelled()) {
            ctx.sendMessage("Stopped.");
            return PromptResponse.cancelled();
        }
        step.run(ctx);
    }
    return PromptResponse.endTurn();
}

@Prompt
Mono<PromptResponse> handle(PromptRequest req, PromptContext ctx) {
    return work(req, ctx)
        .takeUntilOther(ctx.whenCancelled())
        .defaultIfEmpty(PromptResponse.cancelled());
}

public class LoggingInterceptor implements AcpInterceptor {

    @Override
    public boolean preInvoke(AcpInvocationContext context) {
        log.info("Invoking: {}", context.getAcpMethod());
        return true;  // Continue processing
    }

    @Override
    public Object postInvoke(AcpInvocationContext context, Object result) {
        log.info("Result: {}", result);
        return result;
    }

    @Override
    public Object onError(AcpInvocationContext context, Throwable error) {
        log.error("Error in {}: {}", context.getAcpMethod(), error.getMessage());
        // Return null to keep the failure, return a replacement response, or throw an
        // AcpProtocolException to answer with that JSON-RPC error instead
        return null;
    }

    @Override
    public void afterCompletion(AcpInvocationContext context, Throwable ex) {
        // Called once for each call whose preInvoke returned true, however it ended;
        // ex is what the call failed with, or null
    }

    @Override
    public int getOrder() {
        return 0;  // Lower values execute first
    }
}

// Register interceptor
AcpAgentSupport.create(new MyAgent())
    .transport(transport)
    .interceptor(new LoggingInterceptor())
    .build();

public class UserResolver implements ArgumentResolver {

    @Override
    public boolean supportsParameter(AcpMethodParameter parameter) {
        return parameter.getParameterType() == User.class;
    }

    @Override
    public Object resolveArgument(AcpMethodParameter parameter, AcpInvocationContext context) {
        String sessionId = context.getSessionId().orElseThrow();
        return userService.findBySession(sessionId);
    }
}

// Register resolver
AcpAgentSupport.create(new MyAgent())
    .transport(transport)
    .argumentResolver(new UserResolver())
    .build();

public class FutureHandler implements ReturnValueHandler {

    @Override
    public boolean supportsReturnType(AcpMethodParameter returnType) {
        // Future itself only: a CompletableFuture stays with the built-in handler
        return returnType.getParameterType() == Future.class;
    }

    @Override
    public Object handleReturnValue(Object returnValue, AcpMethodParameter returnType,
            AcpInvocationContext context) {
        try {
            return ((Future<?>) returnValue).get();  // the method's response, such as a PromptResponse
        }
        catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new CancellationException("Interrupted while waiting for the handler's result");
        }
        catch (ExecutionException e) {
            throw new ReturnValueHandlingException("The handler's Future failed", e.getCause());
        }
    }
}

// Register handler
AcpAgentSupport.create(new MyAgent())
    .transport(transport)
    .returnValueHandler(new FutureHandler())
    .build();

AcpAgentSupport.create(new MyAgent())
    .transport(new StdioAcpAgentTransport())
    .run();

AcpAgentFactory agents = AcpAgentSupport.create(new MyAgent()).buildFactory();

var server = new StreamableHttpAcpAgentTransport(8080, AcpJsonMapper.createDefault(), agents);
server.start().block();  // http://localhost:8080/acp and ws://localhost:8080/acp

InMemoryTransportPair pair = InMemoryTransportPair.create();

AcpAgentSupport support = AcpAgentSupport.create(new MyAgent())
    .transport(pair.agentTransport())
    .build();

support.start();

// Create client using the paired transport
AcpAsyncClient client = AcpClient.async(pair.clientTransport()).build();

AcpAgentSupport.create(agentInstance)      // Start with agent instance
    .transport(transport)                   // Required: set transport
    .requestTimeout(Duration.ofSeconds(60)) // Optional: request timeout (default: 30s)
    .cancelGracePeriod(Duration.ofSeconds(10)) // Optional: time a cancelled prompt has to return (default: 60s)
    .maxPromptDuration(Duration.ofMinutes(5))  // Optional: longest a prompt may run (default: none)
    .interceptor(interceptor)               // Optional: add interceptor
    .argumentResolver(resolver)             // Optional: add custom resolver
    .returnValueHandler(handler)            // Optional: add custom handler
    .build();                               // Build the support instance

// From class (must have no-arg constructor)
AcpAgentSupport.create(MyAgent.class)

// With factory supplier
AcpAgentSupport.builder().agent(MyAgent.class, () -> new MyAgent(dependency))

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();

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

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

    @NewSession
    NewSessionResponse newSession(NewSessionRequest req) {
        String sessionId = UUID.randomUUID().toString();
        sessionHistory.put(sessionId, new ArrayList<>());
        return new NewSessionResponse(sessionId, null, null);
    }

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

    @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 (capabilities are null before initialize)
        NegotiatedCapabilities caps = ctx.getClientCapabilities();
        if (caps != null && caps.supportsReadTextFile()) {
            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(new StdioAcpAgentTransport())
            .interceptor(new MetricsInterceptor())
            .run();
    }
}

AcpAgent.sync(transport)
    .initializeHandler(req -> InitializeResponse.ok())
    .newSessionHandler(req -> new NewSessionResponse("session-1", null, null))
    .promptHandler((req, ctx) -> {
        ctx.sendMessage("Hello!");
        return PromptResponse.endTurn();
    })
    .build()
    .run();

@AcpAgent(name = "my-agent", version = "1.0")
class MyAgent {
    @NewSession NewSessionResponse newSession() { return new NewSessionResponse("session-1", null, null); }
    @Prompt PromptResponse prompt(SyncPromptContext ctx) {
        ctx.sendMessage("Hello!");
        return PromptResponse.endTurn();
    }
}

AcpAgentSupport.create(new MyAgent()).transport(transport).run();