Advanced Usage

Adding Rules

Use APPEND mode to add constraints while keeping default guardrails:

var session = client.createSession(
    new SessionConfig()
        .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()
        .setSystemMessage(new SystemMessageConfig()
            .setMode(SystemMessageMode.REPLACE)
            .setContent("You are a helpful coding assistant."))
).get();

API Key Authentication

var session = client.createSession(
    new SessionConfig()
        .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()
        .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.

Limitations

When using BYOK, be aware of these limitations:

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.isSuccess() 
        + ", tokens removed: " + data.getTokensRemoved());
});

For short conversations, disable to avoid overhead:

new InfiniteSessionConfig().setEnabled(false)

Loading Skills

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

var session = client.createSession(
    new SessionConfig()
        .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()
        .setSkillDirectories(List.of("/path/to/skills"))
        .setDisabledSkills(List.of("my-skill"))
).get();

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

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.