GitHub Copilot SDK for Java now available—framework and vendor agnostic

The GitHub Copilot SDK for Java is a client library designed to let Java developers build AI agents without vendor lock-in or framework coupling. It is available as a Maven dependency (com.github:copilot-sdk-java:1.0.7-preview.1) and requires JDK 17 or 25 (with 25 recommended for virtual threads), Maven 3.9 or later, a GitHub account with an active Copilot subscription, and the Copilot CLI version 1.0.71 or later.

The SDK can use any AI model provider—OpenAI, Azure, Anthropic, or any OpenAI-compatible endpoint—by passing a provider configuration with a custom baseUrl and apiKey or bearer token. No Copilot subscription is required if you provide your own model credentials. The core capability is creating Copilot agent sessions, registering tools, sending prompts, and receiving structured responses, all from server-side Java code. The SDK works in both Jakarta EE and Spring environments and uses standard Java patterns: CompletableFuture for async operations, annotations for declarative tool definition, lambdas for inline tool handlers, and virtual threads for scalable concurrency.

The article includes a complete sample application: a real-estate lead-management agent built on Open Liberty 26.0.0.5 (the platform runtime), Jakarta EE 11 (with Faces 4.1, CDI 4.1, WebSocket 2.2, Data 1.0, and Persistence 3.2), PrimeFaces 15.0.16 (for the UI), and an H2 in-memory database with 10 seed property listings. The application accepts customer enquiries (e.g., "I'm looking for a 3-bedroom house in London under £800,000") and spins up an isolated agent on a virtual thread to process each one through a pipeline: validating the request, searching the database for matching properties, and writing a report. Status updates are pushed to the browser in real time via Jakarta WebSocket so users can watch agents progress through phases as the model calls tools.

The SDK exposes tools in two ways. The headline API uses the @CopilotTool annotation on a method, which feels familiar to JAX-RS endpoint authors: @CopilotTool declares the method as callable by the model, and @CopilotToolParam describes each parameter so the model knows what to pass. The SDK generates JSON Schema, argument parsing, and dispatch automatically. Using annotations requires two Maven build steps: passing -Acopilot.experimental.allowed=true to the compiler (because the annotation API is experimental) and registering the SDK as an annotationProcessorPath so the compiler can generate $$CopilotToolMeta classes at compile time. Alternatively, developers can define tools inline using lambda-style ToolDefinition.from(...), useful for tools defined at the call site; this approach also supports .overridesBuiltInTool(true) to replace a built-in tool with custom behavior. Tools can be scattered across multiple classes and registered via ToolDefinition.fromObject(...).

The SDK lets developers customize the system message using SystemMessageConfig with SystemMessageMode.CUSTOMIZE, which lets you replace specific sections (e.g., IDENTITY) while keeping safety guardrails intact, or SystemMessageMode.APPEND to add content after the default message. The agent loop itself is simple: session.sendAndWait(enquiry).get() launches the full agentic loop—the model reasons, calls registered tools (potentially multiple times), and returns its final response. On a virtual thread, .get() is non-blocking and does not consume a platform thread while waiting. Developers can subscribe to real-time session events (session.on(...)) to build responsive UIs; events include tool calls, results, and assistant messages, and can be handled using pattern matching (e.g., if (event instanceof AssistantMessageEvent msg)).

For server-side operation, the client is configured in headless mode (CopilotClientMode.EMPTY) so it talks directly to the Copilot CLI without IDE integration. A custom Executor ensures tool callbacks run with container context. Permission handling uses a sessionConfig.setOnPermissionRequest(...) callback; the sample uses PermissionHandler.APPROVE_ALL for development, but production systems should implement a real permission policy. Jakarta EE integration is central: the SDK composes naturally with Jakarta Concurrency, using a ManagedThreadFactory (configured in server.xml with the virtual attribute) so the container can track threads, apply concurrency policies, and propagate context automatically without manual work.