1. 소개
최신 에이전트 스택
프로덕션 등급 AI 에이전트를 빌드하려면 대규모 언어 모델 (LLM)만으로는 부족합니다. LLM은 추론 기능을 제공하지만 강력한 에이전트는 외부 세계와 상호작용하고, 대화 상태를 관리하고, 시간이 지남에 따라 사용자 환경설정을 기억해야 합니다.
이 워크숍에서는 세 가지 기본 기술을 사용하여 포괄적인 에이전트 시스템을 설계하고 빌드하는 방법을 알아봅니다.
- 연결 (MCP): 에이전트가 로컬 도구 및 데이터에 액세스할 수 있도록 합니다.
- 조정 (ADK): 에이전트의 추론 루프와 상태를 관리합니다.
- 메모리 (메모리 뱅크): 장기적인 맞춤 컨텍스트를 제공합니다.
핵심 개념
구성요소 | 함수 |
Model Context Protocol(MCP) | 맞춤 통합 없이 AI 모델을 외부 시스템 (데이터베이스, 파일 시스템, API)에 연결하는 범용 표준입니다. |
에이전트 개발 키트(ADK) | 이벤트 루프, 상태 전환, 도구 실행을 관리하여 에이전트의 런타임 환경을 제공하는 프레임워크 |
세션 서비스 | 단기 메모리를 처리합니다. 이 기능은 즉각적인 대화 컨텍스트 (예: '사용자가 방금 무엇을 물었지?')이지만 세션이 종료되면 삭제됩니다. |
Vertex AI Memory Bank | 장기 메모리를 처리합니다. 사용자별 사실과 환경설정 (예: '사용자가 Python을 선호함')을 무기한으로 저장하여 에이전트가 향후 상호작용을 맞춤설정할 수 있습니다. |
Vertex AI Agent Engine | 대규모로 에이전트 로직 및 메모리 구성요소를 호스팅하는 관리형 인프라 서비스입니다. |
빌드할 항목
이러한 개념을 설명하기 위해 Holiday Design Assistant를 빌드합니다. 이 에이전트는 높은 수준의 사용자 요청을 처리하고 로컬 Python 도구를 자율적으로 오케스트레이션하여 맞춤 코드와 이미지를 생성할 수 있습니다.
다음 세 단계를 진행합니다.
- 도구 레이어: MCP 서버를 만들어 로컬 Python 함수를 AI에 노출합니다.
- 에이전트 레이어: ADK를 사용하여 다단계 워크플로를 계획하고 실행하는 에이전트를 빌드합니다.
- 메모리 레이어: 메모리 뱅크를 통합하여 에이전트가 사용자 스타일 환경설정을 학습하고 기억하도록 지원합니다.
2. 설정
AI 에이전트를 지원하려면 두 가지가 필요합니다. 기반을 제공하는 Google Cloud 프로젝트와
1부: 결제 계정 사용 설정
- 배포에 필요한 5달러 크레딧으로 결제 계정을 청구합니다. Gmail 계정으로 로그인해야 합니다.
2부: 개방형 환경
- 👉 이 링크를 클릭하여 Cloud Shell 편집기로 바로 이동하세요.
- 👉 오늘 언제든지 승인하라는 메시지가 표시되면 승인을 클릭하여 계속합니다.
- 👉 터미널이 화면 하단에 표시되지 않으면 다음을 실행하여 엽니다.
- 보기를 클릭합니다.
- 터미널을 클릭합니다.
- 👉💻 터미널에서 다음 명령어를 사용하여 이미 인증되었는지, 프로젝트가 프로젝트 ID로 설정되었는지 확인합니다.
gcloud auth list - 👉💻 GitHub에서 부트스트랩 프로젝트를 클론합니다.
git clone https://github.com/cuppibla/holiday_workshop - 👉💻 프로젝트 디렉터리에서 설정 스크립트를 실행합니다.
cd ~/holiday_workshop ./init.sh - 👉💻 필요한 프로젝트 ID를 설정합니다.
gcloud config set project $(cat ~/project_id.txt) --quiet
3부: 권한 설정
- 👉💻 다음 명령어를 사용하여 필요한 API를 사용 설정합니다. 이 과정에 몇 분 정도 소요될 수 있습니다.
gcloud services enable \ cloudresourcemanager.googleapis.com \ servicenetworking.googleapis.com \ run.googleapis.com \ aiplatform.googleapis.com \ compute.googleapis.com - 👉💻 터미널에서 다음 명령어를 실행하여 필요한 권한을 부여합니다.
. ~/holiday_workshop/set_env.sh
.env 파일이 생성됩니다. 프로젝트 정보가 표시됩니다.
3. MCP로 성능 강화
AI의 'USB-C' 시대
새 마우스를 구매할 때마다 마더보드에 납땜해야 한다고 상상해 보세요. 최근까지 AI 도구의 상태는 이와 같았습니다. 개발자는 LLM을 데이터베이스, 파일 시스템 또는 API에 연결하기 위해 맞춤 '글루 코드'를 작성해야 했습니다.
모델 컨텍스트 프로토콜 (MCP)을 입력합니다. MCP를 AI 애플리케이션용 USB-C 포트라고 생각하면 됩니다. AI 모델을 데이터 소스 및 도구에 연결하는 표준화된 방법을 제공합니다.
도구용 MCP 서버를 한 번 빌드하면 코드 한 줄을 변경하지 않고도 Gemini CLI, IDE 또는 기타 MCP 호환 클라이언트에 연결할 수 있습니다.
빌드할 항목
이 Codelab에서는 다음 작업을 실행하는 Holiday Design Assistant를 빌드합니다.
- MCP를 사용하여 로컬 환경에 연결 (스튜디오 도구)
- 에이전트 개발 키트 (ADK)를 사용하여 대화 컨텍스트를 안정적으로 관리합니다.
- 사용자의 환경설정을 기억합니다 (예: 'Python 코드를 선호해')를 Vertex AI 메모리 뱅크를 사용하여 여러 세션에서 유지할 수 있습니다.
서버 로직 빌드
환경은 준비되었지만 서버 로직이 불완전합니다. 에이전트가 결국 연하장을 만드는 데 사용할 네 가지 특정 도구를 구현해야 합니다.
1부: 서버 스켈레톤 열기
01-MCP-Files-Testing/01-starter 디렉터리에서 작업합니다.
- Cloud Shell 터미널에서 올바른 디렉터리에 있는지 확인합니다.
cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/ - 다음 명령어를 실행하여 Cloud Shell 편집기에서 파일을 엽니다.
cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
보일러플레이트 코드 (MCP 서버 설정, 연결 처리, Vertex AI 클라이언트 초기화)가 이미 완료되어 있습니다. 하지만 현재 네 가지 핵심 기능은 빈 자리표시자입니다.
2부: 연말연시 장면 생성기 구현
먼저 사용자의 관심분야 (예: '새')를 입력하면 이미지 생성에 최적화된 풍부하고 자세한 프롬프트로 변환합니다.
generate_holiday_scene 함수 내에서 #REPLACE_GENERATE_HOLIDAY_SCENE 주석을 찾습니다.
이 전체 행을 다음 코드로 바꿉니다.
prompt = (
f"""
Create a cozy, high-fidelity 3D render of a winter holiday scene.
The scene should be warm and inviting with soft cinematic lighting.
Seamlessly integrate the following specific theme/interest into the
holiday decor or landscape: {interest}.
The style should be whimsical but detailed.
Aspect Ratio: 16:9 Landscape.
"""
)
generate_image(prompt, "16:9", "static/generated_scene.png")
return "Done! Saved at generated_scene.png"
3부: 최종 사진 결과 구현
마지막으로 조명과 스타일이 포토리얼리스틱하고 축제 분위기를 내도록 합니다.
#REPLACE_GENERATE_FINAL_PHOTO 댓글을 찾습니다.
최종 스타일 전송 및 렌더링을 실행하려면 이 전체 줄을 다음 코드로 바꿉니다.
prompt = (
"""
Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
Lighting: Warm, glowing ambient light from a fire below (out of frame).
Background: Softly blurred (bokeh) pine garland and twinkling lights.
Foreground Composition:
1. A wooden picture frame containing the [attached selfie image].
The face in the photo must be clearly visible.
2. A folded holiday greeting card standing upright next to the frame.
The front of the card displays the [attached holiday scene image] as a print.
Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
"""
)
generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
return "Done! Saved at generated_final_photo.png"
환경 설정
이제 코드가 준비되었으므로 종속 항목이 설치되어 있는지 확인해야 합니다. 여기에서는 빠른 Python 패키지 및 프로젝트 관리자인 uv를 사용합니다.
👉💻 터미널에서 다음을 실행하여 FastMCP를 프로젝트의 종속 항목으로 추가합니다.
cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp
~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml 파일에 새 종속 항목 fastmcp>=2.13.3가 추가됩니다.
4. MCP 서버용 Gemini CLI로 테스트
이제 서버 코드가 완성되었는데 어떻게 테스트해야 할까요?
일반적으로 백엔드 서버를 테스트하려면 프런트엔드 UI를 빌드하거나 복잡한 curl 요청을 작성해야 합니다. 하지만 여기서는 Gemini CLI를 사용할 수 있습니다.
이는 로직을 격리하므로 개발에 매우 유용합니다. 웹 인터페이스나 에이전트 프레임워크를 빌드하는 데 신경 쓰기 전에 모델이 도구를 이해하고 올바르게 호출하는지 확인할 수 있습니다.
연결 및 실행
mcp add 명령어를 사용하여 서버를 관리하도록 Gemini CLI에 지시합니다.
터미널에서 다음을 실행합니다.
gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
add holidays: 서버에 닉네임 ('holidays')을 지정했습니다.uv run ...: 방금 수정한 Python 서버를 시작하는 명시적 명령어를 제공했습니다.
상상을 현실로 만드세요!
이제 채팅 세션을 시작합니다.
gemini
다음 프롬프트를 사용하여 Gemini가 새 도구를 '볼' 수 있는지 테스트해 보세요. Gemini CLI에서 Google의 공휴일 도구를 사용하도록 허용해야 할 수 있습니다.
- 👉 사용자:
"I want to create a festive holiday photo. I like birds a lot." - Gemini:
*Thinking...* *Calling tool: generate_holiday_scene(interest='birds')* Done! Saved at generated_scene.png - 👉 사용자:
"Great! Now generate a knitting pattern for a sweater with reindeer on it." - Gemini:
*Thinking...* *Calling tool: generate_sweater_pattern(motif='reindeer')* Done! Saved at generated_pattern.png
사진 검토
Control+C를 눌러 Gemini CLI를 종료합니다.~/holiday_workshop/01-MCP-Files-Testing/01-starter/static폴더에서 생성된 사진을 확인합니다.
여기에서 사진을 검토하세요. 
결론 및 다음 단계
축하합니다. 작동하는 MCP 서버를 빌드했습니다. 이제 패턴을 생성하고, 이미지를 합성하고, 장면을 개선할 수 있는 기능적인 'AI 도구' 세트가 있습니다.
하지만 위의 테스트에서 뭔가 눈에 띄는 점이 있었나요? 사용자가 프로세스를 주도해야 했습니다. 장면을 요청하고, 그런 다음 패턴을 요청하고, 그런 다음 이를 결합해 달라고 요청해야 했습니다.
Gemini는 스마트하지만, 스웨터에 패턴을 넣기 전에 패턴을 생성하고 이미지 생성이 실패할 경우 오류를 처리해야 하는 복잡한 프로덕션 워크플로에서는 더 많은 제어가 필요합니다. YouTube는 모든 단계에서 도움을 주지 않아도 자체적으로 계획하고, 자신의 작업을 비판하고, 연하장 상태를 관리할 수 있는 전용 시스템을 원합니다.
다음 섹션에서는 이 창의적인 혼란을 정리합니다. 에이전트 개발 키트 (ADK)를 구현하여 이러한 MCP 도구를 완벽한 프로덕션 파이프라인으로 조정하는 구조화된 에이전트를 빌드할 예정입니다.
5. ADK 에이전트 바이브 코딩
Google에는 작동하는 도구 세트 (MCP 서버)가 있지만 현재는 Gemini에 호출할 도구와 시기를 정확하게 알려주는 등 모든 작업을 Google에서 수행하고 있습니다.
이 섹션에서는 추론하고, 계획하고, 다단계 작업을 자율적으로 실행할 수 있는 시스템인 AI 에이전트를 빌드합니다. 이를 위해 에이전트 개발 키트 (ADK)를 사용합니다.
에이전트란 무엇인가요?
MCP 도구가 '손' (작업 수행)이라면 에이전트는 '두뇌'입니다. 에이전트는 LLM을 사용하여 사용자의 의도 ('휴일 카드를 만들어 줘')를 이해하고, 이를 단계별로 분류 ('먼저 장면이 필요하고, 그다음에 패턴이 필요해...')하고, 목표를 달성하기 위해 사용할 도구를 결정합니다.
ADK란 무엇인가요?
에이전트 개발 키트 (ADK)는 이러한 에이전트를 쉽게 빌드할 수 있도록 지원하는 Google의 프레임워크입니다. 채팅 기록 관리, 도구 연결, 다양한 모델 간 전환과 같은 복잡한 '배관'을 처리하므로 앱의 개성과 논리에 집중할 수 있습니다.
컨텍스트 기반 바이브 코딩
단일 대규모 프롬프트를 사용하여 코드를 생성하는 것이 일반적인 패턴입니다. 하지만 복잡한 애플리케이션을 빌드할 때는 AI를 시간이 지남에 따라 컨텍스트를 유지하는 파트너로 취급하는 것이 더 나은 경우가 많습니다.
코드를 한 줄도 작성하기 전에 Gemini CLI의 메모리 기능을 사용하여 준비 작업을 진행합니다.
1. 환경 준비
터미널을 열고 스타터 디렉터리로 이동합니다.
cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter
Gemini CLI를 시작합니다.
gemini
2. 컨텍스트 및 메모리 관리
바이브 코딩을 할 때 AI는 누구인지, 무엇을 알고 있는지 알아야 합니다. Gemini CLI를 사용하면 이를 명시적으로 관리할 수 있습니다.
/memory show: AI가 현재 프로젝트 및 세션에 대해 알고 있는 내용을 확인하려면 이를 입력하세요./memory add: AI가 대화 중에 기억해야 하는 기본 지식을 삽입하는 데 사용합니다.
먼저 코딩 파트너의 페르소나를 정의해 보겠습니다. Gemini CLI 내에서 다음 명령어를 실행합니다.
/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."
이제 Gemini가 자신의 역할을 이해합니다. 이 컨텍스트는 이후의 모든 대답에 영향을 미쳐 ADK를 준수하는 고품질 코드를 보장합니다.
3. 1단계: 기본 에이전트의 분위기 코딩
전체 시스템을 한 번에 생성하려고 하지 말고 스켈레톤부터 시작해 보겠습니다. 파일 구조와 기본 에이전트 페르소나를 설정하려고 합니다.
Gemini CLI에 다음 프롬프트를 입력합니다.
Let's start by building the basic agent structure.
Please create a file structure for a `root_agent`.
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant".
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.
Gemini가 파일 구조와 초기 Python 코드를 생성합니다. 검토하여 올바른지 확인한 다음 변경사항을 적용/수락합니다.
4. 2단계: MCP 서버 추가 (도구)
이제 기본 에이전트가 있으므로 '손'을 제공해야 합니다. 이전 실습에서 빌드한 MCP 서버에 에이전트를 연결해야 합니다.
Gemini CLI에 다음 프롬프트를 입력합니다.
Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.
이제 Gemini가 기존 agent.py를 리팩터링하여 도구 정의와 연결 로직을 포함합니다.
참고: 작업을 확인하거나 생성된 코드가 예상대로 작동하지 않는 경우 ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution에 있는 참조 솔루션과 파일을 비교하면 됩니다.
6. 에이전트 웹 인터페이스 실행
ADK에는 adk web라는 기본 제공 테스트 인터페이스가 함께 제공됩니다. 이렇게 하면 경량 채팅 UI가 실행되어 에이전트와 즉시 대화할 수 있습니다.
- GeminiCLI가 아직 열려 있는 경우
control+C키를 눌러 닫습니다. 이제 터미널에서(solution폴더에 있음) 다음을 실행합니다(starter폴더로 이동하여starter폴더에서uv run adk web를 실행하여 코드를 테스트할 수 있음).cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution uv run adk web --port 8000 - Cloud Shell에서 8000 포트에서 서비스가 실행 중이라는 알림을 표시합니다. 'Web Preview'(웹 미리보기) -> 'Preview on port 8000'(포트 8000에서 미리보기)을 클릭합니다.
에이전트 테스트
이제 채팅 인터페이스가 표시됩니다. 에이전트가 새 안내를 따르고 MCP 도구에 올바르게 액세스하는지 확인해 보겠습니다.
다음 프롬프트를 사용해 보세요.
- '안녕하세요. 누구세요?'
- (축제 분위기의 열정적인 대답을 기대해 줘.)
- '휴일 카드에 사용할 배경이 필요해. 눈 덮인 마을로 만들어 줘'
- (상담사는
generate_holiday_scene에 전화해야 합니다. 시스템 요청 사항에 정의된 '귀여운/만화' 스타일이 자동으로 적용되는 것을 확인할 수 있습니다.
- (상담사는
- '작은 피자 조각이 있는 스웨터 패턴을 생성해 줘.'
- (상담사는
generate_sweater_pattern에 전화해야 합니다.)
- (상담사는
생성된 이미지는 여기에서 확인할 수 있습니다.
테스트를 완료한 경우 Control+C 키를 눌러 종료합니다.
결론 및 다음 단계
이제 컨텍스트 인식 접근 방식을 사용하여 Google ADK 에이전트를 '바이브 코딩'했습니다.
- 컨텍스트 설정:
/memory add을 사용하여 전문가 페르소나를 정의했습니다. - 반복적으로 빌드: 먼저 스켈레톤을 만든 다음 도구 연결을 추가했습니다.
내장 ADK 웹 미리보기는 테스트에 적합하지만 최종 제품에는 맞춤 브랜드 환경이 필요합니다. 다음 섹션에서는 이 에이전트를 맞춤 웹 프런트엔드에 통합합니다.
7. UI와 ADK 연결
이제 에이전트 정의가 있으므로 이를 실행해야 합니다. 이때 러너와 세션 서비스가 사용됩니다.
구현
- 👉 명령어에 다음을 입력합니다.
cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py이 열립니다. # TODO: Create Session Service를 다음으로 바꿉니다.from google.adk.sessions import InMemorySessionService from google.adk.memory import InMemoryMemoryService session_service = InMemorySessionService() memory_service = InMemoryMemoryService()# TODO: Initialize Runner를 다음으로 바꿉니다.runner = Runner( app_name="agents", agent=christmas_agent, session_service=session_service, memory_service=memory_service, )
~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py(조치 필요 없음)에서 158번째 줄을 검토하세요. 애플리케이션이 최종 응답을 가져오는 방법이 궁금한 경우 다음은 러너로 구동되는 이벤트 루프입니다.async for event in runner.run_async( user_id=user_id, session_id=session_id, new_message=content )
심층 분석: 아키텍처 및 배포
FastAPI를 사용하여 이 에이전트를 제공합니다.
- FastAPI를 사용해야 하는 이유: 에이전트는 I/O 바운드 (LLM 대기)인 경우가 많습니다. FastAPI의 비동기 특성은 이 문제를 완벽하게 처리합니다.
- 상태 비저장: API 엔드포인트가 상태 비저장입니다. 전역 범위에 변수를 저장하지 않습니다. Google은
session_id와SessionService를 사용하여 모든 요청의 상태를 재구성합니다. 즉, Cloud Run (서버리스)에 배포하고 0으로 확장할 수 있습니다.
8. 에이전트 매직으로 애플리케이션 사용해 보기
- 👉💻 명령어에 다음을 입력합니다.
cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter ./start_app.sh~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py이 열립니다. - 아래와 같은 결과가 표시됩니다.
👉👉 http://localhost:5173/을 클릭하거나 새 창을 열고http://localhost:5173/을 입력하세요. - 그러면 채팅 인터페이스가 있는 웹사이트가 표시됩니다.
- 이미지 하나를 업로드하여 테스트합니다(본인 또는 반려동물 가능).
- 👉 그런 다음
Can you generate a picture my cat wearing snowflake pattern sweater?
- 👉💻 테스트를 완료한 후 터미널에서
control+C를 눌러 프로세스를 종료합니다.
예상대로 작동하지 않는 경우 ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution로 이동하여 ./start_app.sh를 실행한 다음 위와 동일한 단계를 수행하면 됩니다.
9. Vertex AI Memory Bank는
단기 메모리와 장기 메모리
- 단기 컨텍스트: '내가 방금 뭐라고 했지?' (세션 기록) 채팅 창이 닫히면 이 정보는 손실됩니다.
- 장기 기억: '내가 가장 좋아하는 프로그래밍 언어는 뭐야?' (사용자 환경설정) 이 값은 영구적으로 유지되어야 합니다.
Vertex AI 메모리 뱅크는 이러한 장기 스토리지를 제공합니다. 상담사가 사용자에 관한 맞춤 정보를 저장하고 검색할 수 있습니다.
세션과 메모리 뱅크
- 세션 (
VertexAiSessionService): 로그입니다. 모든 메시지, 도구 호출, 이벤트 (AppendEvent,ListEvents)의 원시적인 시간 순서 시퀀스를 저장합니다. 무슨 일이 일어났는지에 대한 정답을 제공합니다. - 메모리 뱅크 (
VertexAiMemoryBankService): 지식입니다. 합성된 장기적 사실 (GenerateMemories,RetrieveMemories)을 저장합니다. 특정user_id로 범위가 지정되어 개인 정보 보호 및 격리가 보장됩니다.
- 👉💻 명령어에 다음을 입력합니다.
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py이 열립니다. # TODO: Create Vertex AI Session Service & Memory Bank Service를 찾아 전체 줄을 다음으로 바꿉니다.session_service = VertexAiSessionService( project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID ) memory_service = VertexAiMemoryBankService( project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID )
- 👉💻 명령어에 다음을 입력합니다.
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py이 열립니다. # TODO: Set Up Configuration를 다음으로 바꿉니다.# Basic configuration types MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig SimilaritySearchConfig = ( types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig ) GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig # Advanced configuration types CustomizationConfig = types.MemoryBankCustomizationConfig MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample ConversationSource = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource ) ConversationSourceEvent = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent ) ExampleGeneratedMemory = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory )
- 👉 동일한 파일:
04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py# TODO: Set up topic를 찾아 전체 줄을 다음으로 바꿉니다.custom_topics = [ # Topic 1: Sweater Preference MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="sweater_preference", description="""Extract the user's preferences for sweater styles, patterns, and designs. Include: - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.) - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted) - Color preferences (red, green, navy, pastel, etc.) - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft) - Themes (retro, modern, ugly christmas sweater, elegant) Example: "User wants a retro style sweater with a pixelated reindeer pattern." Example: "User prefers dark blue colors and hates itchy wool." """, ) ), # Topic 2: Personal Context MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="personal_context", description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include: - Hobbies and activities (skiing, reading, gaming, cooking, etc.) - Pets (type, breed, name, color) - Job or profession if relevant to their style - General interests (sci-fi, nature, vintage, tech) - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach) Example: "User has a golden retriever named Max." Example: "User loves skiing and wants a snowy mountain background." Example: "User is a software engineer who likes cyberpunk aesthetics." """, ) ) ] - 👉 동일한 파일:
04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py# TODO: Create Agent Engine를 찾아 전체 줄을 다음으로 바꿉니다.agent_engine = client.agent_engines.create( config={ "display_name": AGENT_DISPLAY_NAME, "context_spec": { "memory_bank_config": { "generation_config": { "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash" }, "customization_configs": [customization_config] } }, } )
프롬프트를 사용하면 안 되나요?
'사용자의 기록을 프롬프트에 붙여넣으면 안 되나요?'라고 물을 수 있습니다.
- 크기 제한: 컨텍스트 윈도우는 크지만 무한하지는 않습니다. 5년의 기록을 모두 표시할 수는 없습니다.
- 비용: 'Hello'마다 토큰 100만 개를 처리하는 것은 비용이 너무 많이 듭니다.
- 집중: 메모리 뱅크는 에이전트의 검색 엔진 역할을 합니다. 관련성 있는 사실만 가져옵니다.
- 👉💻 명령어에 다음을 입력합니다.
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py이 열립니다. - 파일
~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py에서# TODO: Add PreloadMemoryTool을 다음으로 바꿉니다.if USE_MEMORY_BANK: agent_tools.append(PreloadMemoryTool())
PreloadMemoryTool 및 add_session_to_memory
agent.py에는 다음과 같은 두 가지 주요 구성요소가 있습니다.
PreloadMemoryTool: 상담사가 'Google 자체'를 검색할 수 있는 도구입니다. 사용자가 '내가 자주 마시는 커피를 가져와 줘'와 같이 모호한 질문을 하면 에이전트는 이 도구를 사용하여 메모리 뱅크에 '커피 선호도'를 쿼리한 후 대답할 수 있습니다.add_session_to_memory: 백그라운드 콜백입니다.- 비동기를 사용하는 이유 메모리를 저장하는 데 시간이 걸립니다 (채팅 요약, 사실 추출). 사용자가 이를 기다리게 해서는 안 됩니다.
after_agent_callback을 사용하여 백그라운드 (add_session_to_memory)에서 실행합니다.
- 비동기를 사용하는 이유 메모리를 저장하는 데 시간이 걸립니다 (채팅 요약, 사실 추출). 사용자가 이를 기다리게 해서는 안 됩니다.
10. Memory Bank In Action
- 👉💻 명령어에 다음을 입력합니다.
cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter ./use_memory_bank.sh
~/holiday_workshop/.env파일을 확인하면 (조치 필요 없음)이 표시됩니다.USE_MEMORY_BANK=TRUE AGENT_ENGINE_ID={agent_engine_id} - 👉💻 애플리케이션 UI로 메모리를 테스트합니다. 명령어에 다음을 입력합니다.
cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter ./start_app.shhttp://localhost:5173/을 클릭하거나 새 창을 열고http://localhost:5173/을 입력합니다.Uvicorn running on http://0.0.0.0:8000은 백엔드 서버일 뿐 클릭하려는 실제 링크가 아닙니다. 이제 웹사이트의 채팅 인터페이스가 맞춤형 에이전트가 되었습니다. - 👉메모리를 테스트합니다. UI에 입력하는 경우:
I want a sweater that matches my dog. He's a golden retriever.I'm a programmer, so I want something geeky. Maybe a matrix style?I like snowflake sweater pattern
에이전트는 이를 환경설정으로 식별하고 메모리 뱅크에 저장합니다.
다음 주(또는 Control+C 및 ./start_app.sh로 애플리케이션을 다시 시작할 때)에 다음과 같이 질문하면
what is my preference on sweater pattern?
에이전트는 메모리 뱅크에 쿼리하고, 선호도를 확인하고, 요청하지 않아도 스웨터 패턴을 생성합니다. 
- Vertex AI Agent Engine에서 Google Cloud 콘솔 Agent Engine으로 이동하여 확인합니다.
- 왼쪽 상단의 프로젝트 선택기에서 프로젝트를 선택해야 합니다.
- 이전 명령에서 배포한 에이전트 엔진을 확인합니다.
use_memory_bank.sh
방금 만든 에이전트 엔진을 클릭합니다.
- 왼쪽 상단의 프로젝트 선택기에서 프로젝트를 선택해야 합니다.
- 배포된 이 에이전트에서
Memories탭을 클릭하면 모든 메모리를 확인할 수 있습니다.
축하합니다. 방금 메모리 뱅크를 에이전트에 연결했습니다.
11. 결론
요약
완전한 에이전트 시스템을 성공적으로 설계하고 구축했습니다.
- 연결: MCP를 사용하여 에이전트가 로컬 도구에 액세스하는 방식을 표준화했습니다.
- 오케스트레이션: ADK를 사용하여 다단계 작업에 필요한 복잡한 추론 루프를 관리했습니다.
- 개인화: 메모리 뱅크를 사용하여 사용자 컨텍스트를 기억하는 지속적인 학습 레이어를 만들었습니다.
다음 단계
- 자체 MCP 서버 빌드: 내부 API 또는 데이터베이스용 서버를 만듭니다.
- ADK 패턴 살펴보기: ADK 문서에서 '추론 루프' 및 '오케스트레이션'에 대해 알아봅니다.
- 배포: 로컬 스크립트에서 Cloud Run의 프로덕션 서비스로 에이전트를 가져옵니다.