Google ADK를 사용하여 Java AI Agent 구축 및 배포하기

Debian 13 “Trixie”는 Java 에이전트 (agent) 개발을 위한 깨끗하고 안정적인 기반을 제공합니다. 워크스테이션 (workstation), 가상 머신 (virtual machine) 또는 클라우드 인스턴스 (cloud instance)에서 Java 프로젝트를 컴파일하고, 로컬 웹 서버를 실행하며, Google Agent Development Kit (ADK) Dev UI를 사용하고, 에이전트를 Google Cloud Run에 배포할 수 있습니다.

이 가이드는 시간 및 날씨 도구 (tools)를 사용하는 작은 ADK 에이전트를 구축합니다. 전체 프로젝트는 sample repository에서 확인할 수 있습니다.

1. Debian Trixie 준비하기

sudo를 실행할 수 있는 사용자 계정과 Debian 13 설치로 시작하세요. 운영 체제 (operating-system) 버전을 확인합니다:

. /etc/os-release
printf '%s %s (%s)\n' "$NAME" "$VERSION_ID" "$VERSION_CODENAME"

2. 필요한 도구 설치하기

패키지 인덱스를 업데이트하고 기본 개발 도구를 설치합니다:

sudo apt-get update
sudo apt-get install -y curl git maven unzip zip

이 프로젝트는 Java 25로 컴파일됩니다. 일치하는 JDK를 설치하는 편리한 방법 중 하나는 SDKMAN!입니다:

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk list java

목록에서 사용 가능한 Java 25 식별자를 선택하여 설치합니다 (예: 25-open):

sdk install java 25-open
java --version
mvn --version

두 명령 모두 Java 25를 보고해야 하며, Maven은 버전 3.6.3 이상이어야 합니다. 빌드 시 이 최소 Maven 버전을 강제합니다.

Google Cloud CLI 설치하기

Google의 Debian 패키지 저장소를 추가합니다:

sudo apt-get install -y apt-transport-https ca-certificates gnupg
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
...

설치를 확인합니다:

gcloud version

Google Cloud CLI는 Vertex AI 인증 및 Cloud Run 배포를 위해 필요합니다. Gemini API 키를 사용하여 에이전트를 로컬에서만 실행하는 경우에는 필요하지 않습니다.

3. 프로젝트 클론 및 검사

git clone https://github.com/xbill9/adk-hello-world-java
cd adk-hello-world-java

에이전트는 다음 위치에 존재합니다:
src/main/java/agents/multitool/MultiToolAgent.java.
이 에이전트의 공개(public) ROOT_AGENT 필드를 통해 ADK Dev UI가 이를 탐색할 수 있습니다:

public static final BaseAgent ROOT_AGENT = initAgent();

public static BaseAgent initAgent() {
...

도구(tools)들은 status와 사람이 읽을 수 있는 report를 포함하는 구조화된 맵(structured maps)을 반환합니다. 시간 도구(time tool)는 IANA 시간대(time zones)를 사용하며 San Francisco, Beijing, Mumbai와 같은 도시의 별칭(aliases)을 포함합니다.

현재 ADK Java 베이스라인 (baseline)

이 샘플은 2026년 7월 27일 기준 Maven Central에서 사용할 수 있는 최신 릴리스인 ADK for Java 1.7.0을 사용합니다. 두 런타임 의존성(runtime dependencies)은 동일한 속성(property)을 사용하므로, 코어 라이브러리(core library)와 Dev UI가 서로 다른 버전으로 어긋나는 것을 방지합니다:

<properties>
  <google-adk.version>1.7.0</google-adk.version>
</properties>
...

이 프로젝트와 관련된 최근 변경 사항은 다음과 같습니다:

Java 25 빌드 지원. ADK 1.6은 Spring AI 통합 및 빌드를 업데이트하여 Java 25와 호환되도록 했습니다.
더욱 신뢰할 수 있는 함수 도구 스트리밍 (function-tool streaming). ADK 1.6은 Gemini 스트리밍 함수 호출(function-call) 처리를 Python ADK와 일치시켰으며, 1.7 버전에서는 스트리밍된 함수 호출 인자(arguments)의 재조립(reassembly) 문제를 수정했습니다.
더 깔끔한 커맨드 라인 종료. ADK는 이제 공유 HTTP 클라이언트에 데몬 스레드(daemon threads)를 사용하여, CLI가 종료된 후에도 유휴(idle) HTTP 워커(workers)가 JVM을 계속 유지하는 것을 방지합니다.
더 안전한 로딩 및 세션. 최근 수정 사항을 통해 동적 클래스 로딩(dynamic class loading) 및 스킬 경로(skill paths)를 제한하고, VertexAiSessionService에서의 사용자 간 정보 노출을 방지합니다.
더 정확한 관측성 (observability). ADK 1.7은 gen_ai.usage.input_tokens에 도구 관련 토큰을 포함합니다.
Gemini 3 플로우(flow) 호환성. ADK 1.7은 Gemini 3 모델이 요구할 경우 강제 함수 호출(forced function calls)의 순서를 재정렬할 수 있습니다. 이 샘플은 안정적이고 널리 사용 가능한 튜토리얼 베이스라인을 위해 gemini-2.5-flash를 그대로 유지합니다.

이것은 프레임워크의 개선 사항이며, 샘플이 이를 재구현하는 것은 아닙니다. ADK 의존성(dependencies)을 1.7.0으로 고정(pinned)하여 애플리케이션에 적용합니다.

4. 인증 모드 선택

설정 스크립트를 실행하세요:

./init.sh

두 가지 모드를 제공합니다:

Gemini API 키: 로컬 개발용입니다. Google AI Studio에서 키를 생성하세요. 스크립트는 이를 사용자 전용 권한으로 ~/gemini.key에 저장합니다.
Vertex AI: 로컬 개발 및 Cloud Run용입니다. Google Cloud 프로젝트 ID를 입력하면, 스크립트가 gcloud 및 애플리케이션 기본 자격 증명 (Application Default Credentials, ADC)을 구성합니다.

선택된 모드는 ~/.adk-hello-world-java-auth에 저장됩니다. 모드를 전환하고 싶을 때마다 ./init.sh를 다시 실행하세요. 실행 스크립트가 set_env.sh를 자동으로 소스(source)하므로, 변수를 수동으로 내보내기(export)할 필요가 없습니다.

Vertex AI의 경우, 사용자의 계정과 Cloud Run 서비스 ID가 필요한 Vertex AI 권한을 가지고 있어야 합니다. Cloud Run은 런타임에 다운로드된 자격 증명 파일 대신 서비스 ID를 사용합니다.

5. 빌드, 테스트 및 린트 (lint)

프로젝트를 컴파일하고 8개의 JUnit Jupiter 테스트를 실행하세요:

make build
make test

테스트는 에이전트 초기화, 지원 및 미지원 도시, 시간대 별칭(time-zone aliases), 그리고 null 입력 등을 다룹니다. Checkstyle은 별도로 실행하세요:

make lint

린트(lint) 타겟은 Google Java Style 경고가 발견되면 실패하며, 이는 로컬 개발 및 지속적 통합 (Continuous Integration, CI)에서 유용하게 사용됩니다.

6. 커맨드 라인 에이전트 실행

./cli.sh

세션 예시:

You > What is the current time in Tokyo?
Agent > The current time in Tokyo is 08:24.

...

7. ADK Dev UI 사용

로컬 서버를 시작하세요:

./devui.sh

브라우저에서 http://127.0.0.1:8080을 여세요. ADK는 target/classes 아래의 Maven 출력물을 스캔하여 UI에서 multi_tool_agent를 사용할 수 있도록 합니다.

ADK Dev UI

web.sh 스크립트는 devui.sh의 별칭(alias)으로 유지됩니다.

ADK 1.6은 WebSocket 오리진(origin) 처리를 강화하였으며, Dev UI가 * CORS 기본값을 사용할 때 경고를 표시합니다. 해당 기본값은 로컬 개발에는 편리하지만, 공개 배포 시 접근 제어(access-control) 메커니즘으로 취급해서는 안 됩니다.

8. Cloud Run에 배포하기

Cloud Run 배포는 로컬 API 키를 서비스에 복사하는 대신 Vertex AI를 사용합니다. 만약 API 키 모드를 선택했다면, ./init.sh를 다시 실행하고 Vertex AI를 선택하세요.

그 다음 배포를 진행합니다:

./cloudrun.sh

이 스크립트는 us-central1 지역의 adk-hello-world-java 서비스를 위해 한 번의 소스 배포를 실행합니다. 저장소에 Dockerfile이 포함되어 있으므로, Cloud Run은 해당 Dockerfile을 원격으로 빌드합니다. 따라서 Debian 시스템에 Docker가 설치되어 있을 필요는 없습니다.

컨테이너는 Cloud Run의 PORT 환경 변수를 읽고 ADK 웹 서버를 시작합니다. 배포가 완료되면 gcloud가 서비스 URL을 출력합니다.

Cloud Run Console

서비스에 ADK Dev UI와 API가 포함되어 있기 때문에 배포는 기본적으로 비공개(private) 상태입니다. Cloud Run IAM을 사용하여 인증된 호출자를 구성하세요. 일회성 공개 데모를 위한 경우, cloudrun.sh에서 --no-allow-unauthenticated를 --allow-unauthenticated로 교체하십시오. 단, CORS를 접근 제어 수단으로 의존하지 마십시오.

프로젝트 구조

.
├── .dockerignore
├── .gcloudignore
...

요약

Debian Trixie는 Java ADK 에이전트를 로컬에서 구축하고 테스트하는 데 필요한 모든 것을 제공합니다.
이 샘플은 로컬 인증을 명시적으로 유지하고, JUnit을 통해 도구 로직을 검증하며, Checkstyle로 Java 스타일을 강제하고, Cloud Run에 배포될 때 Vertex AI 서비스 ID (service identity)를 사용합니다.

Insights