GitHub Copilot SDK for Java: Annotations, Virtual Threads, and BYOK for Enterprise Agent Harnesses

Last updated: August 11, 2026

On August 10, 2026, GitHub published the first deep engineering walkthrough of the Copilot SDK for Java, written by Ed Burns, the principal engineer who led the Java binding. The post is a build-in-public look at what the Java SDK actually does: @CopilotTool annotations that turn ordinary methods into agent tools, virtual-thread execution on JDK 25, a headless server mode with no IDE, and BYOK support that makes the whole runtime work against OpenAI, Anthropic, or any OpenAI-compatible endpoint with your own key - no Copilot subscription required.

The Java binding existed at the SDK's general availability in June. What is new in the weeks since is the shape of it: this is the first language binding documented around enterprise patterns rather than CLI parity, and it reframes how the Copilot runtime can be embedded in a Jakarta EE or Spring application.

Official Sources#

What Shipped#

The SDK is a Maven dependency: com.github:copilot-sdk-java at version 1.0.7-preview.1. Requirements are JDK 17 or 25 (25 recommended for virtual threads), Maven 3.9+, and the Copilot CLI at version 1.0.71 or later installed locally - Java, Go, and Rust are the three bindings where the CLI is not bundled as a dependency, so server environments need it on PATH. Under the hood every SDK in the family talks to the Copilot CLI over JSON-RPC; the client manages the process lifecycle.

The headline API is annotation-based tools:

@CopilotTool(value = "Sets the current phase of the agent. Use this to report progress.",
             name = "set_current_phase")
public String setCurrentPhase(
        @CopilotToolParam("The phase to transition to (VALIDATING, SEARCHING, ...)")
        String phaseName) {
    phase = Phase.valueOf(phaseName.trim().toUpperCase(Locale.ROOT));
    notifyUi();
    return "Phase set to " + phase.getLabel();
}

The SDK generates the JSON Schema, parses arguments, and dispatches calls. The annotation path is still experimental: the Maven build must pass -Acopilot.experimental.allowed=true to the compiler and register the SDK as an annotationProcessorPath, which generates $$CopilotToolMeta classes at compile time. Tools can also be defined inline with ToolDefinition.from(...) lambdas - including .overridesBuiltInTool(true) when you want to replace a built-in tool of the same name - and scanned from any object with ToolDefinition.fromObject(this), which is how tools registered in separate CDI beans are discovered.

Three things stand out for server-side use:

• One-line agentic loop. session.sendAndWait(escapedEnquiry).get() runs the full loop - reasoning, tool calls, re-prompting - and returns when the model is done. On a virtual thread the blocking wait costs no platform thread.
• Event streaming. session.on(event -> ...) fires every tool call, result, and assistant message, so you can build live UIs (the sample pushes status to a browser over Jakarta WebSocket) and log pipelines for observability.
• Least-privilege tool sets. sessionConfig.setAvailableTools(new ToolSet().addCustom("*").addBuiltIn("web_fetch")) opts in per session instead of exposing the full built-in surface (filesystem, shell). The sample uses PermissionHandler.APPROVE_ALL, and the post is explicit that production needs a real permission policy.

The BYOK Story Is the Bigger Change#

The walkthrough's most consequential claim is buried near the top: "Even though it's called GitHub Copilot SDK, you can use it with any direct model provider, such as OpenAI, Azure, Anthropic, or OpenAI-compatible endpoints, by passing a provider with your own baseUrl and apiKey. No Copilot subscription required."

That matches the SDK README, which lists BYOK as a first-class auth mode alongside GitHub OAuth and signed-in-user credentials. Limitations matter here: BYOK is key-based only, with no support for Entra ID, managed identities, or third-party identity providers - so enterprises on Azure-backed identity will still route through GitHub auth or wait. But for everyone else, the practical effect is that the agent runtime GitHub spent two years hardening for Copilot CLI is now a portable harness you can point at any provider your team already has accounts for. Our breakdown of Copilot CLI BYOK and AI credits covered the CLI side; this extends the same capability to server-side Java.

Why It Matters#

Enterprise Java has been the awkward guest in the agent SDK conversation. Options so far meant framework lock-in: Langchain4j disintermediates vendors but introduces its own dependency, and Spring AI ties you to Spring's design decisions. The Copilot SDK for Java deliberately sits underneath both - the sample app runs on Jakarta EE 11 with Open Liberty 26, and the post explicitly shows the Spring-compatible Executor integration point rather than a framework plugin.

The cleanest pattern in the walkthrough is the Executor hand-off: Open Liberty's ManagedThreadFactory with virtual="true" creates container-managed virtual threads that propagate CDI, JNDI, and transaction context. Pass that as the SDK's Executor, and a tool callback like searchProperties() can @Inject a JPA repository and query the database, because the container context survives the hop into the model's tool call. That is the difference between an agent harness you demo and one you can put behind a JPA transaction.

It also keeps the JVM's concurrency story intact. One CopilotClient per application (a @ApplicationScoped CDI singleton), N concurrent sendAndWait calls, each on its own virtual thread, and platform threads stay free for the request load. For teams whose blast radius is a Spring Boot service rather than a CLI, that is the deployment model that gets past architecture review.

What to Watch#

Three things are worth watching from here. First, whether the experimental annotation processor graduates - compile-time tool metadata generation is the sort of thing enterprise build teams will insist on being stable. Second, whether BYOK grows identity support beyond raw keys, since that decides whether large enterprises can adopt it at all. Third, the pattern of one language deep-dive per month: if GitHub follows the Java post with the same treatment for Go and Rust, the SDK is positioning itself less as a Copilot extension and more as a neutral agent runtime, which puts it in a different competitive lane than the SDK-vs-CLI-vs-Action tradeoffs we covered earlier.

FAQ#

Do I need a Copilot subscription to use the GitHub Copilot SDK for Java?#

No, not in BYOK mode. GitHub's walkthrough says you can use the SDK with any direct model provider, such as OpenAI, Azure, Anthropic, or OpenAI-compatible endpoints, by passing a provider with your own baseUrl and apiKey, with no Copilot subscription required. BYOK is key-based only, with no support for Entra ID, managed identities, or third-party identity providers.

What are the requirements for the Copilot SDK for Java?#

The SDK is the Maven dependency com.github:copilot-sdk-java at version 1.0.7-preview.1. It needs JDK 17 or 25 (25 recommended for virtual threads), Maven 3.9+, and the Copilot CLI at version 1.0.71 or later installed locally, because the Java binding does not bundle the CLI as a dependency.

How do @CopilotTool annotations work?#

Annotating a method with @CopilotTool and its parameters with @CopilotToolParam turns it into an agent tool: the SDK generates the JSON Schema, parses arguments, and dispatches calls. The annotation path is still experimental, so the Maven build must pass -Acopilot.experimental.allowed=true and register the SDK as an annotation processor. Tools can also be defined inline with ToolDefinition.from(...) or scanned from an object with ToolDefinition.fromObject(this).

Can the Copilot SDK for Java run inside Jakarta EE or Spring?#

Yes. The sample app runs on Jakarta EE 11 with Open Liberty 26, and the post shows a Spring-compatible Executor integration point rather than a framework plugin. Passing container-managed virtual threads as the SDK's Executor propagates CDI, JNDI, and transaction context, so a tool callback can inject a JPA repository and query the database.

Continue Reading#

• GitHub Copilot SDK Hits GA - the June GA post: all six language bindings, auth modes, and what the SDK exposes
• GitHub Copilot CLI, BYOK, and AI Credits - the cost-control side of BYOK and credit accounting
• Codex SDK vs CLI vs GitHub Action - when to embed an agent runtime vs drive it from a CLI
• Agents SDK Evolution - how the agent SDK landscape is consolidating
• Agent PR Governance with GitHub Copilot Review - what a governed agent pipeline looks like in practice
• OpenJDK Bans AI-Generated Code: What the New Policy Means for Java Contributors

Sources#

• Using the GitHub Copilot SDK for Java - GitHub Blog (fetched August 11, 2026)
• github/copilot-sdk - GitHub (fetched August 11, 2026)
• GitHub Copilot SDK Java API docs (fetched August 11, 2026)