구글 ADK 사용법: 5개 언어 에이전트 개발 키트 설치·배포 정리

구글 ADK(Agent Development Kit)는 AI 에이전트를 코드로 만들고 평가·배포하는 오픈소스 개발 키트로, 2026년 10월 14일 구글 클라우드가 파이썬, Go, 타입스크립트, 자바, 코틀린 5개 언어를 같은 키트로 지원한다고 정리했다. 쓰던 언어 그대로 에이전트를 만들 수 있고, 만든 에이전트는 Cloud Run에 올려 서비스할 수 있다. 아래에서 언어 고르는 기준, 시작 명령, Cloud Run 배포 순서를 차례로 본다.

구글 ADK란 무엇이고 5개 언어는 무엇이 같은가

ADK 공식 문서는 ADK를 에이전트를 만들고 디버깅하고 배포하기 위한 오픈소스 프레임워크로 소개한다. 여러 에이전트를 순서대로, 병렬로, 반복해서 돌리는 구성과 세션·메모리 관리, 평가와 관측 기능이 들어 있다. 모델은 제미나이를 비롯해 여러 모델에 연결할 수 있다.

언어가 달라도 두 가지 규격은 공통이다. 구글 클라우드 블로그에 따르면 5개 언어 모두 MCP(AI가 외부 도구를 부르는 공통 규격) 클라이언트를 갖고 있어 MCP 도구를 어느 언어에서나 부를 수 있다. 에이전트끼리 HTTP로 대화하는 A2A 규격도 지원해서, 파이썬으로 만든 에이전트와 Go로 만든 에이전트가 서로 호출할 수 있다.

ADK 2.0의 그래프 워크플로는 에이전트와 일반 함수를 방향이 있는 그래프로 이어 조건 분기와 병렬 단계를 만드는 기능이다. 블로그에 따르면 Go와 타입스크립트가 이 엔진 위에서 돌고, 코틀린은 실험 단계다.

ADK 언어별 차이와 고르는 기준

구글 클라우드 블로그는 같은 날씨 조회 도구를 5개 언어로 만들어 보이며 언어마다 도구를 선언하는 방식이 다르다고 설명한다. 아래 표는 그 내용을 언어별로 정리한 것이다.

언어	도구 선언 방식	특징
파이썬	타입과 docstring을 붙인 일반 함수를 tools에 전달	기준 구현이다. BigQuery·Spanner·Bigtable 연동과 Gemini·Anthropic·OpenAI·LiteLLM 모델 어댑터, 평가 도구가 가장 폭넓다
Go	functiontool.New와 struct 태그	컴파일러가 도구 시그니처를 검사한다. A2A 서버 핸들러와 OpenTelemetry 추적이 들어 있다
타입스크립트	FunctionTool과 Zod 스키마	하나의 스키마로 런타임 검증, JSON Schema, 타입 추론을 처리한다. 브라우저용 번들과 WebMCP를 지원한다
자바	@Schema 어노테이션과 LlmAgent.builder()	RxJava로 이벤트를 스트리밍하고, Maven 개발 UI 플러그인과 Spring AI·LangChain4j 연결을 제공한다
코틀린	@Tool·@Param을 빌드 시점에 읽는 KSP 플러그인	런타임 리플렉션이 없고 안드로이드 R8 축소와 맞는다. 기기 안에서 에이전트 루프를 돌리는 구성도 가능하다

블로그에 따르면 파이썬이 기준 구현이어서 구글 클라우드 연동과 평가 도구가 가장 넓다. 서비스가 이미 타입스크립트나 자바로 돼 있다면 블로그가 소개한 대로 Zod 스키마나 Spring AI 연결처럼 그 언어의 기존 도구와 맞물린다. 안드로이드 앱 안에서 에이전트를 돌려야 하면 기기에서 에이전트 루프를 돌릴 수 있다고 소개된 코틀린을 고른다.

구글 ADK 사용법: 언어별 설치와 첫 실행

공통 준비물은 제미나이 API 키다. Go와 코틀린 시작 문서는 GOOGLE_API_KEY, 타입스크립트 시작 문서는 GEMINI_API_KEY라는 이름으로 .env 파일에 넣으라고 안내한다. 키는 구글 AI 스튜디오에서 만든다.

언어	요구 환경	설치	실행
파이썬	Python 3.11 이상	pip install google-adk	adk run <에이전트 폴더>, 웹 화면은 adk web <폴더>
Go	Go 1.25 이상	go get google.golang.org/adk/v2	go run agent.go, 웹 화면은 go run agent.go web api webui
타입스크립트	Node.js 24.13.0 이상	npm install @google/adk	npx adk run agent.ts, 웹 화면은 npx adk web
자바	Java 17 이상, Maven 3.9 이상	pom.xml에 com.google.adk:google-adk 추가	mvn compile exec:java로 실행 클래스 지정
코틀린	Java 17 이상, Gradle 8.0 이상	build.gradle.kts에 google-adk-kotlin-core와 KSP 프로세서 추가	gradle run

요구 환경은 파이썬 저장소와 Go, 타입스크립트, 자바, 코틀린 시작 문서에 있다. 파이썬에서는 아래처럼 에이전트 하나를 정의하는 것이 시작이다.

from google.adk import Agent

root_agent = Agent(
    name="greeting_agent",
    model="gemini-3.5-flash",
    instruction="You are a helpful assistant. Greet the user warmly.",
)

이 파일을 담은 폴더를 adk run에 넘기면 터미널에서 대화하고, adk web은 브라우저 개발 화면을 연다. 각 시작 문서는 이 웹 화면이 개발과 디버깅 전용이며 운영 환경에 쓰지 말라고 안내한다. 브라우저 화면에서 에이전트를 골라 메시지를 보냈을 때 instruction에 적은 대로 답이 돌아오면 첫 실행이 된 것이다.

프로젝트 틀을 한 번에 만들고 싶으면 구글 클라우드 블로그가 소개한 agents-cli를 쓴다. uvx google-agents-cli setup으로 구글 클라우드 인증 확인, CLI 설치, ADK 스킬 추가를 한 번에 하고, agents-cli scaffold create my-go-agent --agent adk_go --deployment-target cloud_run --region us-central1처럼 언어(--agent), 배포 대상, 리전을 지정해 프로젝트를 만든다. 파이썬은 --agent adk를 쓴다. Claude Code나 Codex 같은 코딩 에이전트가 ADK를 다루게 하려면 adk.dev/llms.txt에 5개 언어의 API 문서가 정리돼 있다.

ADK 에이전트를 Cloud Run에 배포하는 방법

블로그에 따르면 스캐폴드 명령의 배포 대상은 Cloud Run, Gemini Enterprise Agent Runtime, GKE 중에서 고른다. Cloud Run 배포 문서에는 언어별 배포 명령이 다음과 같이 나온다.

언어	배포 명령	필수 지정값
파이썬	adk deploy cloud_run	--project, --region, 에이전트 경로
타입스크립트	npx adk deploy cloud_run (package.json이 있는 폴더에서)	--project, --region
Go	./adkgo deploy cloudrun	-p 프로젝트, -r 리전, -s 서비스 이름, -e main.go 경로
자바	직접 만든 Dockerfile과 gcloud run deploy <서비스> --source .	서비스 이름, --region, --project

배포 전에 gcloud auth login과 gcloud config set project로 계정과 프로젝트를 맞춰 둔다. 같은 문서에 따르면 adk deploy는 Cloud Build로 이미지를 만들므로 기본 컴퓨트 서비스 계정에 roles/cloudbuild.builds.builder 역할이 필요하고, API 키는 Secret Manager에 GOOGLE_API_KEY 비밀로 넣은 뒤 서비스 계정에 roles/secretmanager.secretAccessor를 주라고 안내한다.

같은 문서의 확인 방법은 이렇다. 배포가 끝나면 서비스 주소를 열어 에이전트를 골라 메시지를 보내거나, GET $APP_URL/list-apps로 앱 이름을 확인하고 POST $APP_URL/run_sse로 메시지를 보내 이벤트와 최종 답이 돌아오는지 본다. 인증이 필요한 서비스면 gcloud auth print-identity-token 값을 토큰으로 쓴다. 이상하면 Cloud Run 콘솔의 로그를 확인한다.

배포 문서에 따르면 세션 저장소와 아티팩트 저장소를 따로 지정하지 않으면 둘 다 인스턴스 메모리에만 있어서, Cloud Run이 인스턴스를 교체하면 대화 기록이 사라진다. 대화 기록을 유지하려면 --session_service_uri와 --artifact_service_uri를 지정한다.

구글 클라우드 블로그는 Go를 Cloud Run 배포에 유리한 언어로 소개한다. 컴파일된 에이전트가 약 2MiB의 distroless 정적 이미지에 들어가고, 정적 바이너리는 컨테이너가 뜨자마자 포트를 열어 동적 언어나 JVM 서비스의 로딩·워밍업 비용이 없다는 설명이다.

ADK를 처음 쓸 때 자주 하는 실수

웹 개발 화면을 그대로 운영 서비스로 노출하는 것이 가장 흔하다. adk web과 go run agent.go web api webui는 개발·디버깅용이어서 인증과 세션 저장소를 따로 갖춘 배포 구성으로 바꿔야 한다. 두 번째는 API 키를 코드나 이미지에 넣는 것이다. 시작 문서는 로컬에서 .env 파일을 쓰라고 안내하고, 배포 문서는 Cloud Run에서 Secret Manager 비밀을 쓰라고 안내한다. 세 번째는 코틀린의 그래프 워크플로가 실험 단계인 점을 놓치는 것이다. 블로그에 따르면 그래프 워크플로는 Go와 타입스크립트에서 쓰이므로 필요한 프로젝트는 이 둘부터 본다.

자주 묻는 질문

구글 ADK는 제미나이만 쓸 수 있나?

아니다. 파이썬 저장소는 ADK가 모델과 배포 환경에 얽매이지 않는다고 설명하고, 블로그는 파이썬에서 Gemini, Anthropic, OpenAI, LiteLLM 어댑터를 쓸 수 있다고 소개한다.

구글 ADK는 무료인가?

ADK는 Apache-2.0 라이선스의 오픈소스다. 에이전트가 호출하는 모델 API와 배포하는 Cloud Run 같은 서비스의 요금은 각 서비스의 가격표를 따른다.

ADK 에이전트는 Cloud Run 말고 어디에 배포하나?

Gemini Enterprise Agent Runtime과 GKE도 스캐폴드의 배포 대상이고, ADK 공식 문서는 자체 인프라 배포도 가능하다고 설명한다.