Advanced Usage

Overriding Built-in Tools

You can replace a built-in CLI tool (such as grep or read_file) with your own implementation by using ToolDefinition.createOverride(). This signals to the CLI that the name collision is intentional and your custom implementation should be used instead.

var customGrep = ToolDefinition.createOverride(
    "grep",
    "Project-aware search with custom filtering",
    Map.of(
        "type", "object",
        "properties", Map.of(
            "query", Map.of("type", "string", "description", "Search query")
        ),
        "required", List.of("query")
    ),
    invocation -> {
        String query = (String) invocation.getArguments().get("query");
        // Your custom search logic here
        return CompletableFuture.completedFuture("Results for: " + query);
    }
);

var session = client.createSession(
    new SessionConfig()
        .setTools(List.of(customGrep))
        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

Skipping Permission for Safe Tools

When a tool performs only read-only or non-destructive operations, you can mark it to skip the permission prompt entirely using ToolDefinition.createSkipPermission():

var safeLookup = ToolDefinition.createSkipPermission(
    "safe_lookup",
    "Look up a record by ID (read-only, no side effects)",
    Map.of(
        "type", "object",
        "properties", Map.of(
            "id", Map.of("type", "string")
        ),
        "required", List.of("id")
    ),
    invocation -> {
        String id = (String) invocation.getArguments().get("id");
        return CompletableFuture.completedFuture("Record: " + lookupRecord(id));
    }
);

The CLI bypasses the permission request for this tool invocation, so no PermissionRequestedEvent is emitted and the onPermissionRequest handler is not called.

See ToolDefinition Javadoc for details.

Adding Rules

Use APPEND mode to add constraints while keeping default guardrails:

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setSystemMessage(new SystemMessageConfig()
            .setMode(SystemMessageMode.APPEND)
            .setContent("""
                <rules>
                - Always check for security vulnerabilities
                - Suggest performance improvements
                </rules>
            """))
).get();

Full Control

Use REPLACE mode for complete control (removes default guardrails):

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setSystemMessage(new SystemMessageConfig()
            .setMode(SystemMessageMode.REPLACE)
            .setContent("You are a helpful coding assistant."))
).get();

Fine-grained Customization

Use CUSTOMIZE mode to override individual sections of the default system prompt without replacing it entirely. You can replace, remove, append, prepend, or transform specific sections using the section identifiers from SystemPromptSections.

Static overrides:

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setSystemMessage(new SystemMessageConfig()
            .setMode(SystemMessageMode.CUSTOMIZE)
            .setSections(Map.of(
                // Replace the tone section
                SystemPromptSections.TONE,
                    new SectionOverride()
                        .setAction(SectionOverrideAction.REPLACE)
                        .setContent("Be concise and formal in all responses."),
                // Remove the code-change-rules section entirely
                SystemPromptSections.CODE_CHANGE_RULES,
                    new SectionOverride()
                        .setAction(SectionOverrideAction.REMOVE)
            ))
            // Optional: extra content appended after all sections
            .setContent("Always mention quarterly earnings."))
).get();

Transform callbacks let you inspect and modify section content at runtime:

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setSystemMessage(new SystemMessageConfig()
            .setMode(SystemMessageMode.CUSTOMIZE)
            .setSections(Map.of(
                SystemPromptSections.IDENTITY,
                    new SectionOverride()
                        .setTransform(content ->
                            CompletableFuture.completedFuture(
                                content + "\nAlways end your reply with DONE."))
            )))
).get();

See SystemMessageConfig, SectionOverride, and SystemPromptSections Javadoc for details.

Inline Blob Attachments

Use BlobAttachment to pass inline base64-encoded binary data — for example, an image captured at runtime — without writing it to disk first:

// Load image bytes and base64-encode them
byte[] imageBytes = Files.readAllBytes(Path.of("/path/to/screenshot.png"));
String base64Data = Base64.getEncoder().encodeToString(imageBytes);

session.send(new MessageOptions()
    .setPrompt("Describe this screenshot")
    .setAttachments(List.of(
        new BlobAttachment()
            .setData(base64Data)
            .setMimeType("image/png")
            .setDisplayName("screenshot.png")
    ))
).get();

See BlobAttachment Javadoc for details.

Both Attachment and BlobAttachment implement the sealed MessageAttachment interface. For a mixed list with both types, use an explicit type hint:

session.send(new MessageOptions()
    .setPrompt("Analyze these")
    .setAttachments(List.<MessageAttachment>of(
        new Attachment("file", "/path/to/file.java", "Source"),
        new BlobAttachment()
            .setData(base64Data)
            .setMimeType("image/png")
            .setDisplayName("screenshot.png")
    ))
).get();

API Key Authentication

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setProvider(new ProviderConfig()
            .setType("openai")
            .setBaseUrl("https://api.openai.com/v1")
            .setApiKey("sk-..."))
).get();

Bearer Token Authentication

Some providers require bearer token authentication instead of API keys:

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setProvider(new ProviderConfig()
            .setType("openai")
            .setBaseUrl("https://my-custom-endpoint.example.com/v1")
            .setBearerToken(System.getenv("MY_BEARER_TOKEN")))
).get();

Note: The bearerToken option accepts a static token string only. The SDK does not refresh this token automatically. If your token expires, requests will fail and you'll need to create a new session with a fresh token.

Microsoft Foundry Local

Microsoft Foundry Local lets you run AI models locally on your own device with an OpenAI-compatible API. Install it via the Foundry Local CLI, then point the SDK at your local endpoint:

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setProvider(new ProviderConfig()
            .setType("openai")
            .setBaseUrl("http://localhost:<PORT>/v1"))
            // No apiKey needed for local Foundry Local
).get();

Note: Foundry Local starts on a dynamic port — the port is not fixed. Use foundry service status to confirm the port the service is currently listening on, then use that port in your baseUrl.

To get started with Foundry Local:

# Windows: Install Foundry Local CLI (requires winget)
winget install Microsoft.FoundryLocal

# macOS / Linux: see https://foundrylocal.ai for installation instructions

# List available models
foundry model list

# Run a model (starts the local server automatically)
foundry model run phi-4-mini

# Check the port the service is running on
foundry service status

Limitations

When using BYOK, be aware of these limitations:

Manual Compaction

Trigger compaction immediately when you want to reduce context usage before the automatic threshold is reached:

session.compact().get();

Compaction Events

When compaction occurs, the session emits events that you can listen for:

session.on(SessionCompactionStartEvent.class, start -> {
    System.out.println("Compaction started");
});
session.on(SessionCompactionCompleteEvent.class, complete -> {
    var data = complete.getData();
    System.out.println("Compaction completed - success: " + data.success() 
        + ", tokens removed: " + data.tokensRemoved());
});

For short conversations, disable to avoid overhead:

new InfiniteSessionConfig().setEnabled(false)

Configuration Options

Multiple Agents

Register multiple agents for different tasks:

var agents = List.of(
    new CustomAgentConfig()
        .setName("reviewer")
        .setDescription("Code review")
        .setPrompt("You review code for issues."),
    new CustomAgentConfig()
        .setName("documenter")
        .setDescription("Documentation writer")
        .setPrompt("You write clear documentation.")
        .setInfer(true)  // Auto-select when appropriate
);

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setCustomAgents(agents)
).get();

See CustomAgentConfig Javadoc for full details.

Programmatic Agent Selection

You can inspect and switch agents at runtime:

var available = session.listAgents().get();

var current = session.getCurrentAgent().get();
if (current != null) {
    System.out.println("Current agent: " + current.name());
}

var selected = session.selectAgent("reviewer").get();
System.out.println("Selected: " + selected.name());

session.deselectAgent().get(); // Return to the default agent

Loading Skills

Skills are loaded from SKILL.md files in subdirectories of the specified skill directories:

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setSkillDirectories(List.of("/path/to/skills"))
).get();

Each skill subdirectory should contain a SKILL.md file with YAML frontmatter:

---
name: my-skill
description: A skill that provides domain-specific knowledge
---

# Skill Instructions

Your skill instructions go here...

Disabling Skills

Disable specific skills by name:

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setSkillDirectories(List.of("/path/to/skills"))
        .setDisabledSkills(List.of("my-skill"))
).get();

Graceful Stop vs Force Stop

The SDK provides two shutdown methods:

Use stop() for normal shutdown — it ensures each session is properly closed (flushing pending operations) before terminating the connection:

// Graceful: closes all sessions, then disconnects
client.stop().get();

Use forceStop() when you need to terminate immediately, such as during error recovery or when the server is unresponsive:

// Immediate: skips session cleanup, kills connection
client.forceStop().get();

Tip: In try-with-resources blocks, close() delegates to stop(), so graceful session cleanup happens automatically. close() is blocking and waits up to CopilotClient.AUTOCLOSEABLE_TIMEOUT_SECONDS seconds for shutdown to complete.

Listing Sessions with Context

Session metadata may include context information for persisted sessions:

var sessions = client.listSessions().get();
for (var session : sessions) {
    var context = session.getContext();
    if (context != null) {
        System.out.println("Session: " + session.getSessionId());
        System.out.println("  Working dir: " + context.getCwd());
        System.out.println("  Repository: " + context.getRepository());
        System.out.println("  Branch: " + context.getBranch());
        System.out.println("  Git root: " + context.getGitRoot());
    }
}

Filtering Sessions by Context

Use SessionListFilter to filter sessions by context fields:

// Find sessions for a specific repository
var filter = new SessionListFilter()
    .setRepository("owner/myproject")
    .setBranch("main");

var sessions = client.listSessions(filter).get();

Filter options:

• setCwd(String) - Filter by exact working directory match
• setGitRoot(String) - Filter by git repository root
• setRepository(String) - Filter by repository in “owner/repo” format
• setBranch(String) - Filter by git branch name

Context Changed Events

Listen for changes to the working directory context:

session.on(SessionContextChangedEvent.class, event -> {
    var newContext = event.getData();
    System.out.println("Context changed:");
    System.out.println("  New CWD: " + newContext.getCwd());
    System.out.println("  Repository: " + newContext.getRepository());
    System.out.println("  Branch: " + newContext.getBranch());
});

The session.context_changed event fires when the working directory context changes between conversation turns.

Subscribing to All Lifecycle Events

var subscription = client.onLifecycle(event -> {
    System.out.println("Session " + event.getSessionId() + ": " + event.getType());
    
    if (event.getMetadata() != null) {
        System.out.println("  Summary: " + event.getMetadata().getSummary());
    }
});

// Later, when done listening:
subscription.close();

Subscribing to Specific Event Types

import com.github.copilot.sdk.json.SessionLifecycleEventTypes;

// Listen only for session creation
var subscription = client.onLifecycle(
    SessionLifecycleEventTypes.CREATED,
    event -> System.out.println("New session: " + event.getSessionId())
);

Available event types:

• SessionLifecycleEventTypes.CREATED - Session was created
• SessionLifecycleEventTypes.DELETED - Session was deleted
• SessionLifecycleEventTypes.UPDATED - Session was updated
• SessionLifecycleEventTypes.FOREGROUND - Session moved to foreground (TUI+server mode)
• SessionLifecycleEventTypes.BACKGROUND - Session moved to background (TUI+server mode)

Getting the Foreground Session

var sessionId = client.getForegroundSessionId().get();
if (sessionId != null) {
    System.out.println("TUI is displaying session: " + sessionId);
}

Setting the Foreground Session

client.setForegroundSessionId("session-123").get();

Event Handler Exceptions

If an event handler registered via session.on() throws an exception, the SDK catches it and logs it at WARNING level. By default, dispatch stops after the first handler error (PROPAGATE_AND_LOG_ERRORS policy). You can opt in to continue dispatching despite errors using SUPPRESS_AND_LOG_ERRORS:

// With SUPPRESS_AND_LOG_ERRORS, second handler still runs
session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);

session.on(AssistantMessageEvent.class, msg -> {
    throw new RuntimeException("bug in handler 1");
});

session.on(AssistantMessageEvent.class, msg -> {
    // This handler executes normally despite the exception above
    System.out.println(msg.getData().content());
});

Errors are always logged at WARNING level regardless of the policy or whether a custom error handler is set.

Custom Event Error Handler

Set a custom EventErrorHandler for additional handling beyond the default logging — such as metrics, alerts, or integration with external error-reporting systems:

session.setEventErrorHandler((event, exception) -> {
    metrics.increment("handler.errors");
    logger.error("Handler failed on {}: {}",
        event.getType(), exception.getMessage());
});

The error handler receives both the event that was being dispatched and the exception that was thrown. If the error handler itself throws, that exception is caught and logged at SEVERE, and dispatch is stopped to prevent cascading failures.

Pass null to use only the default logging behavior:

session.setEventErrorHandler(null);

Event Error Policy

By default, the SDK propagates errors and stops dispatch on the first handler error (EventErrorPolicy.PROPAGATE_AND_LOG_ERRORS). You can opt in to suppress errors so that all handlers execute despite errors:

session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);

The EventErrorHandler (if set) is always invoked regardless of the policy — the policy only controls whether remaining handlers execute after the error handler returns. Errors are always logged at WARNING level.

You can combine both for full control:

// Log errors via custom handler and suppress (continue dispatching)
session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);
session.setEventErrorHandler((event, ex) ->
    logger.error("Handler failed, continuing: {}", ex.getMessage(), ex));

Or switch policies dynamically:

// Start strict (propagate errors, stop dispatch)
session.setEventErrorPolicy(EventErrorPolicy.PROPAGATE_AND_LOG_ERRORS);

// Later, switch to lenient mode (suppress errors, continue)
session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);

See EventErrorPolicy and EventErrorHandler Javadoc for details.