devgo.cnJava 开发者想在应用里接入大模型，过去的选择多少有点憋屈：用 Langchain4j（一个封装了多家模型厂商的 Java AI 编排框架），虽然屏蔽了具体 AI 厂商，但你还是被这个框架牵着走；用 Spring AI（Spring 生态的 AI 集成框架），等于把设计决策也交给了 Spring。现在 GitHub Copilot SDK for Java 出现了，它是第一个真正框架无关的 Java AI 驱动方式，而且支持 BYOK（自带密钥，Bring Your Own Key），意味着你可以拿它接 OpenAI、Azure、Anthropic 或任何兼容 OpenAI 协议的端点，只需要在 ProviderConfig 里填自己的 baseUrl 和 apiKey。最反直觉的是，它叫 Copilot SDK，但你不需要 Copilot 订阅。
这个 SDK 本质上是一个客户端库，让服务端 Java 代码能以编程方式创建 Copilot Agent（一个由模型驱动的自主任务执行单元）会话、注册工具、发提示词、收结构化响应。它跑在 Jakarta EE（Java 企业版的开源规范集）和 Spring 等服务器环境里，而且 API 风格对老 Java 开发者很友好：CompletableFuture（Java 的异步结果容器，类似 Promise）、注解、lambda、虚拟线程（JVM 管理的轻量级线程，能大幅提升并发吞吐），都是熟悉的东西。Maven 坐标是 com.github:copilot-sdk-java:1.0.7-preview.1，前置要求 JDK 17 或 25（推荐 25）、Maven 3.9+、GitHub 账号带 Copilot 订阅、本地装 Copilot CLI 1.0.71+。虽然前置要求里列了 GitHub 账号和 Copilot CLI，但 BYOK 支持意味着你可以用任意直接模型提供商，不依赖 Copilot 订阅。
官方给了一个完整的 Jakarta EE 11 示例应用，技术栈是 Open Liberty（一个轻量级 Jakarta EE 应用服务器）26.0.0.5、Jakarta EE 11（包含 Faces 4.1、CDI 4.1、WebSocket 2.2、Data 1.0、Persistence 3.2）、PrimeFaces（一个 Java Web UI 组件库）15.0.16，数据库用 H2（一个纯 Java 的内存数据库），预置了 10 条房产数据。应用本身是一个房产线索管理 agent 管道：客户提交“我想找伦敦 80 万英镑以下的三居室”，系统就在一个虚拟线程上拉起一个隔离的 Copilot Agent，经过校验、搜索、写报告等阶段处理，阶段包括 VALIDATING、SEARCHING、WRITING_REPORT 等。
架构里用 Jakarta WebSocket（全双工通信协议，服务端可以主动推数据给浏览器）把服务端状态实时推到浏览器，所以你能在页面上看到 agent 在阶段间推进。同时提交多个查询，就能看到多个虚拟线程 agent 并发跑，每个都有独立的 Copilot 会话。
最值得看的是它如何把工具调用变成普通 Java 方法。用 @CopilotTool 注解声明一个方法为模型可调用的工具，@CopilotToolParam 描述每个参数，SDK 自动生成 JSON Schema（描述工具参数结构的规范，让模型知道该传什么参数）、解析参数、分发调用。比如 setCurrentPhase 方法，模型调用它来更新 agent 阶段。
这个注解 API 目前是实验特性，Maven 构建里要开 -Acopilot.experimental.allowed=true，并把 SDK 配成 annotationProcessorPath（Maven 编译器中配置注解处理器的路径），让编译期生成 $$CopilotToolMeta 元数据。如果你不想写独立方法，也可以用 ToolDefinition.from(...) 在调用点定义 lambda 工具，还支持 .overridesBuiltInTool(true) 覆盖内置工具。工具也不一定和 agent 逻辑同处一个类，可以放在 CDI（上下文和依赖注入，Jakarta EE 的依赖注入规范）bean 里，用 ToolDefinition.fromObject() 注册；示例里因为 CDI 代理（CDI 容器为 bean 生成的代理对象）会遮蔽注解元数据，所以用了 lambda 包装。
SDK 还允许细粒度控制系统消息，用 SystemMessageMode.CUSTOMIZE 可以只替换特定部分，保留其余内容。
这个 SDK 的启发在于，它把“AI 工具调用”抽象成了 Java 开发者熟悉的注解和 lambda，同时通过 BYOK 解耦了模型厂商。如果你在维护企业级 Java 应用，想接入 agent 能力又不想被框架绑架，可以直接拿 Maven 依赖试。要留意的是：注解工具 API 还是 preview，要开实验开关；JDK 25 推荐用，能解锁虚拟线程；另外示例里 CDI 代理的坑也提醒我们，注解元数据在代理场景下可能丢失，需要绕一下。整体上，这是 Java 生态里少见的“框架无关 + 厂商中立”的 AI 编程入口，值得关注。
内容与图片版权归原作者所有 · 原文: https://github.blog/engineering/using-the-github-copilot-sdk-for-java/