GitHub Copilot SDK for Java는 Jakarta EE 환경에서 AI 에이전트를 프로덕션 애플리케이션에 직접 통합하는 프레임워크 중립적인 SDK다. Langchain4j나 Spring AI와 달리 특정 프레임워크에 락인되지 않으며, BYOK(Bring Your Own Key) 방식으로 OpenAI, Anthropic, Azure 등 다양한 AI 공급자를 지원한다. Maven 의존성 설정부터 어노테이션 기반 툴 등록, 에이전트 루프 실행까지 실제 부동산 리드 관리 시스템을 예시로 SDK 전체 흐름을 설명한다.
핵심 포인트- GitHub Copilot SDK for Java는 BYOK 방식으로 OpenAI, Anthropic, Azure 등 직접 모델 공급자를 지원하며, IDE 없이 Java 애플리케이션에 Copilot 기능을 통합한다.
- `@CopilotTool` 어노테이션으로 메서드를 툴로 선언하는 방식은 JAX-RS와 유사해 Java 개발자에게 익숙하며, 람다 기반 인라인 툴 정의도 지원한다.
- `session.sendAndWait()` 한 줄로 완전한 tool-calling 에이전트 루프를 실행한다.
- Jakarta EE의 `ManagedThreadFactory`를 통해 컨테이너 관리 가상 스레드와 통합하며 CDI/JNDI/트랜잭션 컨텍스트가 자동 전파된다.
- 샘플 앱은 QUEUED → VALIDATING → SEARCHING → WRITING_REPORT → DONE 상태 파이프라인으로 격리된 Copilot 에이전트가 고객 문의를 처리한다.
상세 정리- 배경: GitHub Copilot을 IDE 밖에서 서버 애플리케이션에 직접 통합하려는 Java 엔터프라이즈 개발자를 대상으로 하며, Jakarta EE 11 + Open Liberty 26.0.0.5 환경에서 검증됐다.
- 의존성: Maven에 `com.github:copilot-sdk-java:1.0.7-preview.1` 추가, JDK 17 또는 25(가상 스레드 권장), Copilot CLI 1.0.71 이상이 사전 조건이다.
- 어노테이션 기반 툴 등록: `@CopilotTool(value="...", name="...")` + `@CopilotToolParam`으로 메서드를 툴로 선언하며, `maven-compiler-plugin`에 어노테이션 프로세서 등록과 `-Acopilot.experimental.allowed=true` 컴파일러 플래그가 필수다.
- 람다 기반 툴: `ToolDefinition.from()` 빌더로 별도 메서드 없이 인라인 툴을 정의하며, `overridesBuiltInTool(true)`으로 SDK 내장 툴을 오버라이드할 수 있다.
- 시스템 메시지 커스터마이징: `SystemMessageConfig`의 `setSections()`으로 `IDENTITY` 등 특정 섹션만 REPLACE하거나 APPEND해 에이전트 동작을 세밀하게 제어한다.
- 에이전트 루프: `client.createSession(sessionConfig).get()` → `session.sendAndWait(enquiry).get()`으로 tool-calling 루프 전체를 두 줄에 실행한다.
- 실시간 이벤트 스트리밍: `session.on(event -> { captureSessionEvent(event); uiUpdateSocket.pushDetailUpdate(id); })`로 WebSocket 기반 실시간 UI 업데이트를 구현한다.
- Jakarta EE 통합: `ManagedThreadFactory`로 컨테이너 관리 가상 스레드를 `Executor`로 주입하며, CDI/JNDI/트랜잭션 컨텍스트가 자동 전파돼 Jakarta EE 생명주기 내에서 안전하게 동작한다.
- 툴 접근 제어: `ToolSet`으로 모든 커스텀 툴(`*`) 또는 특정 내장 툴(`web_fetch`)만 세션에 허용해 에이전트가 실행할 수 있는 작업 범위를 제한한다.
- 샘플 앱 구조: PrimeFaces 15 + H2 인메모리 DB 기반 부동산 리드 관리 시스템이며, 각 고객 문의를 격리된 에이전트 인스턴스가 상태 머신으로 처리한다.
왜 읽나Jakarta EE/Open Liberty 환경에서 IDE 독립적으로 Copilot AI 에이전트를 서버 애플리케이션에 통합하려는 Java 백엔드 엔지니어에게 전체 코드 흐름을 담은 실전 레퍼런스다.
GitHub Engineering·
Stack Overflow Blog·
LINE Engineering·
AWS Korea Tech·