1. 소개
이 Codelab에서는 Google의 에이전트 개발 키트 (ADK)와 Gemini를 사용하여 첫 번째 AI 에이전트를 단계별로 빌드합니다. 추론 및 행동의 핵심 개념을 보여주는 콘텐츠를 계획하고 작성하는 기본 블로그 작성 에이전트를 만듭니다.
실습할 내용
- ADK 개발 환경을 설정합니다.
- 플래너와 작성자로 멀티 에이전트 시스템을 만듭니다.
- 로컬에서 에이전트를 실행하고 ADK 웹 UI를 통해 상호작용합니다.
필요한 항목
- 웹브라우저(예: Chrome)
- 머신에 Python 3.10 이상이 설치되어 있어야 합니다.
- Google AI Studio API 키입니다.
이 Codelab은 초보자를 포함한 모든 수준의 개발자를 대상으로 합니다.
예상 소요 시간: 30분
2. 시각적 가이드: AI 에이전트란 무엇인가요?
빌드를 시작하기 전에 AI 에이전트가 무엇인지, 그리고 AI 에이전트가 따르는 일반적인 패턴을 빠르게 이해해 보겠습니다.
AI 에이전트란 무엇인가요?
가장 간단한 수준에서 에이전트는 단순히 대답하는 것이 아니라 결정하고 조치를 취할 수 있는 소프트웨어입니다. 기존 챗봇처럼 단일 응답을 생성하는 대신 요청을 살펴보고, 취해야 할 단계를 파악하고, API를 호출하고, 코드를 실행하고, 결과를 살펴본 후 다음에 무엇을 해야 할지 결정합니다.
가장 명확한 설명 중 하나는 연구 논문 ReAct: Synergizing Reasoning and Acting in Language Models에서 확인할 수 있습니다. 이 논문의 아이디어는 간단하지만 강력합니다. 언어 모델은 한 번에 텍스트를 생성해서는 안 됩니다. 실제로 단계별로 추론하고, 도구나 API를 호출하는 등의 작업을 취하고, 결과를 관찰한 다음, 다음에 무엇을 해야 할지 결정할 수 있습니다.
추론, 행동, 관찰, 조정의 이러한 사이클은 최신 AI 에이전트가 작동하는 방식의 기반입니다. 또한 Google Cloud의 정의와도 일치합니다. 즉, 추론, 계획, 기억이 가능하며 사용자를 대신하여 적응하고 결정을 내릴 수 있는 충분한 자율성을 갖춘 시스템입니다.
세 가지 에이전트 동작 패턴
모든 에이전트가 동일하게 작동하는 것은 아닙니다. 에이전트를 세 가지 광범위한 패턴으로 생각하는 것이 유용합니다.
- 순차적 에이전트: 조립 라인처럼 1단계, 2단계, 3단계 순으로 실행됩니다. 예측 가능하지만 경직되어 있습니다.
- 사후 대응 에이전트: 즉석에서 결정합니다. 현재 상태를 살펴보고 '다음으로 무엇을 해야 할까?'라고 묻습니다. 한 번은 도구 A를 사용하고 다음에는 도구 B를 사용할 수 있습니다. 유연하지만 미리 계획하지 않습니다.
- 숙고형 또는 계획형 에이전트: 계획을 스케치하기 위해 일시중지한 후 실행합니다. 여행을 예약하는 것을 생각해 보세요. 무작위로 항공편을 구매하는 것이 아니라 날짜와 호텔을 선택하고 단계를 순서대로 진행한 다음 완료합니다.
어떤 것이 '올바른' 것일까요? 문제에 따라 다릅니다. 단순하고 예측 가능한 흐름에는 순차적 방식이 적합합니다. 동적 작업에는 반응형 방식이 더 적합합니다. 종속성이 있는 다단계 목표에는 계획 에이전트가 적합합니다.
이 실습에서는 먼저 개요를 만든 다음 블로그 게시물을 작성하는 숙고/계획 에이전트를 빌드합니다.
3. 시작하기 전에
Google Cloud 계정 및 프로젝트 만들기
이 실습의 뒷부분에서 Google Cloud Run에 에이전트를 배포하려면 Google Cloud 계정과 결제가 사용 설정된 프로젝트가 필요합니다.
- Google Cloud 콘솔에 로그인합니다. 새 프로젝트를 만들거나 기존 프로젝트를 재사용합니다. 아직 Google 계정이 없다면 계정을 만들어야 합니다.
- 다음으로 Cloud 리소스를 사용하려면 Cloud 콘솔에서 결제를 사용 설정해야 합니다. 이 Codelab을 실행하는 데는 몇 센트 미만의 비용이 듭니다. Google Cloud 신규 사용자는 300달러(USD) 상당의 무료 체험판 프로그램에 참여할 수 있습니다.
- 프로젝트 ID (모든 Google Cloud 프로젝트에서 고유한 이름)를 기록해 둡니다. 에이전트를 구성하고 배포하는 데 필요합니다.
Google AI Studio API 키 가져오기
Gemini 모델을 사용하려면 Google AI Studio의 API 키가 필요합니다.
- Google AI Studio로 이동합니다.
- API 키 가져오기를 클릭합니다.
- 새 키를 만들거나 기존 키를 사용합니다. 나중에 사용할 수 있도록 키를 복사합니다.
4. 블로그 작성자 에이전트 프로젝트 구조 만들기
이 단계에서는 로컬 머신에 블로그 작성 에이전트의 코드를 저장할 디렉터리와 파일을 설정합니다.
1. 블로그 작성 에이전트 작업공간 만들기
터미널을 열고 다음 명령어를 실행하여 블로그 작성자 에이전트 전용 디렉터리를 만들고 해당 디렉터리로 이동합니다.
mkdir bloggeragent
cd bloggeragent
2. 에이전트 파일 초기화
Google ADK 프레임워크는 프로젝트 디렉터리에서 직접 에이전트 워크플로를 로드합니다. bloggeragent의 루트에 필요한 파일을 직접 만듭니다.
touch requirements.txt .env __init__.py agent.py
5. 종속 항목 설치 및 환경 설정
이 단계에서는 Python 가상 환경을 설정하고, Google ADK 프레임워크를 설치하고, 환경 변수를 구성하여 블로그 에이전트를 Gemini 모델로 인증합니다.
1. 에이전트 요구사항 구성
bloggeragent 디렉터리에서 requirements.txt 파일을 열고 다음을 추가하여 블로그 작성 에이전트에 필요한 패키지를 지정합니다.
google-adk==2.2.0
python-dotenv
2. 에이전트의 가상 환경 만들기
bloggeragent 디렉터리에서 Python 가상 환경을 만들고 활성화하여 에이전트의 패키지를 격리합니다.
python3 -m venv .venv
source .venv/bin/activate
3. ADK 프레임워크 설치
requirements.txt에 정의된 종속 항목을 설치하여 로컬 워크스페이스에 Google ADK를 설치합니다.
pip install -r requirements.txt
4. 에이전트 API 사용자 인증 정보 구성
프로젝트 루트에서 만든 .env 파일을 열고 Gemini API 키를 추가합니다.
GOOGLE_API_KEY=your_api_key
your_api_key를 Google AI Studio에서 복사한 키로 바꿉니다.
6. 멀티 에이전트 블로그 작성기 빌드
이 단계에서는 블로그 작성 에이전트 시스템의 핵심 워크플로를 구현합니다.
단순한 단일 프롬프트 챗봇 대신 자체 수정 루프와 개요 확인을 사용하여 고품질 기술 게시물을 작성하는 복잡한 멀티 에이전트 시스템을 빌드합니다. 이는 앞에서 설명한 숙고/계획 패턴을 따릅니다.
아키텍처 개요
시스템의 전문가 에이전트가 상호작용하는 방식은 다음과 같습니다.
init.py 구성
텍스트 편집기에서 __init__.py을 열고 다음 가져오기를 추가하여 러너에 에이전트 워크플로를 노출합니다.
from . import agent
블로그 작성 에이전트 워크플로 작성
코드 편집기에서 agent.py을 열고 플래너, 작성자, 유효성 검사기, 기본 블로거 에이전트를 정의하는 다음 코드를 추가합니다.
import os
import sys
from pathlib import Path
import datetime
from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool
# env config
load_dotenv()
MODEL = os.getenv("MODEL", "gemini-flash-latest")
# Sub-Agent: Planner
blog_planner = Agent(
name="BlogPlanner",
model=MODEL,
description="Creates a practical, skimmable outline in Markdown.",
instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion
If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
output_key="blog_outline",
)
class OutlineValidationChecker(Agent):
def __init__(self):
super().__init__(
name="OutlineValidationChecker",
model=MODEL,
description="Validates that the outline is usable.",
instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
output_key="validation_result",
)
robust_blog_planner = LoopAgent(
name="RobustBlogPlanner",
description="Retries planning if validation fails.",
sub_agents=[blog_planner, OutlineValidationChecker()],
max_iterations=3,
)
# Sub-Agent: Writer
blog_writer = Agent(
name="BlogWriter",
model=MODEL,
description="Writes a technical blog post from the outline.",
instruction="""
Write a complete Markdown article from the outline in `blog_outline`.
Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
output_key="blog_post",
)
class BlogPostValidationChecker(Agent):
def __init__(self):
super().__init__(
name="BlogPostValidationChecker",
model=MODEL,
description="Validates the final post.",
instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
output_key="validation_result",
)
robust_blog_writer = LoopAgent(
name="RobustBlogWriter",
description="Retries writing if validation fails.",
sub_agents=[blog_writer, BlogPostValidationChecker()],
max_iterations=3,
)
# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool = agent_tool.AgentTool(agent=robust_blog_writer)
# Root Agent: Plan → Write
root_agent = Agent(
name="Blogger",
model=MODEL,
description="Minimal multi-agent blogger that plans and writes.",
instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.
Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
tools=[
planner_tool, # calls RobustBlogPlanner
writer_tool, # calls RobustBlogWriter
],
)
에이전트 아키텍처 이해
방금 agent.py에 추가한 코드의 주요 구성요소를 분석하여 멀티 에이전트 계획 및 작성 워크플로를 구현하는 방법을 알아보겠습니다.
1. BlogPlanner 하위 에이전트
blog_planner 에이전트는 콘텐츠 계획을 담당합니다. 사용자가 제공한 주제를 가져와 제목, 소개, 4~6개의 섹션, 결론이 포함된 구조화된 개요를 마크다운으로 생성합니다. 개요는 "blog_outline" 키 아래의 공유 상태 사전에 저장됩니다.
2. OutlineValidationChecker
OutlineValidationChecker 에이전트는 품질 관리 역할을 합니다. 상태에서 생성된 "blog_outline"를 검토합니다. 개요가 유효하면 "ok"로 응답합니다. 그렇지 않으면 누락된 항목 목록과 함께 "retry"를 반환합니다.
3. RobustBlogPlanner 루프
에이전트가 잘못된 개요를 생성하지 않도록 플래너와 유효성 검사기를 robust_blog_planner이라는 LoopAgent 안에 래핑합니다. 유효성 검사에 실패하고 "retry"를 반환하면 루프가 최대 3번까지 플래너를 자동으로 다시 실행하여 다음 단계로 이동하기 전에 자체 수정합니다.
4. BlogWriter 하위 에이전트
개요가 확정되면 blog_writer 에이전트가 상태에서 "blog_outline"를 읽고 개요의 구조와 일치하며 소프트웨어 엔지니어에 맞게 조정된 전체 기술 문서를 마크다운으로 생성합니다.
5. BlogPostValidationChecker 및 RobustBlogWriter 루프
개요와 마찬가지로 최종 아티클은 BlogPostValidationChecker에 의해 검증되어 모든 주요 섹션이 존재하고 명확한지 확인합니다. 작성자와 검사자는 robust_blog_writer 루프에 포함되어 검사자가 문제를 발견하면 최대 3번까지 자체 수정할 수 있습니다.
6. 루프를 도구로 노출
AgentTool를 사용하여 플래너 루프 (robust_blog_planner)와 작성자 루프 (robust_blog_writer)를 도구 (planner_tool 및 writer_tool)로 래핑합니다. 이를 통해 다른 에이전트가 이러한 복잡한 워크플로를 간단한 도구처럼 호출할 수 있습니다.
7. Blogger 루트 에이전트
root_agent (Blogger로 명명됨)는 전체 워크플로를 조정합니다. 주제가 주어지면 다음을 수행하도록 안내합니다.
planner_tool를 호출하여 검증된 개요를 생성합니다.writer_tool를 호출하여 개요를 기반으로 초안을 작성합니다.- 대체 제목 3개와 트윗 후크 2개를 생성하여 마무리합니다.
이 멀티 에이전트 루프 아키텍처는 사용자에게 출력을 표시하기 전에 LLM 형식 또는 구조적 실수를 포착하고 수정하여 안정성을 보장합니다.
7. 에이전트 실행 및 테스트
이제 에이전트가 실제로 작동하는지 확인해 보겠습니다.
1. ADK 웹 UI 시작
터미널에서 bloggeragent 프로젝트 루트 디렉터리에 있고 가상 환경이 활성화 (source .venv/bin/activate)되어 있는지 확인한 후 웹 인터페이스를 시작합니다.
adk web
2. 에이전트와 상호작용
- 브라우저를 열고
http://127.0.0.1:8000(또는 지정한 포트)로 이동합니다. Blogger에이전트가 로드되고 시각적 레이아웃 (Blogger 루트 에이전트가 RobustBlogPlanner 및 RobustBlogWriter 도구를 가리킴)이 표시된 ADK 웹 UI가 표시됩니다.
- 메시지 상자에 기술 주제를 입력하고 Enter 키를 누릅니다. 다음은 에이전트를 평가하는 데 사용할 수 있는 흥미로운 테스트 프롬프트입니다.
How to build an AI agent using planning loopsExplain the difference between REST and gRPC in microservicesA guide to using Python's asyncio for backend concurrencyWhy developers should use Docker for local database setups
- UI에서 실행 추적을 확인합니다.
BlogPlanner가 개요를 만들고,OutlineValidationChecker가 개요를 검증하고,BlogWriter가 개요를 기반으로 최종 초안을 작성하는 것을 확인할 수 있습니다.
8. Cloud Run에 배포
이제 에이전트가 로컬에서 작동하는지 확인했으므로 다른 사용자가 사용할 수 있도록 Google Cloud Run에 배포해 보겠습니다.
Google Cloud Run은 웹 요청 또는 Pub/Sub 이벤트를 통해 호출 가능한 스테이트리스(Stateless) 컨테이너를 실행할 수 있게 해 주는 관리형 컴퓨팅 플랫폼입니다.
1. 배포를 위한 기본 요건
블로그 작성 에이전트를 Cloud Run에 배포하려면 로컬 머신에 Google Cloud CLI (gcloud)를 설치하고 인증해야 합니다.
- Google Cloud CLI 설치: Google Cloud CLI가 설치되어 있지 않으면 운영체제 (macOS, Windows 또는 Linux)에 맞는 Google Cloud CLI 설치 가이드를 따르세요.
- 로컬 터미널 인증: 설치가 완료되면 터미널에서 다음 명령어를 실행하여 Google Cloud 계정에 로그인합니다.
gcloud auth login - 인증 확인: 계정이 로그인되었으며 Google Cloud 리소스에 액세스할 수 있는지 확인합니다.
gcloud auth list
2. Google Cloud 프로젝트 설정
터미널에서 활성 프로젝트를 설정합니다.
gcloud config set project <YOUR_PROJECT_ID>
컨테이너화된 에이전트를 빌드하고 배포하는 데 필요한 Google Cloud 서비스를 사용 설정합니다.
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
ADK 배포 명령어는 Google Cloud Build를 사용하여 빌드 프로세스를 자동화하므로 기본 Compute 서비스 계정에 Cloud Build 사용 권한을 부여해야 합니다.
다음을 실행하여 프로젝트 번호를 찾습니다.
gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"
다음 명령어를 실행하여 필요한 IAM 역할을 바인딩합니다 (
- Cloud Build에 컨테이너를 빌드할 수 있는 권한을 부여합니다.
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/cloudbuild.builds.builder"
- 배포된 에이전트가 API 키 없이 Gemini 모델을 호출할 수 있도록 Gemini Enterprise 액세스 권한을 부여합니다.
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
3. 로컬 환경 변수 설정
배포 명령어를 간소화하고 오타를 방지하려면 터미널 세션에서 프로젝트 ID를 환경 변수로 설정하세요.
export PROJECT_ID="<YOUR_PROJECT_ID>"
4. ADK CLI를 사용하여 배포
ADK CLI는 Cloud Run에 에이전트를 배포하는 간소화된 명령어를 제공합니다.
가상 환경이 활성화되어 있고 bloggeragent 프로젝트 디렉터리에 있는지 확인한 후 배포 명령어를 실행합니다.
# Deploy using ADK
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=us-east1 \
--service_name=bloggeragent \
--with_ui \
. \
-- \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global
배포 프로세스 중에 터미널에 다음 두 가지 질문이 표시됩니다.
- 저장소 생성 확인:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created. Do you want to continue (Y/n)?
Y를 입력하고 Enter 키를 누릅니다. - 인증되지 않은 액세스 허용:
Allow unauthenticated invocations to [bloggeragent] (y/N)?
y를 입력하고 Enter 키를 누릅니다. 이렇게 하면 브라우저에서 ADK 웹 UI에 공개적으로 액세스할 수 있습니다.
5. 배포된 에이전트에 액세스
배포가 완료되면 명령어에서 URL이 출력됩니다. 브라우저에서 해당 URL을 열어 공개적으로 액세스할 수 있는 라이브 ADK 웹 UI에 액세스하세요.
9. 삭제
Google Cloud 계정에 지속적으로 비용이 청구되지 않도록 하려면 이 Codelab 중에 생성된 리소스를 삭제하세요.
1. Cloud Run 서비스 삭제
배포된 bloggeragent 서비스를 삭제합니다.
gcloud run services delete bloggeragent --region=us-east1 --quiet
2. Artifact Registry 저장소 삭제
빌드된 컨테이너 이미지를 저장하기 위해 만든 Docker 저장소를 삭제합니다.
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet
3. 로컬 서버 중지
로컬 ADK 서버를 중지하려면 실행 중인 터미널에서 CTRL+C를 누르고 가상 환경을 비활성화합니다.
deactivate
10. 축하합니다
축하합니다. Google의 ADK와 Gemini를 사용하여 첫 번째 AI 에이전트를 빌드했습니다.
학습한 내용
- AI 에이전트의 핵심 개념 (추론 및 행동)
- Google ADK를 사용하여 멀티 에이전트 시스템을 빌드하는 방법
- 웹 UI를 사용하여 에이전트를 실행하고 테스트하는 방법
다음 단계
- 에이전트에 도구 (예: 웹 검색 또는 API 호출)를 추가해 보세요.
- MCP 서버를 통합하는 동영상 2를 기대해 주세요.