메모리 및 MCP가 포함된 ADK 에이전트 패턴

1. 학습할 내용

ADK 마스터 클래스 - 멀티 에이전트 시스템 여정에 오신 것을 환영합니다

이제 AI 에이전트의 흥미로운 세계로 들어서게 됩니다. 단순히 질문에 답변하는 챗봇은 잊으세요. 복잡한 작업을 추론, 계획, 도구 사용을 통해 수행할 수 있는 정교한 자율 시스템을 빌드하기 위해 Agent Development Kit (ADK)를 자세히 살펴보겠습니다.

이 Codelab 전체가 실습 여정입니다. 세션의 모든 코드와 예시가 포함된 1 GitHub 저장소 입니다. github repo

이 가이드를 마치면 다음 작업을 할 수 있습니다.

• 첫 번째 AI 에이전트 빌드: 사용자의 요구사항을 이해하고, Google 검색과 같은 도구를 사용하고, 자세하고 유용한 응답을 생성할 수 있는 완전한 기능을 갖춘 에이전트를 처음부터 빌드합니다.
• 멀티 에이전트 시스템 구성: 에이전트가 작업을 다른 전문 에이전트에게 위임하여 함께 작업하는 AI 전문가팀을 만드는 혁신적인 개념인 "에이전트-도구" 패턴을 알아봅니다.
• 복잡한 워크플로 조정: 단순한 위임을 넘어 라우터, 순차 체인, 루프, 병렬 실행과 같은 고급 패턴을 숙달하여 거의 모든 요청을 처리할 수 있는 강력하고 효율적이며 지능적인 애플리케이션을 빌드합니다.
• 에이전트에게 메모리 제공: 후속 질문을 처리하고, 의견을 통해 학습하고, 다단계 작업을 원활하게 관리할 수 있도록 하는 대화형 메모리의 중요한 역할을 이해합니다.
• MCP와 연결: MCP 도구 상자와 연결합니다.

지금 시작해 보세요. 🚀

2. 설정: API 키 가져오기

Google AI Studio API 키 설정

이 Codelab은 무료 Google AI Studio API 키에서 완전히 실행됩니다. Google Cloud 프로젝트, 결제 계정 또는 크레딧이 필요하지 않습니다. 메모리 (세션 6) 및 MCP (세션 7)를 포함한 모든 세션이 키에 대해 로컬 로 실행됩니다. 각 학습자는 자체 키를 사용하므로 API 할당량은 공유되지 않고 개인별로 적용됩니다.

필요한 항목:

• Python 3.9 이상 (python3 --version으로 확인)
• Google 계정 (AI Studio 키를 만드는 데 사용)
• 터미널 - 로컬 머신 또는 Cloud Shell 모두 작동
• 약 10분

AI 에이전트를 구동하려면 Google AI Studio의 Gemini API 키가 필요합니다. 가장 빠르게 시작하는 방법입니다.

1단계 - AI Studio에서 Gemini API 키 가져오기 (1분)

1. 새 브라우저 탭에서 https://aistudio.google.com/app/apikey를 엽니다.
2. Google 계정으로 로그인합니다.
3. 'API 키 만들기' (오른쪽 상단)를 클릭합니다.
4. 프로젝트 드롭다운이 있는 대화상자가 열립니다.

• 이전에 Google 프로젝트를 만든 경우: 프로젝트를 선택하고 '기존 프로젝트에서 API 키 만들기'를 클릭합니다.
• 목록에 없는 경우: '프로젝트 만들기'를 클릭합니다.

5. 표시되는 API 키를 복사 합니다. AIza...로 시작하고 약 40자입니다.

✏️ 안전한 곳에 붙여넣습니다. 아래 4단계에서 필요합니다.

API 키를 비밀번호처럼 취급합니다. 공개 채팅이나 스크린샷에 붙여넣거나 공개 GitHub 저장소에 커밋하지 마세요.

2단계 - 저장소 클론하기 (1분)

👉💻 터미널 (또는 Cloud Shell)을 열고 가이드 저장소를 클론합니다.

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

3단계 - 가상 환경 만들기 및 종속 항목 설치

👉💻 .adk_env라는 가상 환경을 만들고 활성화한 다음 종속 항목을 설치합니다.

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

터미널 프롬프트의 시작 부분에 (.adk_env)가 표시됩니다.

4단계 - 🔥 중요: API 키 추가

⚠️ 이 단계를 건너뛰지 마세요. adk_tutorial 폴더의 루트 에 .env 파일을 만듭니다. 이 파일 하나가 이 Codelab의 모든 세션 을 구동합니다. ADK 웹 세션 (1~5)과 명령줄 메모리 및 MCP 세션 (6~7)이 모두 자동으로 읽습니다.

👉💻 키로 .env 파일을 만듭니다 (your_actual_api_key_here를 1단계의 키로 바꿉니다).

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

이제 ~/adk_tutorial/.env에 다음이 포함되어야 합니다.

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 중요: your_actual_api_key_here를 1단계의 실제 API 키로 바꿉니다 (AIza...로 시작).

⚠️ GOOGLE_GENAI_USE_VERTEXAI가 FALSE 로 설정되어 있는지 확인합니다. 이렇게 하면 ADK가 Vertex AI 대신 Google AI Studio API 키로 인증됩니다.

✅ 체크포인트: AIza... 키가 포함된 .env 파일이 ~/adk_tutorial/.env에 있고 터미널 프롬프트에 (.adk_env)가 표시됩니다. 이제 에이전트를 빌드할 준비가 되었습니다.

3. 세션 1: ADK 웹의 첫 번째 에이전트

다음을 실행하여 ADK 웹을 엽니다.

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

명령어를 실행하면 다음과 같이 ADK 웹 서버가 시작되었음을 나타내는 출력이 터미널에 표시됩니다.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 그런 다음 브라우저에서 http://localhost:8000 을 열어 ADK 개발 UI 에 액세스합니다.

로컬이 아닌 Cloud Shell에서 실행하시나요? Cloud Shell 툴바 (일반적으로 오른쪽 상단)에서 웹 미리보기 아이콘을 클릭하고 포트 변경을 선택한 다음 포트를 8000으로 설정하고 "변경 및 미리보기"를 클릭합니다. Cloud Shell에서 새 브라우저 탭에 ADK 개발 UI가 열립니다.

👉 소환 의식이 완료되었으며 이제 에이전트가 실행 중입니다. 브라우저의 ADK 개발 UI 는 Familiar에 직접 연결됩니다.

첫 번째 에이전트 선택 UI 상단의 드롭다운 메뉴에서 a_single_agent 를 선택합니다.

여기에서 a_single_agent 를 선택할 수 있습니다.

여기에서 추적을 확인할 수 있습니다.

👉 테스트 프롬프트:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. 세션 2: 워크플로 에이전트: 순차 에이전트, 병렬 에이전트, 루프 에이전트

세션 1 단계에 따라 ADK 웹 UI를 엽니다.

병렬 에이전트

병렬 워크플로 에이전트 선택 UI 상단의 드롭다운 메뉴에서 b2_parallel_agent 를 선택합니다.

👉 테스트 프롬프트:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

여기에서 b2_parallel_agent 를 선택할 수 있습니다.

여기에서 추적을 확인할 수 있습니다.

순차 에이전트

순차 워크플로 에이전트 선택 UI 상단의 드롭다운 메뉴에서 b1_sequential_agent 를 선택합니다.

👉 테스트 프롬프트:

Find a good sushi near Standford and tell me how to get there.

여기에서 b1_sequential_agent 를 선택할 수 있습니다.

여기에서 추적을 확인할 수 있습니다.

루프 에이전트

루프 워크플로 에이전트 선택 UI 상단의 드롭다운 메뉴에서 b3_loop_agent 를 선택합니다.

👉 테스트 프롬프트:

Plan a trip from Sunnyvale to San Francisco today.

여기에서 b3_loop_agent 를 선택할 수 있습니다.

여기에서 추적을 확인할 수 있습니다.

5. 세션 3: 커스텀 에이전트

세션 1 단계에 따라 ADK 웹 UI를 엽니다.

ADK 웹 UI가 열리면 드롭다운에서 c_custom_agent 를 선택합니다.

👉 테스트 프롬프트:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

여기에서 c_custom_agent 를 선택할 수 있습니다.

여기에서 추적을 확인할 수 있습니다.

6. 세션 4: 오케스트레이터 패턴 - 라우팅 에이전트

세션 1 단계에 따라 ADK 웹 UI를 엽니다.

ADK 웹 UI가 열리면 드롭다운에서 d_routing_agent 를 선택합니다.

👉 테스트 프롬프트:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

여기에서 d_routing_agent 를 선택할 수 있습니다.

여기에서 추적을 확인할 수 있습니다.

7. 세션 5: 도구로서의 에이전트

세션 1 단계에 따라 ADK 웹 UI를 엽니다.

ADK 웹 UI가 열리면 드롭다운에서 e_agent_as_tool 을 선택합니다.

👉 테스트 프롬프트:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

여기에서 e_agent_as_tool 을 선택할 수 있습니다.

여기에서 추적을 확인할 수 있습니다.

8. 세션 6: 장기 메모리가 있는 에이전트

완전히 로컬에서 실행됩니다. 이 세션은 대화 메모리를 로컬 SQLite 데이터베이스 (~/.adk/ 아래)에 저장하므로 Google Cloud, 결제 또는 크레딧 없이 다시 시작해도 환경설정이 유지됩니다. 에이전트는 설정에서 만든 ~/adk_tutorial/.env에서 AI Studio 키를 읽습니다.

👉💻 폴더로 이동하고 실행기를 사용하여 에이전트를 구동하여 장기 메모리를 테스트합니다.

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 테스트 프롬프트:

I like Art and Italian food.

그런 다음 Ctrl+C 를 눌러 세션을 종료합니다. 세션을 다시 시작합니다.

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 테스트 프롬프트:

Plan a trip to San Francisco based on my preference.

✅ 에이전트는 이전 실행에서 "미술과 이탈리아 음식"을 기억해야 합니다. 이는 세션 간에 작동하는 장기 메모리입니다.

9. 세션 7: MCP로 에이전트 역량 강화

완전히 로컬에서 실행됩니다. 이 세션은 로컬 SQLite 데이터베이스 (destinations.db)를 읽는 로컬 MCP 도구 상자 서버를 시작합니다. Google Cloud, 결제 또는 크레딧이 필요하지 않습니다. 유일한 외부 다운로드는 오픈소스 MCP 도구 상자 바이너리입니다.

1단계: 로컬 데이터베이스 준비

👉💻 저장소 루트에서 샘플 데이터베이스를 만듭니다.

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

이렇게 하면 ~/adk_tutorial/에 destinations.db가 생성됩니다.

⚠️ 샘플 데이터베이스에는 파리, 로마, 뉴욕, 도쿄의 4개 도시만 포함되어 있습니다. (관광명소 유형: 랜드마크, 박물관, 공원) 다른 도시 (예: 샌프란시스코 또는 서니베일)를 참조하는 프롬프트는 이러한 행이 존재하지 않으므로 결과 없음을 올바르게 반환합니다. 이 세션을 테스트할 때는 위의 4개 도시를 사용하세요.

2단계: MCP 도구 상자 서버 설치 및 실행

👉💻 운영체제 용 MCP 도구 상자 바이너리를 다운로드합니다.

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

다운로드가 완료되면 실행합니다.

chmod +x toolbox

어떤 Mac을 사용하고 있는지 잘 모르는 경우 uname -m을 실행합니다. arm64 = Apple Silicon, x86_64 = Intel. Windows 에서는 .../windows/amd64/toolbox.exe를 다운로드하고 PowerShell에서 실행합니다.

3단계

한 터미널에서 다음 명령어를 실행합니다 (실행 상태로 둡니다. 에이전트가 http://127.0.0.1:7001에서 연결됨).

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

다른 터미널에서 다음 명령어를 실행합니다.

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 테스트 프롬프트 (샘플 데이터베이스에 있는 도시인 파리, 로마, 뉴욕, 도쿄를 사용합니다.)

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

세션 7 문제 해결

• "연결 거부됨" / 에이전트가 도구를 찾지 못함: 첫 번째 터미널의 도구 상자 서버가 실행되고 있지 않습니다. 다시 시작하고 포트 7001에서 수신 대기 중인지 확인합니다.
• 모든 쿼리가 빈 결과를 반환함: 1단계 를 실행하여 ~/adk_tutorial/destinations.db가 있는지, 프롬프트에서 4개 도시 (파리, 로마, 뉴욕, 도쿄) 중 하나를 사용하는지 확인합니다.
• toolbox: cannot execute binary file macOS에서: Linux 빌드를 다운로드했습니다. 2단계를 OS=darwin/arm64 (Apple Silicon) 또는 OS=darwin/amd64 (Intel)로 다시 실행합니다.