첫 번째 AI 에이전트를 로컬에서 구축하기: Antigravity IDE를 활용한 Google ADK 실전 가이드

서론 (Introduction)

AI 에이전트를 구축하는 것은 전통적으로 클라우드 인프라와 크레딧을 필요로 했으며, 이는 이제 막 시작하는 학생들과 개발자들에게 장벽이 될 수 있습니다. 하지만 만약 여러분의 로컬 머신에서 완전히 무료로, 지능형 AI 에이전트를 구축, 테스트 및 실행할 수 있다면 어떨까요?

이 가이드에서는 클라우드 크레딧 없이 Google Agent Development Kit (ADK)와 Antigravity IDE를 사용하여 첫 번째 AI 에이전트를 만드는 과정을 안내해 드리겠습니다. 또한, 준비가 되면 최소한의 변경만으로 Google Cloud에 배포할 수도 있습니다.

AI 개발을 처음 탐색하는 분이든, 개념 증명 (Proof-of-Concept)을 구축하는 분이든, 이 실습 튜토리얼을 통해 30분 이내에 실행 가능한 상태가 될 수 있습니다.

Google Agent Development Kit (ADK)란 무엇인가?

Google Agent Development Kit은 대규모의 신뢰할 수 있는 AI 에이전트를 구축하기 위한 오픈 소스 기반의 Python 우선 (Python-first) 프레임워크입니다. 다음과 같은 구조화된 방식으로 생각하면 됩니다:

에이전트 지침 및 동작 정의
도구 및 통합 (Integrations) 연결
다양한 LLM 백엔드 (Gemini, Vertex AI) 간 전환
배포 전 로컬에서 테스트 및 디버깅

주요 장점 (Key Advantages)
✅ 특정 벤더 종속성 없음 (No vendor lock-in) – 코드 우선 (Code-first), 프레임워크 불가지론적 (Framework-agnostic) 설계
✅ 로컬 우선 개발 (Local-first development) – 모든 것을 자신의 머신에서 테스트
✅ 내장된 도구 (Built-in tooling) – CLI 및 Web UI 포함
✅ 쉬운 배포 – 준비가 되면 Cloud Run, App Engine 또는 Kubernetes로 전송

사전 요구 사항 (Prerequisites)
시작하기 전에 다음 사항을 확인하세요:

시스템에 Python 3.10 이상 설치됨
텍스트 에디터 또는 IDE (Antigravity IDE를 사용할 예정입니다)
무료 Gemini API 키 (Google AI Studio에서 사용 가능))
약 30분의 시간 ⏱️

1단계: 작업 공간 설정 (Set Up Your Workspace)

프로젝트 디렉토리 생성
에이전트 프로젝트를 위한 새 폴더를 생성합니다:

mkdir Agent
cd Agent

가상 환경 초기화
가상 환경 (Virtual environment)은 프로젝트 종속성을 격리된 상태로 유지합니다:

# 가상 환경 생성
python -m venv .venv

...

Pro Tip: 항상 가상 환경 (virtual environment)을 사용하세요. 이는 패키지 충돌을 방지하고 설정을 재현 가능하게 (reproducible) 만듭니다.

Step 2: Google ADK 설치하기

이 부분이 핵심입니다. 올바른 패키지를 설치하세요:

pip install google-adk

⚠️ 중요: pip install adk를 실행하지 마세요. 이는 ADK 명령과 충돌하는 관련 없는 RPC 라이브러리를 설치합니다.

설치를 확인합니다:

adk --version

Step 3: 첫 번째 에이전트 스캐폴딩 (Scaffold) 하기

ADK CLI를 사용하여 보일러플레이트 (boilerplate) 파일을 생성할 수 있습니다:

adk create my_agent

CLI에서 다음과 같은 프롬프트가 나타날 수 있습니다:

모델 선택 (Choose a model) → gemini-3.5-flash (무료, 빠름, 성능 우수)를 위해 1번 선택
백엔드 선택 (Choose a backend) → 인프라 설정이 필요 없는 Google AI를 위해 1번 선택
Google API 키 입력 (Enter your Google API Key) → Gemini API 키를 붙여넣으세요 (또는 지금은 자리 표시자 입력)

이 명령어를 실행한 후, 다음과 같은 구조를 볼 수 있습니다:

my_agent/
├── .env              # API 인증 정보 (Git에서 제외됨)
├── .gitignore        # 비밀 정보의 커밋을 방지함
...

Step 4: API 키 설정하기

my_agent/.env 파일을 엽니다:

GOOGLE_GENAI_USE_ENTERPRISE=0
GOOGLE_API_KEY=YOUR_GEMINI_API_KEY

YOUR_GEMINI_API_KEY를 Google AI Studio에서 발급받은 실제 키로 교체하세요.

보안 주의 사항: .gitignore는 이 파일이 버전 관리 시스템에 커밋되는 것을 방지합니다. API 키를 절대 커밋하지 마세요!

Step 5: 에이전트 코드 살펴보기

my_agent/agent.py를 엽니다. 다음과 같은 코드가 보일 것입니다:

from google.adk.agents.llm_agent import Agent

root_agent = Agent(
...

이것이 당신의 에이전트 정의입니다. 단순하지만 강력합니다:

model: 에이전트를 구동하는 LLM (Large Language Model)
name: 에이전트의 고유 식별자
description: 에이전트가 수행하는 역할
instruction: 행동을 안내하는 시스템 프롬프트 (system prompt)

Step 6: 에이전트 실행하기 (두 가지 옵션)

옵션 A: 터미널 CLI (대화형 채팅)
터미널에서 빠르게 테스트하려면:

# Windows에서는 이모지 충돌을 방지하기 위해 UTF-8 인코딩을 설정하세요:
export PYTHONIOENCODING="utf-8"

...

메시지를 입력하고 에이전트로부터 실시간으로 응답을 받을 수 있는 대화형 프롬프트(interactive prompt)가 나타납니다.

옵션 B: Web UI (시각적 채팅 인터페이스)
더 세련된 경험을 원한다면:

adk web my_agent

브라우저에서 http://127.0.0.1:8000을 열면 깔끔한 채팅 인터페이스가 나타납니다. 이는 데모(demo)나 사용자 테스트(user testing)에 매우 유용합니다.

실제 활용 사례 (Real-World Use Cases)

ADK로 구축할 수 있는 몇 가지 아이디어는 다음과 같습니다:

📚 학습 보조 도구 (Study Assistant) – 개념 설명, 퀴즈 생성
🛠️ 코드 도우미 (Code Helper) – 코드 디버깅 (debug), 최적화 제안
📰 뉴스 애그리게이터 (News Aggregator) – 여러 소스의 뉴스 요약
🤖 고객 지원 봇 (Customer Support Bot) – 자주 묻는 질문 (FAQ) 처리, 상담원 연결
📊 데이터 분석가 (Data Analyst) – 데이터 처리 및 인사이트 생성

지금 바로 시작하기

구축할 준비가 되셨나요? 스타터 템플릿 (starter template)을 클론(clone)하거나 다운로드하세요:

📦 저장소 (Repository): KojoShaddy/my_agent

저장소에는 다음 내용이 포함되어 있습니다:

전체 설정 가이드 (setup guide)
단계별 코드랩 (codelab)
예제 에이전트 코드
배포 문서 (deployment documentation)

결론

AI 에이전트를 구축하는 것은 더 이상 클라우드 인프라 (cloud infrastructure)에 의해 제한되지 않습니다. Google ADK와 Antigravity IDE를 사용하면, 오늘 바로 로컬 머신 (local machine)에서 지능형 에이전트를 구축하는 데 필요한 모든 것을 갖출 수 있습니다.

이것이 여러분의 첫 번째 AI 프로젝트이든, 혹은 고급 에이전트 아키텍처 (agent architectures)를 탐구하는 과정이든, 이 기초는 여러분에게 큰 도움이 될 것입니다. 로컬에서 시작하여 빠르게 반복(iterate)하고, 준비가 되면 클라우드로 확장(scale)하세요.

리소스 및 다음 단계

📖 공식 Google ADK 문서 (Official Google ADK Docs)
🔑 무료 Gemini API 키 받기 (Get Your Free Gemini API Key)
💻 Antigravity IDE 다운로드 (Download Antigravity IDE)
🚀 Google Cloud 배포 가이드 (Google Cloud Deployment Guide)

Insights