에이전트 엔지니어링 — 참조 구현 (Java 21)

한국어 기술서 『에이전트 엔지니어링』의 참조 구현입니다. 책은 설계서이고 돌아가는 코드는 여기 있습니다 — 본문은 계약과 배선도만 싣고, 전체 리스팅은 이 저장소가 받습니다.

두 디렉터리와 그 지위

디렉터리	무엇인가
base/	1권 『밑바닥부터 만드는 코딩 에이전트』 최종 산출물 ch25의 사본. 2권은 여기를 고치지 않습니다
plus/	2권이 새로 얹는 것 — 그래프 런타임과 평가 하네스, 이 둘뿐

base/                      1권이 이미 제공한 것
├── agent-core/            엔진 · 컨텍스트 · 도구 · 권한 · 서브에이전트
└── agent-cli/             REPL · 렌더링 · 부트스트랩

plus/                      2권이 새로 얹는 것
└── src/main/java/plus/
    ├── graph/             그래프 런타임
    ├── eval/              평가 하네스
    └── trace/             평가가 읽는 원자료

1권 코드 전체(ch02~ch25 장별 스냅샷)는 별도 저장소 https://github.com/kangwoo/build-a-coding-agent 에 있습니다. 여기 base/는 그중 마지막 스냅샷 하나입니다.

base/를 고치지 않는 이유는 2권이 1권 코드를 고치는 책이 아니기 때문입니다. 본문의 설계 주장이 이미 있는 코드에서 어떻게 성립하는가를 짚는 것이지, 주장에 맞게 코드를 고치는 것이 아닙니다.

⟦더하기⟧가 둘로 봉인된 이유는 이 둘이 「나눈다」와 「잰다」의 유일한 존재 증명이기 때문입니다. 셋째 덩어리는 늘리지 않습니다.

그리고 plus는 base의 agent.*를 하나도 import하지 않습니다. 이것은 편의를 위한 분리가 아니라 설계 주장의 물증입니다 — 한 층을 가짜로 바꿔 끼울 수 있어야 그 층이 뜻을 가집니다. 둘은 서로 컴파일 의존이 없는 독립 빌드이므로 하나로 묶지 마십시오.

빌드와 시험

JDK 21만 있으면 되고 Gradle 전역 설치는 필요 없습니다. 둘 다 API 키 없이 통과합니다 — 통과에 키가 필요하면 그 시험은 실행 결과가 아니라 네트워크를 재고 있는 것입니다.

(cd base && env -u JAVA_TOOL_OPTIONS ./gradlew test)   # 40개 클래스 167개
(cd plus && env -u JAVA_TOOL_OPTIONS ./gradlew test)   # 10개 클래스 80개

env -u JAVA_TOOL_OPTIONS를 붙이는 이유는 코드와 무관합니다. 셸이 그 변수를 export해 두면(예: -Xmx4g) Gradle이 포크한 시험 JVM이 그것을 물려받아, 시험이 하나도 돌기 전에 Process 'Gradle Test Executor N' finished with non-zero exit value 1로 죽습니다.

base에서 GrepToolTest·GlobToolTest의 4건이 건너뛰어질 수 있습니다. @EnabledIf가 rg(ripgrep)와 fd의 존재를 보고 판단하기 때문이고, 키와는 무관합니다. 두 명령을 설치하면 함께 돕니다.

BUILD SUCCESSFUL을 결과로 읽지 마십시오. 시험이 하나도 안 돌아도 그 줄은 나옵니다 — 실제 건수는 build/test-results/test/*.xml에 있습니다.

실제 LLM 호출은 base의 ./gradlew run에서만 일어나고, 그때만 ANTHROPIC_API_KEY 같은 환경변수가 필요합니다.

책의 어디를 보나

부록 J(참조 구현) 가 이 저장소의 안내서입니다. 여덟 층이 실제로 어느 패키지에 앉는지의 대응표, 두 덩어리의 배선도, 그리고 이 코드가 못 하는 것 목록이 거기 있습니다. 마지막 것이 특히 부록에만 있습니다 — 지면에 적을 수 없던 한계 넷이 코드를 짜다가 나왔고, 부록 J가 그것을 적고 있습니다.