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

Event-Based Processing

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

var done = new CompletableFuture<Void>();

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

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

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().getContent());
        case SessionErrorEvent err -> 
            System.err.println("Error: " + err.getData().getMessage());
        case SessionIdleEvent idle -> 
            done.complete(null);
        default -> { }
    }
});

Key Event Types

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

Session Events

Assistant Events

Tool Events

User Events

Subagent Events

Other Events

See the events package Javadoc for detailed event data structures.

Get Conversation History

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

List<AbstractSessionEvent> history = session.getMessages().get();

for (AbstractSessionEvent event : history) {
    switch (event) {
        case UserMessageEvent user -> 
            System.out.println("User: " + user.getData().getContent());
        case AssistantMessageEvent assistant -> 
            System.out.println("Assistant: " + assistant.getData().getContent());
        case ToolExecutionCompleteEvent tool -> 
            System.out.println("Tool: " + tool.getData().getToolName());
        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:

List<ModelInfo> models = client.listModels().get();

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

Use a Specific Model

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

Multiple Concurrent Sessions

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

var session2 = client.createSession(
    new SessionConfig().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().getContent());
System.out.println("Claude: " + future2.get().getData().getContent());

Resume a Previous Session

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

// Or list all sessions
List<SessionMetadata> sessions = client.listSessions().get();

// Resume a session
var session = client.resumeSession(lastSessionId).get();

Clean Up Sessions

// Delete a specific session
client.deleteSession(sessionId).get();