Copilot SDK for Java - Documentation

Simple Request-Response

For straightforward interactions, use sendAndWait():

var response = session.sendAndWait("What is the capital of France?").get();
System.out.println(response.getData().content());

Event-Based Processing

For more control, subscribe to events and use send():

Exception isolation: If a handler throws an exception, the SDK logs the error. By default, dispatch stops after the first handler error (PROPAGATE_AND_LOG_ERRORS). To continue dispatching to remaining handlers, set EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS. You can customize error handling with session.setEventErrorHandler() — see the Advanced Usage guide.

Symptoms of policy misconfiguration

• You registered multiple session.on(...) handlers, but only the first one runs
• A handler throws once and later handlers stop receiving events
• You expected “best effort” fan-out, but dispatch halts on errors

Fix

Set the event error policy to suppress-and-continue:

session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);

Optionally add a custom error handler for observability:

session.setEventErrorHandler((event, exception) -> {
    System.err.println("Handler failed for event " + event.getType() + ": " + exception.getMessage());
});

Use PROPAGATE_AND_LOG_ERRORS when you want fail-fast behavior.

var done = new CompletableFuture<Void>();

// Type-safe event handlers (recommended)
session.on(AssistantMessageEvent.class, msg -> {
    System.out.println("Response: " + msg.getData().content());
});

session.on(SessionErrorEvent.class, err -> {
    System.err.println("Error: " + err.getData().message());
});

session.on(SessionIdleEvent.class, idle -> {
    done.complete(null);
});

session.send("Tell me a joke").get();
done.get(); // Wait for completion

You can also use a single handler for all events:

session.on(event -> {
    switch (event) {
        case AssistantMessageEvent msg -> 
            System.out.println("Response: " + msg.getData().content());
        case SessionErrorEvent err -> 
            System.err.println("Error: " + err.getData().message());
        case SessionIdleEvent idle -> 
            done.complete(null);
        default -> { }
    }
});

Key Event Types

For the complete list of all event types, see Event Types Reference below.

Session Events

Assistant Events

Tool Events

User Events

Subagent Events

Other Events

External Tool Events

Permission Events

Command Events

Plan Mode Events

See the events package Javadoc for detailed event data structures.

Get Conversation History

Retrieve all messages and events from a session using getMessages():

var history = session.getMessages().get();

for (var event : history) {
    switch (event) {
        case UserMessageEvent user -> 
            System.out.println("User: " + user.getData().content());
        case AssistantMessageEvent assistant -> 
            System.out.println("Assistant: " + assistant.getData().content());
        case ToolExecutionCompleteEvent tool -> 
            System.out.println("Tool: " + tool.getData().toolCallId());
        default -> { }
    }
}

This is useful for:

• Displaying conversation history in a UI
• Persisting conversations for later review
• Debugging and logging session state

Abort Current Operation

Cancel a long-running operation using abort():

// Start a potentially long operation
var messageFuture = session.send("Analyze this large codebase...");

// User clicks cancel button
session.abort().get();

// The session will emit an AbortEvent
session.on(AbortEvent.class, evt -> {
    System.out.println("Operation was cancelled");
});

Use cases:

• User-initiated cancellation in interactive applications
• Timeout handling in automated pipelines
• Graceful shutdown when application is closing

Custom Timeout

Use sendAndWait with a custom timeout for CI/CD pipelines:

try {
    // 30-second timeout
    var response = session.sendAndWait(
        new MessageOptions().setPrompt("Quick question"),
        30000  // timeout in milliseconds
    ).get();
} catch (ExecutionException e) {
    if (e.getCause() instanceof TimeoutException) {
        System.err.println("Request timed out");
        session.abort().get();
    }
}

List Available Models

Query available models before creating a session:

var models = client.listModels().get();

for (var model : models) {
    System.out.printf("%s (%s)%n", model.getId(), model.getName());
}

Use a Specific Model

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("claude-sonnet-4")
).get();

Allowlist (Available Tools)

Restrict the session to only specific tools:

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setAvailableTools(List.of("read_file", "search_code", "list_dir"))
).get();

When availableTools is set, the assistant can only use tools in this list.

Blocklist (Excluded Tools)

Allow all tools except specific ones:

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setExcludedTools(List.of("execute_command", "write_file"))
).get();

Tools in the excludedTools list will not be available to the assistant.

Combining with Custom Tools

Tool filtering applies to built-in tools. Your custom tools (registered via setTools()) are always available:

var lookupTool = ToolDefinition.create("lookup_issue", "Fetch issue", schema, handler);

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setTools(List.of(lookupTool))           // Custom tool always available
        .setAvailableTools(List.of("read_file")) // Only allow read_file from built-ins
).get();

Checking Connection State

Query the client's connection state at any time without making a server call:

ConnectionState state = client.getState();
switch (state) {
    case CONNECTED -> System.out.println("Ready");
    case CONNECTING -> System.out.println("Starting up...");
    case DISCONNECTED -> System.out.println("Not connected");
    case ERROR -> System.out.println("Connection failed");
}

The four states are:

State Transitions

                 start()
  DISCONNECTED ──────────► CONNECTING
                               │
                    ┌──────────┼──────────┐
                    │ success  │          │ failure
                    ▼          │          ▼
              CONNECTED        │        ERROR
                    │          │
        stop() /    │          │
        forceStop() │          │
                    ▼          │
              DISCONNECTED ◄───┘
                    │
                    │ start()  (retry)
                    ▼
               CONNECTING

• DISCONNECTED → CONNECTING: start() was called
• CONNECTING → CONNECTED: Server connection and protocol handshake succeeded
• CONNECTING → ERROR: Connection or protocol verification failed
• CONNECTED → DISCONNECTED: stop() or forceStop() was called, or close() via try-with-resources
• DISCONNECTED → CONNECTING: start() can be called again to retry

Server Status

Get CLI version and protocol information:

var status = client.getStatus().get();
System.out.println("CLI version: " + status.getVersion());
System.out.println("Protocol version: " + status.getProtocolVersion());

Authentication Status

Check whether the current connection is authenticated and how:

var auth = client.getAuthStatus().get();
if (auth.isAuthenticated()) {
    System.out.println("Logged in as: " + auth.getLogin());
    System.out.println("Auth type: " + auth.getAuthType());
    System.out.println("Host: " + auth.getHost());
} else {
    System.out.println("Not authenticated: " + auth.getStatusMessage());
}

Ping

Verify server connectivity:

var pong = client.ping("hello").get();
System.out.println("Server responded, protocol version: " + pong.protocolVersion());

See ConnectionState, GetStatusResponse, and GetAuthStatusResponse Javadoc for details.

Multiple Concurrent Sessions

var session1 = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-4.1")
).get();

var session2 = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("claude-sonnet-4")
).get();

// Send messages concurrently
var future1 = session1.sendAndWait("Summarize REST APIs");
var future2 = session2.sendAndWait("Summarize GraphQL");

System.out.println("GPT: " + future1.get().getData().content());
System.out.println("Claude: " + future2.get().getData().content());

Resume a Previous Session

// Get the last session ID
var lastSessionId = client.getLastSessionId().get();

// Or list all sessions
var sessions = client.listSessions().get();

// Resume a session
var session = client.resumeSession(lastSessionId, new ResumeSessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)).get();

Resume Options

When resuming a session, you can optionally reconfigure many settings. This is useful when you need to change the model, update tool configurations, or modify behavior.

Example: Changing Model on Resume

// Resume with a different model
var config = new ResumeSessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    .setModel("claude-sonnet-4")    // Switch to a different model
    .setReasoningEffort("high");    // Increase reasoning effort

var session = client.resumeSession("user-123-task-456", config).get();

See ResumeSessionConfig Javadoc for complete options.

Clean Up Sessions

Closing a session releases its in-memory resources but preserves session data on disk, so it can be resumed later. Use deleteSession() to permanently remove session data from disk:

// Close a session (releases in-memory resources; session can be resumed later)
session.close();

// Permanently delete a session and all its data from disk (cannot be resumed)
client.deleteSession(sessionId).get();

Cloning SessionConfig

Use clone() to copy a base configuration before making per-session changes:

var base = new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    .setModel("gpt-4.1")
    .setStreaming(true);

var derived = base.clone()
    .setWorkingDirectory("/repo-a");

clone() creates a shallow copy. Collection fields are copied into new collection instances, while nested objects/handlers are shared references.

See SessionConfig Javadoc for full details.