Google ADK Python 추천: Gemini 에이전트를 코드로 만들고 평가하는 공식 프레임워크
설치, 첫 테스트, 평가, 배포 전 체크포인트까지 보는 GitHub 추천 글
Google ADK Python은 무엇인가
빠른 답변: 빠른 답변: google adk-python Agent Development Kit v1.34.0은 Google의 공식 Python 에이전트 개발 프레임워크를 stable 기준으로 검토하기 좋은 버전입니다. Gemini 에이전트를 코드로 만들고, 로컬에서 실행한 뒤 평가와 배포 후보까지 확인하려는 독자에게 맞습니다.
AI 에이전트 프레임워크를 볼 때 저는 먼저 “예제만 예쁜가, 아니면 프로젝트에 남길 구조가 있는가”를 확인합니다. Google ADK Python은 그 기준에서 꽤 실용적인 편입니다. 단순 채팅 예제가 아니라 `agent.py`, `root_agent`, CLI 실행, 개발용 웹 UI, 평가, Cloud Run 배포 문서가 한 흐름으로 이어집니다.
여기서 볼 부분은 Google 공식 저장소라는 간판보다 코드 중심 개발 방식입니다. README는 Gemini에 최적화되어 있다고 설명하면서도 model-agnostic, deployment-agnostic 방향을 함께 내세웁니다. 다만 이 말을 모든 모델에서 같은 품질을 보장한다는 뜻으로 읽으면 곤란합니다. 이 글에서는 Gemini에 가장 자연스럽게 붙는 공식 프레임워크로 보되, 다른 provider는 별도 검증 대상으로 다룹니다.
따라서 이 글의 목적은 google/adk-python을 바로 채택하라는 권유가 아닙니다. 설치해 볼 가치가 있는지, 기존 OpenAI Agents SDK나 LangGraph와 나란히 비교할지, v2 계열 안정화를 기다릴지 판단하는 데 필요한 기준을 정리합니다.
지금 v1.34.0을 보는 이유
빠른 답변: 빠른 답변: GitHub API 기준 google/adk-python은 2026-05-19에 push됐고, 최신 정식 릴리스 v1.34.0은 2026-05-18에 게시됐습니다. 다만 v2.0.0 prerelease와 main 브랜치 변화가 함께 보이므로 사용법은 stable 기준으로 분리해야 합니다.
이번 글에서 google adk-python Agent Development Kit v1.34.0을 다루는 이유는 시간성이 분명하기 때문입니다. 사용자 피드백 기준 GitHub API는 2026-05-19T01:12:05Z push, 19,707 stars, Apache-2.0 license를 확인했습니다. keyword_research에서는 같은 날 다른 확인 시점에 19,710 stars와 2026-05-19T02:24:28Z push도 잡혀 있습니다. 별 수는 계속 움직이므로 본문에서는 약 1.9만 stars로 보는 편이 안전합니다.
정식 릴리스 기준선은 2026-05-18T23:56:51Z에 게시된 v1.34.0입니다. 동시에 2026-04-09 v2.0.0a3 prerelease와 main 브랜치의 2.x 전환 흐름도 보입니다. 한국 사용자 입장에서는 GitHub main을 그대로 따라가기보다 PyPI와 GitHub latest release가 맞물리는 v1.34.0 stable로 첫 테스트를 잡는 것이 낫습니다.
> 이 글의 기준선은 v1.34.0 stable입니다. 2.x 흐름은 참고 신호로만 보겠습니다.
릴리스 노트에서 실제로 볼 부분
빠른 답변: 빠른 답변: Agent Development Kit v1.34.0은 A2A persistent task store, Gemini Live API 평가, Cloud Telemetry mTLS, McpToolset OAuth PKCE, Skill Registry 관련 변경을 포함합니다. 처음 보는 독자에게는 평가, 인증, 도구 연동, 운영 추적이 보강되는 릴리스로 이해하면 충분합니다.
릴리스 노트를 기능명 그대로 따라가면 글이 금방 딱딱해집니다. 제가 보기에는 v1.34.0의 신호는 네 갈래입니다. 에이전트가 긴 작업을 다루고, 외부 도구 권한을 더 섬세하게 연결하고, Gemini Live API 평가를 넓히고, Cloud 쪽 telemetry를 보강하는 방향입니다.
실제로 확인할 부분은 작습니다. MCP나 OAuth PKCE는 편리하지만 권한 설계가 따라와야 합니다. Gemini Live API 평가는 음성·실시간 흐름을 실험하는 독자에게 더 의미가 있습니다. persistent task store와 telemetry는 노트북에서 한 번 실행하는 수준보다 운영 후보로 보는 독자에게 중요합니다.
다만 릴리스 항목이 곧 내 서비스의 안정성을 보장하지는 않습니다. 특히 API key, OAuth scope, MCP 서버 권한은 개인 테스트 환경에서 좁게 시작해야 합니다.
추천 근거는 공식보다 구조에 있다
빠른 답변: 빠른 답변: 추천 근거는 공식 Google 저장소, Apache-2.0 license, 약 1.9만 stars, pip 설치, 평가와 배포 문서까지 이어지는 구조입니다. google adk-python Agent Development Kit v1.34.0은 개인 개발자가 에이전트 프레임워크를 비교할 때 첫 실험 비용이 낮은 편입니다.
google/adk-python의 장점은 “Google이 만들었다”에서 끝나지 않습니다. 시작 흐름이 짧습니다. `pip install google-adk`로 설치하고, `adk create my_agent`로 기본 구조를 만든 뒤, `.env`에 `GOOGLE_API_KEY`를 넣고 `adk run` 또는 `adk web`으로 확인합니다. 처음 도입할 때 실패 지점이 어디인지 좁혀 보기 좋습니다.
또 하나 마음에 드는 지점은 평가 문서가 따로 있다는 점입니다. 에이전트는 한 번 좋은 답을 냈다고 끝나는 도구가 아닙니다. 프롬프트, 모델, 도구 권한, 외부 API 상태에 따라 결과가 흔들립니다. ADK가 `adk web`, `pytest`, `adk eval` 같은 평가 경로를 제시한다는 점은 개인 프로젝트에서도 꽤 중요한 차이입니다.
비교 관점에서는 Gemini와 Google Cloud 쪽으로 이미 기울어진 프로젝트에 잘 맞습니다. OpenAI 중심 도구 체인, LangGraph 그래프 구조, CrewAI 역할 기반 구성을 쓰고 있다면 갈아타기보다 작은 agent 하나로 병렬 검증하는 편이 현실적입니다.
설치부터 첫 테스트까지
빠른 답변: 빠른 답변: Python 3.10 이상에서 venv를 만들고 `pip install google-adk`, `adk create my_agent`, `GOOGLE_API_KEY` 설정, `adk run my_agent` 또는 `adk web --port 8000` 순서로 검증합니다. 첫날 목표는 `my_agent/agent.py`의 `root_agent`가 로컬에서 재현 가능하게 동작하는지 확인하는 것입니다.
처음부터 Cloud Run 배포나 복잡한 multi-agent를 붙이면 문제 원인을 찾기 어렵습니다. 저는 Google ADK Python을 볼 때 아래처럼 작게 시작하는 편을 권합니다.
1. Python 3.10 이상인지 확인하고 프로젝트별 venv를 만듭니다.
2. `pip install google-adk`로 stable 패키지를 설치합니다.
3. `adk create my_agent`로 기본 구조를 생성합니다.
4. `my_agent/.env`에 테스트용 `GOOGLE_API_KEY`를 넣습니다.
5. `.env`가 Git에 들어가지 않도록 `.gitignore`를 확인합니다.
6. `adk run my_agent`로 CLI 대화를 먼저 봅니다.
7. 디버깅이 필요할 때만 `adk web --port 8000`으로 개발용 웹 UI를 엽니다.
공식 Quickstart의 예시 구조는 `my_agent/agent.py`, `my_agent/.env`, `my_agent/__init__.py`입니다. 여기서 기준점은 `agent.py` 안의 `root_agent`입니다. 실무 도입 전에는 `root_agent`의 model, instruction, tools를 표로 남기고, 어떤 입력에서 어떤 답을 기대하는지 작은 평가 세트를 붙이는 편이 좋습니다.
| 점검 항목 | 첫 테스트에서 볼 것 |
|---|---|
| 런타임 | Python 3.10 이상, venv 분리 |
| 패키지 | `google-adk==1.34.0` 기준 설치 여부 |
| 비밀값 | `.env`의 `GOOGLE_API_KEY`가 저장소에 커밋되지 않는지 |
| 실행 | `adk run my_agent`에서 기본 응답 재현 여부 |
| 디버깅 | `adk web --port 8000`은 개발/디버깅 용도로만 사용 |
| 평가 | `adk eval` 또는 pytest로 최소 케이스 자동화 가능성 확인 |
운영 모델과 추천 필드
빠른 답변: 빠른 답변: 운영 관점에서는 로컬 CLI 테스트, ADK Web 디버깅, 평가 자동화, Cloud Run 또는 Agent Runtime 배포 후보를 분리해야 합니다. 추천 분야는 Gemini 기반 업무 자동화, RAG 프로토타입, MCP 도구 실험, Google Cloud 배포를 검토하는 작은 AI agent 프로젝트입니다.
ADK Python을 오래 쓰려면 “실행했다”보다 “어떻게 관리할 것인가”가 더 중요합니다. 로컬에서는 `adk run`으로 agent 동작을 빠르게 확인하고, 개발 중에는 `adk web`으로 대화와 도구 호출 흐름을 봅니다. 반복 검증은 `adk eval`이나 pytest로 묶고, 운영 후보는 Cloud Run 배포 문서처럼 `agent.py`, `root_agent`, `__init__.py`, `requirements.txt` 구조를 확인해야 합니다.
한국 개인 개발자나 소규모 팀에는 Gemini API를 이미 쓰는 내부 자동화, 문서 질의응답 RAG 프로토타입, MCP Toolset으로 외부 도구를 붙이는 실험, Google Cloud 배포까지 고려하는 agent 백엔드가 현실적입니다. 반대로 단순히 한 번 프롬프트를 보내는 API wrapper가 필요하다면 ADK는 무거울 수 있습니다.
운영 중 확인할 필드는 구체적이어야 합니다. `GOOGLE_API_KEY` 보관 위치, MCP 서버 command, OAuth scope, Cloud Run 서비스 계정, `requirements.txt` 버전 고정, 평가 세트 실패율, 로그와 telemetry 보존 범위가 최소 체크리스트입니다.
비교 기준과 도입 보류 조건
빠른 답변: 빠른 답변: google adk-python Agent Development Kit v1.34.0은 Gemini와 Google Cloud 쪽 실험에는 잘 맞지만, 모든 에이전트 프레임워크를 대체한다고 보기는 이릅니다. 모델 중립성은 프레임워크 방향으로 이해하고, 실제 품질은 provider별로 검증해야 합니다.
선택 기준은 승자 찾기가 아니라 현재 워크플로와 맞는지입니다. ADK는 Google 공식 저장소, Gemini 친화성, 평가와 배포 문서가 강점입니다. LangGraph는 그래프 기반 상태 흐름을 세밀하게 다루는 프로젝트에 익숙하고, OpenAI Agents SDK는 OpenAI 모델과 도구 호출을 중심에 둔 팀에서 비교 대상이 됩니다. CrewAI는 역할 기반 agent team 실험을 빠르게 해 보는 쪽에 가깝습니다.
| 상황 | ADK Python 판단 |
|---|---|
| Gemini API와 Google Cloud를 이미 쓴다 | 우선 작은 agent로 실험 |
| 여러 provider를 같은 품질로 즉시 바꿔 쓰고 싶다 | LiteLLM 등 별도 검증 필요 |
| production UI가 필요하다 | `adk web`을 운영 UI로 쓰면 안 됨 |
| API key와 외부 도구 권한 관리가 아직 없다 | 도입 전 보류가 나음 |
| v2.0.0 안정화를 기다리는 조직이다 | v1.34.0 테스트만 작게 진행 |
제가 보기에는 이 저장소의 좋은 사용법은 새 표준으로 바로 갈아타는 방식이 아닙니다. 작은 agent 하나를 만들어 기존 프레임워크와 같은 입력, 같은 평가 기준, 같은 도구 권한으로 비교하는 것입니다. 그래야 Google ADK Python이 내 프로젝트의 복잡도를 줄이는지, 아니면 Google 생태계 의존성만 늘리는지 나눠 볼 수 있습니다.
자주 묻는 질문
Q. Google ADK Python은 무엇인가?
A. Google ADK Python은 AI agent를 Python 코드로 만들고, 로컬에서 실행하고, 평가와 배포 후보까지 이어 보기 위한 Google의 공식 Agent Development Kit입니다. 공식 저장소는 google/adk-python이며, 이 글은 v1.34.0 stable 기준으로 설명합니다.
Q. google-adk는 어떻게 설치하나?
A. PyPI 기준 Python 3.10 이상 환경에서 `pip install google-adk`로 설치합니다. 첫 테스트는 venv 생성, `adk create my_agent`, `my_agent/.env`의 `GOOGLE_API_KEY` 설정, `adk run my_agent` 순서가 가장 단순합니다.
Q. ADK Python은 Gemini 전용인가?
A. Gemini에 최적화된 프레임워크로 보는 것이 자연스럽지만, 공식 문서는 모델과 배포 환경에 중립적인 방향도 설명합니다. 다만 다른 provider에서 Gemini와 동일한 품질이나 기능을 보장한다고 해석하면 안 됩니다.
Q. adk run과 adk web은 어떻게 다르게 쓰나?
A. `adk run`은 CLI에서 agent 동작을 빠르게 확인할 때 쓰고, `adk web --port 8000`은 개발 중 대화와 디버깅 흐름을 보기 위한 웹 UI입니다. 공식 문서 기준 ADK Web은 개발/디버깅 용도이므로 운영 사용자 화면으로 두면 안 됩니다.
Q. 지금 도입을 보류해야 하는 경우는 언제인가?
A. Google Cloud나 Gemini API 권한이 준비되지 않았거나, 외부 도구 권한과 API key 관리 기준이 없거나, v2 계열 안정화 이후에만 프레임워크를 고르는 조직이라면 보류가 낫습니다. 단순 API 호출 wrapper만 필요해도 ADK는 과한 선택일 수 있습니다.
함께 읽으면 좋은 글
- GitHub 추천: LiveKit Agents로 실시간 음성 AI 에이전트 만들기 — GITHUB 추천
- GitHub MCP Server 추천: AI 에이전트와 GitHub 워크플로를 연결하는 공식 서버 — GITHUB 추천
- Composio 추천: AI 에이전트에 외부 도구와 SaaS 액션을 붙이는 방법 — GITHUB 추천
- LiteLLM 추천: 여러 AI 모델 API를 하나의 LLM 게이트웨이로 묶는 방법 — GITHUB 추천
- Graphify GitHub 추천: AI 코딩 에이전트에게 코드 지식 그래프를 주는 법 — GITHUB 추천
참조 링크
- google/adk-python — 공식 저장소, owner/repo, README 포지셔닝, license, GitHub 활동 신호 확인
- ADK Python v1.34.0 release — 2026-05-18 최신 정식 릴리스와 v1.34.0 변경 사항 확인
- google-adk 1.34.0 on PyPI — 패키지명, 설치 명령, Python 3.10 이상 요구사항 확인
- Python Quickstart for ADK — venv, adk create, GOOGLE_API_KEY, adk run, adk web, root_agent 흐름 확인
- Why Evaluate Agents — adk web, pytest, adk eval 기반 평가 경로 확인
- Deploy to Cloud Run — Cloud Run 배포 전 필요한 파일 구조와 운영 전환 기준 확인
- Model Context Protocol Tools — MCP Toolset 연동과 외부 도구 권한 검토 근거
- Build Your First Intelligent Agent Team — LiteLLM 기반 다른 provider 실험 가능성 확인