이 Codelab 정보
1. 개요
지금 AI로 빌드를 시작하려면 어떻게 해야 하나요? 대부분의 경우 '모델이 내가 생각하고 있는 이 문제를 해결하는 데 실제로 도움이 될 수 있을까?'라는 간단한 질문으로 시작합니다. 이때 Google AI 스튜디오가 유용합니다. 여기에서 무엇이든 빠르게 프로토타입을 제작할 수 있습니다. 주방을 리모델링하고 싶은데 Gemini가 도움이 될 것 같습니다. 저는 엔지니어이지 일반 건축업자가 아닙니다. 무엇을 요청해야 할지 모르겠네요. 규정, 비품 등 고려해야 할 사항이 너무 많습니다. 따라서 이를 세분화하고 Gemini가 매우 상세한 프롬프트를 생성하도록 한 다음 전체 리노베이션 계획을 생성하고 리모델링을 시각화해 보겠습니다. 하지만 잠깐만요. 여기에서 비즈니스 확장에 실제로 어떻게 도움이 될 수 있나요? AGENTS를 입력합니다.
에이전트는 AI 모델과 소통하면서 보유한 도구와 컨텍스트를 사용해 목표 기반 작업을 수행하는 자율 프로그램으로, 진실에 기반한 자율적 의사 결정을 할 수 있습니다.
에이전트 개발 키트 (ADK)
에이전트 개발 키트 (ADK)는 AI 에이전트를 개발하고 배포하기 위한 유연하고 모듈식 프레임워크입니다. ADK는 여러 개의 고유한 에이전트 인스턴스를 멀티 에이전트 시스템 (MAS)으로 구성하여 정교한 애플리케이션 빌드를 지원합니다.
ADK에서 멀티 에이전트 시스템은 계층 구조를 형성하는 경우가 많은 여러 에이전트가 협력하거나 조정하여 더 큰 목표를 달성하는 애플리케이션입니다. 이렇게 애플리케이션을 구성하면 향상된 모듈성, 전문성, 재사용성, 유지보수성, 전용 워크플로 에이전트를 사용하여 구조화된 제어 흐름을 정의하는 기능 등 상당한 이점을 얻을 수 있습니다.
빌드할 항목
프로토타입 프롬프트에서 에이전트 빌드로 전환할 준비가 되셨나요? 주방 리노베이션 프로젝트의 제안서 문서를 생성하는 데 도움이 되는 상담사를 만듭니다. 이 실습에서는 다음을 수행합니다.
- ADK로 리노베이션 제안서 문서를 생성하는 간단한 에이전트 빌드
- 생성된 리노베이션 제안서 문서를 Cloud Storage 버킷에 저장합니다.
- Cloud Shell 및 에이전트 웹 출력에서 에이전트 테스트
요구사항
2. 시작하기 전에
프로젝트 만들기
- Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
- Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요 .
- 또한 이 글을 읽고 Google Cloud를 시작하고 ADK를 사용하는 데 도움이 되는 크레딧을 받고 싶다면 이 링크를 사용하여 크레딧을 사용하세요.
- 여기의 안내에 따라 사용할 수 있습니다. 이 링크는 2025년 7월 15일까지만 사용할 수 있습니다.
- 이 링크를 클릭하여 Cloud Shell을 활성화합니다. Cloud Shell에서 해당 버튼을 클릭하여 Cloud Shell 터미널 (클라우드 명령어 실행용)과 편집기 (프로젝트 빌드용) 간에 전환할 수 있습니다.
- Cloud Shell에 연결되면 다음 명령어를 사용하여 이미 인증되었는지, 프로젝트가 프로젝트 ID로 설정되어 있는지 확인합니다.
gcloud auth list
- Cloud Shell에서 다음 명령어를 실행하여 gcloud 명령어가 프로젝트를 알고 있는지 확인합니다.
gcloud config list project
- 프로젝트가 설정되지 않은 경우 다음 명령어를 사용하여 설정합니다.
gcloud config set project <YOUR_PROJECT_ID>
- Python 3.9 이상이 설치되어 있어야 합니다.
다른 gcloud 명령어 및 사용법은 문서를 참고하세요.
3. 프로토타입
Google AI Studio로 이동합니다. 프롬프트에 입력을 시작합니다. 프롬프트는 다음과 같습니다.
I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.
최적의 응답을 얻으려면 오른쪽에 있는 매개변수를 조정하고 구성합니다.
이 간단한 설명을 바탕으로 Gemini가 리노베이션을 시작할 수 있도록 매우 자세한 프롬프트를 제공했습니다. Google은 Gemini를 사용하여 AI 스튜디오와 Google 모델에서 더 나은 대답을 얻고 있습니다. 사용 사례에 따라 사용할 모델을 선택할 수도 있습니다.
Gemini 2.5 Pro를 선택했습니다. 이는 사고 모델이므로 긴 형식의 분석과 상세한 문서에 대해 더 많은 출력 토큰(이 경우 최대 65,000개)을 얻을 수 있습니다. Gemini 사고 상자는 네이티브 추론 기능이 있고 긴 컨텍스트 요청을 받을 수 있는 Gemini 2.5 Pro를 사용 설정하면 제공됩니다.
아래에서 응답 스니펫을 확인하세요.
AI 스튜디오가 데이터를 분석하여 캐비닛, 카운터탑, 백플래시, 바닥재, 세면대, 일관성, 색상 팔레트, 재료 선택 등 모든 항목을 생성했습니다. Gemini에서 출처를 언급하기도 합니다.
이제 다른 프롬프트를 사용하여 아이디어를 실현해 보세요.
- 이 프롬프트를 복사하여 프롬프트 편집기에 붙여넣습니다.
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
- 현재 주방의 이미지를 첨부하세요. 샘플 주방 이미지를 사용할 수도 있습니다.
- 이미지를 생성할 수 있도록 모델을 'Gemini 2.0 Flash 미리보기 이미지 생성'으로 변경합니다.
다음과 같은 출력이 표시되었습니다.
이것이 바로 Gemini의 장점입니다.
동영상 이해부터 기본 이미지 생성, Google 검색으로 실제 정보에 그라운딩하는 작업까지 Gemini로만 가능한 작업이 있습니다.
AI 스튜디오에서 이 프로토타입을 가져와 API 키를 가져온 후 Vertex AI ADK의 기능을 사용하여 전체 에이전트 애플리케이션으로 확장할 수 있습니다.
4. ADK 설정
이제 '시작하기 전에' 섹션에서 활성화한 Cloud Shell 터미널로 이동하겠습니다.
- 가상 환경 만들기 및 활성화 (권장)
Cloud Shell 터미널에서 가상 환경을 만듭니다.
python -m venv .venv
가상 환경을 활성화합니다.
source .venv/bin/activate
- ADK 설치
pip install google-adk
5. 프로젝트 구조
- Cloud Shell 터미널에서 원하는 프로젝트 위치에 대리인 앱의 루트 디렉터리를 만듭니다.
mkdir agentic-apps
- 기본 디렉터리 내에 현재 프로젝트와 관련된 폴더를 하나 만듭니다.
mkdir renovation-agent
- Cloud Shell 편집기로 이동하여 파일을 만들어 다음 프로젝트 구조를 만듭니다 (처음에는 비어 있음).
renovation-agent/
__init__.py
agent.py
requirements.txt
.env
6. 소스 코드
- 'init.py'로 이동하여 다음 콘텐츠로 업데이트합니다.
from . import agent
- agent.py로 이동하여 다음 경로의 다음 콘텐츠로 파일을 업데이트합니다.
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/agent.py
agent.py에서는 필요한 종속 항목을 가져오고 .env 파일에서 구성 매개변수를 가져오며 제안서 문서를 생성하고 Cloud Storage 버킷에 저장하는 root_agent를 정의합니다. Cloud Storage 단계를 실행하려면 store_pdf라는 도구를 사용합니다.
- Cloud Storage 버킷이 있는지 확인
상담사가 생성하는 제안서 문서를 저장하기 위함입니다. Vertex AI로 만드는 에이전트 시스템이 액세스할 수 있도록 만들고 액세스를 프로비저닝합니다. 방법은 다음과 같습니다.
https://cloud.google.com/storage/docs/creating-buckets#console
버킷 이름을 'next-demo-store'로 지정합니다. 다른 이름을 지정하는 경우 ENV 변수 설정 단계에서 .env 파일의 STORAGE_BUCKET 값을 업데이트해야 합니다.
- 버킷에 대한 액세스 권한을 설정하려면 Cloud Storage 콘솔로 이동하여 스토리지 버킷으로 이동합니다 (이 경우 버킷 이름은 'next-demo-storage'임: https://console.cloud.google.com/storage/browser/next-demo-storage).
'권한 -> 주 구성원 보기 -> 액세스 권한 부여'로 이동합니다. 'allUsers'를 'Principals'로, 'Storage Object User'를 'Role'로 선택합니다.
Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
- 종속 항목 목록 만들기
requirements.txt에 모든 종속 항목을 나열합니다. 저장소에서 복사할 수 있습니다.
단일 에이전트 시스템 소스 코드 설명
agent.py 파일은 에이전트 개발 키트 (ADK)를 사용하여 주방 리노베이션 멀티 에이전트 시스템의 구조와 동작을 정의합니다. 주요 구성요소를 살펴보겠습니다.
에이전트 정의
루트 에이전트 (Orchestrator): proposal_agent
root_agent는 이 단일 에이전트 시스템의 조정자 역할을 합니다. 초기 리노베이션 요청을 수신하고 요청의 요구사항에 따라 호출할 도구를 결정합니다.
그런 다음 root_agent는 도구에서 응답을 수집하고 이를 결합하여 사용자에게 포괄적인 응답을 제공합니다. 이 경우 'store_pdf'라는 도구가 하나만 있습니다.
7. 데이터 흐름 및 주요 개념
사용자가 ADK 인터페이스 (터미널 또는 웹 UI)를 통해 요청을 시작합니다.
- root_agent에서 요청을 수신합니다.
- root_agent는 요청을 분석하고 필요한 경우 도구로 라우트합니다.
- 'store_pdf' 도구는 수정된 텍스트 콘텐츠를 PDF 파일에 작성한 다음 Google Cloud Storage에 업로드하도록 설계되었습니다.
- 그러면 root_agent에 응답이 반환됩니다.
- root_agent는 응답을 결합하고 사용자에게 최종 출력을 제공합니다.
LLM (대규모 언어 모델)
에이전트는 텍스트를 생성하고, 질문에 답변하고, 추론 작업을 실행하는 데 LLM을 많이 사용합니다. LLM은 상담사가 사용자 요청을 이해하고 응답하는 기능의 '두뇌'입니다. 이 애플리케이션에서는 Gemini 2.5를 사용합니다.
Google Cloud Storage
생성된 리노베이션 제안서 문서를 저장하는 데 사용됩니다. 버킷을 만들고 상담사가 액세스하는 데 필요한 권한을 부여해야 합니다.
Cloud Run (선택사항)
OrderingAgent는 Cloud Run 함수를 사용하여 AlloyDB와 상호작용합니다. Cloud Run은 HTTP 요청에 대한 응답으로 코드를 실행하는 서버리스 환경을 제공합니다.
AlloyDB
OrderingAgent를 사용하는 경우 주문 정보를 저장할 AlloyDB 데이터베이스를 설정해야 합니다.
.env 파일
.env 파일에는 API 키, 데이터베이스 사용자 인증 정보, 버킷 이름과 같은 민감한 정보가 저장됩니다. 이 파일을 안전하게 보관하고 저장소에 커밋하지 않는 것이 중요합니다. 또한 상담사 및 Google Cloud 프로젝트의 구성 설정을 저장합니다. root_agent 또는 지원 함수는 일반적으로 이 파일에서 값을 읽습니다. .env 파일에서 모든 필수 변수가 올바르게 설정되어 있는지 확인합니다. 여기에는 Cloud Storage 버킷 이름이 포함됩니다.
8. 모델 설정
사용자 요청을 이해하고 응답을 생성하는 상담사의 기능은 대규모 언어 모델 (LLM)을 기반으로 합니다. 에이전트는 인증 사용자 인증 정보가 필요한 이 외부 LLM 서비스를 안전하게 호출해야 합니다. 유효한 인증이 없으면 LLM 서비스에서 에이전트의 요청을 거부하고 에이전트가 작동하지 않습니다.
- Google AI Studio에서 API 키를 가져옵니다.
- .env 파일을 설정하는 다음 단계에서
<<your API KEY>>를 실제 API 키 값으로 바꿉니다.
9. ENV 변수 설정
- 이 저장소의 템플릿 .env 파일에서 매개변수 값을 설정합니다. 제 경우에는 .env에 다음과 같은 변수가 있습니다.
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>
자리표시자를 값으로 바꿉니다.
10. 에이전트 실행
- 터미널을 사용하여 상위 디렉터리로 이동합니다.
cd agentic-apps/renovation-agent
- 모든 종속 항목 설치
pip install -r requirements.txt
- Cloud Shell 터미널에서 다음 명령어를 실행하여 에이전트를 실행할 수 있습니다.
adk run .
- 다음을 실행하여 ADK 프로비저닝된 웹 UI에서 실행할 수 있습니다.
adk web
- 다음 프롬프트를 사용하여 테스트합니다.
user>>
Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.
