Module 13: Agent Handlers

Implement all handler types that an ACP agent can provide.

What You’ll Learn

All five handler types: initialize, newSession, loadSession, prompt, cancel
Session tracking with ConcurrentHashMap
Logging to stderr (stdout is reserved for the protocol)

The Code

An ACP agent has five handler types. Three are required (initialize, newSession, prompt) and two are optional (loadSession, cancel). This example shows all five wired up with the sync builder API. Note that stdout is reserved for the JSON-RPC protocol — agent logging goes to stderr:

import com.agentclientprotocol.sdk.agent.*;
import com.agentclientprotocol.sdk.agent.transport.*;
import com.agentclientprotocol.sdk.spec.AcpSchema.*;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;

var sessions = new ConcurrentHashMap<String, String>();
var transport = new StdioAcpAgentTransport();

AcpSyncAgent agent = AcpAgent.sync(transport)

    .initializeHandler(req -> {
        System.err.println("Protocol version: " + req.protocolVersion());
        return InitializeResponse.ok();
    })

    .newSessionHandler(req -> {
        String sessionId = UUID.randomUUID().toString();
        sessions.put(sessionId, req.cwd());
        System.err.println("New session: " + sessionId);
        return new NewSessionResponse(sessionId, null, null);
    })

    .loadSessionHandler(req -> {
        System.err.println("Loading session: " + req.sessionId());
        return new LoadSessionResponse(List.of(), List.of());
    })

    .promptHandler((req, context) -> {
        context.sendMessage("Received: " + req.text());
        return PromptResponse.endTurn();
    })

    .cancelHandler(notification -> {
        System.err.println("Cancel requested for: " +
            notification.sessionId());
    })

    .build();

agent.run();

Handler Reference

Handler	Method	Required	Description
`initializeHandler`	`initialize`	Yes	Protocol handshake, capability exchange
`newSessionHandler`	`session/new`	Yes	Create session with working directory
`loadSessionHandler`	`session/load`	No	Resume an existing session by ID
`promptHandler`	`session/prompt`	Yes	Process user prompts
`cancelHandler`	`session/cancel`	No	Handle cancellation (fire-and-forget notification)

The cancelHandler receives a CancelNotification, not a request — it has no response. This is the JSON-RPC notification pattern: the client sends it and does not expect a reply.

Source Code

View on GitHub

Running the Example

./mvnw package -pl module-13-agent-handlers -q
./mvnw exec:java -pl module-13-agent-handlers

Next Module

Module 14: Sending Updates — send all types of session updates to clients.

Projects

AgentWorks

Agento

Supporting Projects

Migration

13 agent handlers

Module 13: Agent Handlers

What You’ll Learn

The Code

Handler Reference

Source Code

Running the Example

Next Module

​Module 13: Agent Handlers

​What You’ll Learn

​The Code

​Handler Reference

​Source Code

​Running the Example

​Next Module

Module 13: Agent Handlers

What You’ll Learn

The Code

Handler Reference

Source Code

Running the Example

Next Module