이 페이지는 Cloud Translation API를 통해 번역되었습니다.

ADK, MCP 도구 상자, AlloyDB로 스포츠 상점 에이전트 AI 어시스턴트 빌드

1. 소개

빌드할 항목

이 Codelab에서는 스포츠 용품점 에이전트 AI 어시스턴트를 빌드하는 방법을 알아봅니다. ADK, MCP 도구 상자, AlloyDB로 구동되는 차세대 에이전트 AI 애플리케이션은 다음과 같은 다양한 작업을 지원합니다.

자연어를 사용하여 제품을 검색합니다.
추천 제품을 구매할 수 있는 주변 매장을 찾습니다.
새 주문하기
기존 주문 상태를 확인합니다.
선호하는 배송 방법으로 주문을 업데이트합니다.

학습할 내용

PostgreSQL용 AlloyDB 데이터베이스 프로비저닝 및 채우기
PostgreSQL용 AlloyDB 인스턴스로 데이터베이스용 MCP 도구 상자 설정
에이전트 개발 키트 (ADK)를 사용하여 스포츠 매장 문의를 지원하는 AI 에이전트 설계 및 개발
클라우드 환경에서 에이전트 및 데이터베이스용 MCP 도구 상자 테스트
지능형 에이전트 응답을 위해 AlloyDB의 고급 쿼리 기능 활용

필요한 항목

이 Codelab을 완료하려면 다음이 필요합니다.

Chrome 웹브라우저
Gmail 계정
결제가 사용 설정된 Google Cloud 프로젝트

이 Codelab은 초보자를 포함한 모든 수준의 개발자를 대상으로 합니다.

2. 시작하기 전에

이 섹션에서는 스포츠 용품점 에이전트 AI 어시스턴트 빌드를 시작하기 전에 Google Cloud 프로젝트에서 필요한 초기 설정을 안내합니다.

프로젝트 만들기

Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요 .
이 링크를 클릭하여 Cloud Shell을 활성화합니다. Cloud Shell에서 해당 버튼을 클릭하여 Cloud Shell 터미널 (클라우드 명령어 실행)과 편집기 (프로젝트 빌드) 간에 전환할 수 있습니다.

Cloud Shell에 연결되면 다음 명령어를 사용하여 인증이 완료되었고 프로젝트가 해당 프로젝트 ID로 설정되었는지 확인합니다.

gcloud auth list

Cloud Shell에서 다음 명령어를 실행하여 gcloud 명령어가 프로젝트를 알고 있는지 확인합니다.

gcloud config list project

PROJECT_ID 변수를 설정합니다. 다음 명령어를 사용하여 설정하세요.

export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID

다음 명령어를 실행하여 다음 API를 사용 설정합니다.

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com

3. AlloyDB 인스턴스 만들기

이 섹션에서는 AlloyDB 데이터베이스 클러스터와 인스턴스를 설정하고 AI 에이전트에 필요한 네트워킹 및 권한을 구성합니다.

먼저 Cloud Shell 터미널에서 다음 명령어를 실행하여 AlloyDB 클러스터를 만듭니다.

gcloud alloydb clusters create alloydb-cluster \
    --password=alloydb\
    --network=default \
    --region=us-central1 \
    --database-version=POSTGRES_16

AlloyDB는 안전하고 고성능 액세스를 위해 비공개 IP 연결을 사용합니다. Google에서 Google 관리형 서비스 네트워킹 인프라에 대한 서비스 피어링 연결에 사용할 수 있도록 VPC 내에 비공개 IP 범위를 할당해야 합니다. 다음 명령어를 실행합니다.

gcloud compute addresses create peering-range-for-alloydb \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=16 \
    --description="Automatically allocated IP range for service networking" \
    --network=default

다음으로 VPC 서비스 피어링 연결을 만듭니다. 이를 통해 Google Cloud Virtual Private Cloud (VPC) 네트워크가 AlloyDB를 비롯한 Google의 관리형 서비스와 안전하고 비공개로 통신할 수 있습니다. 다음 명령어를 실행합니다.

gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges=peering-range-for-alloydb \
--network=default

이제 AlloyDB 클러스터 내에 기본 인스턴스를 만듭니다. 애플리케이션이 연결할 실제 데이터베이스 엔드포인트입니다. 다음 명령어를 실행하여 AlloyDB 인스턴스를 만듭니다.

gcloud alloydb instances create alloydb-inst \
     --instance-type=PRIMARY \
     --cpu-count=2 \
     --region=us-central1 \
     --cluster=alloydb-cluster \
     --availability-type=ZONAL \
     --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED

참고: 인스턴스를 만드는 데 약 10분이 걸릴 수 있습니다. 이 작업이 완료될 때까지 기다린 후 계속 진행하세요.

Vertex AI 통합 사용 설정

AlloyDB 인스턴스가 벡터 검색 쿼리 (시맨틱 검색과 같은 AI 기능에 필수적임)를 실행하고 Vertex AI에 배포된 모델을 호출하도록 허용하려면 AlloyDB 서비스 에이전트에 Vertex AI 권한을 부여해야 합니다.

먼저 IAM 바인딩에 필요하므로 Google Cloud 프로젝트 번호를 가져옵니다.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

그런 다음 Vertex AI 권한을 AlloyDB 서비스 에이전트에 부여합니다.

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

공개 IP 사용 설정

다음 단계를 준비하기 위해 AlloyDB 인스턴스에서 공개 IP 연결을 사용 설정합니다.

콘솔에서 화면 상단 중앙에 있는 검색 필드로 이동하여 'alloydb'를 입력한 다음, 공개 IP 연결 섹션으로 이동하여 수정합니다. '공개 IP 사용 설정' 체크박스를 선택하고 Cloud Shell 머신의 IP 주소를 입력합니다.

Cloud Shell 머신의 IP를 확인하려면 Cloud Shell 터미널로 이동하여 'ifconfig | grep -A 1 eth0' 명령어를 입력합니다. 결과에서 마지막 두 자리를 마스크 크기 '/16'으로 0.0으로 바꿉니다. 예를 들어 XX가 숫자인 경우 'XX.XX.0.0/16'과 같이 표시됩니다.

인스턴스 수정 페이지의 승인된 외부 네트워크 '네트워크' 텍스트 상자에 이 IP를 붙여넣습니다.

참고: 업데이트 작업은 최대 3분이 걸릴 수 있습니다.

4. 데이터베이스 로드

스토어 데이터베이스 만들기

이제 데이터베이스를 만들고 스포츠 매장의 초기 데이터를 로드할 차례입니다.

psql가 Cloud Shell에서 비공개 AlloyDB 인스턴스에 연결할 수 있도록 하려면 AlloyDB 인증 프록시를 사용합니다. 이 유틸리티는 데이터베이스에 대한 연결을 안전하게 터널링합니다. (AlloyDB 인증 프록시 참고)

다음 명령어를 사용하여 AlloyDB 인증 프록시를 다운로드합니다.

wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.3/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

실행 파일로 만듭니다.

chmod +x alloydb-auth-proxy

첫 번째 Cloud Shell 터미널 창에서 이 명령어를 실행합니다. 프록시는 백그라운드에서 실행되며 연결을 전달합니다.

./alloydb-auth-proxy "projects/$PROJECT_ID/locations/us-central1/clusters/alloydb-cluster/instances/alloydb-inst" --public-ip

중요: 이 터미널 창을 열어 두고 프록시를 실행합니다. 닫지 마세요.

Cloud Shell에서 새 터미널 창을 엽니다 (상단의 'Cloud Shell 터미널' 탭 옆에 있는 + 아이콘 클릭).

psql을 사용하여 AlloyDB 인스턴스에 연결합니다.

psql -h 127.0.0.1 -U postgres

참고: 메시지가 표시되면 클러스터 생성 중에 postgres 사용자에 대해 설정한 비밀번호를 입력합니다 (문서를 직접 따르는 경우 비밀번호는 alloydb임).

애플리케이션의 저장소 데이터베이스를 만듭니다 (명령어를 하나씩 실행).

CREATE DATABASE store;
\c store
exit

Source Code(소스 코드)

이제 Codelab의 소스 코드 저장소를 클론합니다. 클론하기 전에 홈 디렉터리 또는 적절한 위치에 있는지 확인하고 다음 명령어를 실행합니다.

git clone https://github.com/mtoscano84/sports-agent-adk-mcp-alloydb.git

데이터베이스 채우기

복제된 프로젝트의 data 폴더로 이동하여 데이터베이스 덤프 파일에 액세스합니다.

cd sports-agent-adk-mcp-alloydb/data

그런 다음 저장소의 store_backup.sql 파일을 사용하여 샘플 데이터 세트를 store 데이터베이스로 가져옵니다.

psql -h 127.0.0.1 -U postgres -d store -f store_backup.sql

참고: 이 가져오기 중에 일부 경고 및 오류 메시지가 표시될 수 있지만 이 Codelab에서는 무시해도 됩니다. 덤프에 전체 스키마가 포함된 경우 이러한 메시지는 이미 존재하는 권한 또는 객체와 관련이 있는 경우가 많습니다. 무시할 수 있는 경고와 오류가 표시됩니다.

5. 승인 서비스 설정

이 섹션에서는 애플리케이션의 승인 서비스를 설정합니다. 이 서비스는 액세스를 보호하고 AI 에이전트의 프롬프트 인젝션 취약점으로부터 보호하는 데 매우 중요합니다.

먼저 store 데이터베이스의 users 테이블에 샘플 사용자를 추가합니다. 이 사용자는 애플리케이션에서 인증에 사용됩니다.

콘솔로 이동하여 AlloyDB로 이동하고 기본 인스턴스와 AlloyDB Studio를 선택합니다.

메시지가 표시되면 클러스터를 설정할 때 만든 사용자 인증 정보를 사용하여 AlloyDB Studio에 로그인합니다.

사용자 이름: 'postgres'
데이터베이스: 'store'
비밀번호: 'alloydb'

SQL 편집기에서 INSERT 문을 실행하여 데이터베이스에 사용자를 추가합니다. 이름, 성, 이메일 주소를 변경합니다.

중요:

위치를 예시와 같이 유지합니다.
Google Cloud Console에 등록할 때 사용하는 이메일 주소를 사용합니다.

INSERT INTO users (user_id, first_name, last_name, Address, city, postal_code, location, email)
VALUES (10,'John', 'Doe', 'Carrer Muntaner 39', 'Barcelona', '08019', '0101000020E61000008AAE0B3F38B144401FBB0B9414780140', 'john.doe@example.com');

다음으로 프로젝트의 OAuth 동의 화면을 구성해야 합니다. 이 화면은 애플리케이션이 사용자의 Google 계정에 대한 액세스를 요청할 때 사용자에게 표시되며 애플리케이션의 브랜드를 정의합니다.

콘솔에서 'API 및 서비스', 'Google OAuth 동의'로 이동합니다.

애플리케이션의 브랜드를 만들려면 다음 정보를 제공하세요.

앱 이름: '스포츠 쇼핑 에이전트 AI'
사용자 지원 이메일: 'YOUR_EMAIL'
잠재고객: '외부'
연락처 정보: 'YOUR_EMAIL'

이제 프런트엔드 애플리케이션이 Google로 사용자 ID를 검증하는 데 사용할 OAuth 클라이언트 ID를 만듭니다.

먼저 Google Cloud 프로젝트 번호가 있는지 확인합니다. 이는 리디렉션 URI를 올바르게 구성하는 데 필요합니다. Cloud Shell 터미널에서 다음 명령어를 실행합니다.

이 Cloud Shell 터미널 창에서 PROJECT_ID 변수가 설정되지 않은 경우 다음을 실행합니다.

export PROJECT_ID=[YOUR_PROJECT_ID]

그런 다음 다음 명령어를 사용하여 PROJECT_NUMBER를 가져옵니다.

gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

그런 다음 'API 및 서비스' -> '사용자 인증 정보' -> '사용자 인증 정보 만들기' -> 'OAuth 클라이언트 ID'로 이동합니다.

다음 정보를 사용하여 사용자 인증 정보를 만드세요.

애플리케이션 유형: '웹 애플리케이션'
이름: '스포츠 쇼핑 에이전트 AI 앱'

승인된 JavaScript 원본:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

승인된 리디렉션 URI:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

참고: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app은 이 Codelab의 뒷부분에서 설정할 프런트엔드 애플리케이션의 예상 배포 URL입니다. [YOUR_PROJECT_NUMBER] 를 복사한 실제 번호로 바꿔야 합니다.

중요: 생성 후 팝업에 OAuth 클라이언트 ID와 클라이언트 보안 비밀이 표시됩니다. 나중에 프런트엔드를 구성할 때 필요하므로 OAuth 클라이언트 ID를 안전한 곳에 저장합니다.

6. 데이터베이스용 MCP 도구 상자 설정

툴박스는 애플리케이션의 오케스트레이션 프레임워크와 데이터베이스 사이에 위치하여 도구를 수정, 배포 또는 호출하는 데 사용되는 제어 영역을 제공합니다. 도구를 저장하고 업데이트할 수 있는 중앙 위치를 제공하여 도구 관리를 간소화하므로, 상담사와 애플리케이션 간에 도구를 공유하고 애플리케이션을 다시 배포하지 않고도 도구를 업데이트할 수 있습니다.

데이터베이스용 MCP 도구 상자에서 지원하는 데이터베이스 중 하나가 AlloyDB이고 이전 섹션에서 이미 프로비저닝했으므로 도구 상자를 설정해 보겠습니다.

먼저 Cloud Shell 환경에서 MCP Toolbox 서버를 로컬로 설정하여 기능을 확인합니다.

Cloud Shell 터미널에서 클론된 프로젝트 저장소 내에 있는 toolbox 폴더로 이동합니다.

cd sports-agent-adk-mcp-alloydb/src/toolbox

다음 명령어를 실행하여 Toolbox 바이너리를 다운로드하고 실행 권한을 부여합니다.

# see releases page for other versions
export VERSION=0.7.0

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

chmod +x toolbox

참고: 여기서는 버전 0.7.0이 지정됩니다. 프로덕션 환경에서는 항상 도구 상자 출시 페이지에서 최신 안정화 버전을 확인하고 사용하세요.

Cloud Shell 편집기로 이동합니다 (편집기 아이콘을 클릭하여 터미널에서 전환할 수 있음).

동일한 sports-agent-adk-mcp-alloydb/src/toolbox 디렉터리에서 tools.yaml이라는 파일을 찾을 수 있습니다. 이 파일을 열고 이전 단계의 OAuth 클라이언트 ID와 Google Cloud 프로젝트 ID로 자리표시자를 업데이트합니다.

tools.yaml 이해하기

소스는 도구가 상호작용할 수 있는 다양한 데이터 소스를 나타냅니다. 소스는 도구가 상호작용할 수 있는 데이터 소스를 나타냅니다. tools.yaml 파일의 소스 섹션에서 소스를 맵으로 정의할 수 있습니다. 일반적으로 소스 구성에는 데이터베이스와 연결하고 상호작용하는 데 필요한 모든 정보가 포함됩니다.

도구는 에이전트가 취할 수 있는 작업(예: 소스 읽기 및 쓰기)을 정의합니다. 도구는 상담사가 SQL 문을 실행하는 등 취할 수 있는 작업을 나타냅니다. tools.yaml 파일의 도구 섹션에서 도구를 맵으로 정의할 수 있습니다. 일반적으로 도구는 작업을 수행할 소스가 필요합니다.

tools.yaml 구성에 대한 자세한 내용은 이 문서를 참고하세요.

데이터베이스용 MCP 도구 상자 서버 실행

(mcp-toolbox 폴더에서) 다음 명령어를 실행하여 서버를 시작합니다.

./toolbox --tools-file "tools.yaml"

이제 클라우드에서 웹 미리보기 모드로 서버를 열면 애플리케이션의 모든 도구와 함께 Toolbox 서버가 실행되는 것을 확인할 수 있습니다.

MCP Toolbox Server는 기본적으로 포트 5000에서 실행됩니다. Cloud Shell을 사용하여 이를 테스트해 보겠습니다.

아래와 같이 Cloud Shell에서 웹 미리보기를 클릭합니다.

포트 변경을 클릭하고 아래와 같이 포트를 5000으로 설정한 후 변경 및 미리보기를 클릭합니다.

다음과 같은 출력이 표시됩니다.

데이터베이스용 MCP 툴킷에서는 도구를 검증하고 테스트할 수 있는 Python SDK를 설명하며, 이 내용은 여기에 문서화되어 있습니다. 이 섹션에서는 이러한 도구를 활용하는 에이전트 개발 키트 (ADK)로 바로 이동합니다.

Toolbox를 Cloud Run에 배포해 보겠습니다.

툴박스 서버를 다른 애플리케이션 및 AI 에이전트와 통합할 수 있는 공개 엔드포인트로 액세스할 수 있도록 하려면 Cloud Run에 배포합니다. Cloud Run에서 Toolbox를 호스팅하는 방법에 대한 자세한 안내는 여기를 참고하세요.

Cloud Shell 터미널로 돌아와서 toolbox 폴더로 이동합니다.

cd sports-agent-adk-mcp-alloydb/src/toolbox

PROJECT_ID 환경 변수가 Google Cloud 프로젝트 ID로 설정되어 있는지 확인합니다.

export PROJECT_ID=$PROJECT_ID

다음으로 프로젝트에서 다음 Google Cloud 서비스가 사용 설정되어 있는지 확인합니다.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com

Google Cloud Run에 배포할 Toolbox 서비스의 ID 역할을 할 별도의 서비스 계정을 만들어 보겠습니다. 또한 이 서비스 계정에 Secret Manager에 액세스하고 AlloyDB와 통신할 수 있는 올바른 역할이 있는지 확인합니다.

gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/secretmanager.secretAccessor


gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member='serviceAccount:toolbox-identity@'$PROJECT_ID'.iam.gserviceaccount.com' \
    --role='roles/alloydb.client'


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member='serviceAccount:toolbox-identity@'$PROJECT_ID'.iam.gserviceaccount.com' \
    --role='roles/serviceusage.serviceUsageConsumer'

그런 다음 tools.yaml 파일을 비밀로 업로드합니다. Cloud Run에 Toolbox를 설치해야 하므로 Toolbox의 최신 컨테이너 이미지를 사용하여 IMAGE 변수에 설정합니다.

gcloud secrets create tools --data-file=tools.yaml

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

마지막으로 다음 명령어를 사용하여 Toolbox 서버를 Cloud Run에 배포합니다. 이 명령어는 애플리케이션을 컨테이너화하고, 서비스 계정을 구성하고, 보안 비밀을 삽입하고, 공개적으로 노출합니다.

gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated

이렇게 하면 구성된 tools.yaml을 사용하여 Toolbox 서버를 Cloud Run에 배포하는 프로세스가 시작됩니다. 배포가 성공하면 다음과 유사한 메시지가 표시됩니다.

Deploying container to Cloud Run service [toolbox] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00002-dn2] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app

이제 브라우저에서 위에 나열된 서비스 URL을 방문할 수 있습니다. 앞서 본 'Hello World' 메시지가 표시됩니다. 다음 URL을 방문하여 사용 가능한 도구를 확인할 수도 있습니다.

https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app/api/toolset

Google Cloud 콘솔에서 Cloud Run으로 이동하면 Cloud Run의 서비스 목록에 Toolbox 서비스가 표시됩니다.

7. ADK로 빌드된 에이전트

이 섹션에서는 에이전트 개발 키트 (ADK)를 사용하여 빌드된 AI 에이전트를 Cloud Run에 배포합니다.

먼저 Cloud Run에서 에이전트를 빌드하고 배포하고 Artifact Registry 및 Cloud Storage와 상호작용하는 데 필요한 API를 프로젝트에서 사용 설정합니다. Cloud Shell 터미널에서 다음 명령어를 실행합니다.

gcloud services enable artifactregistry.googleapis.com \
                       cloudbuild.googleapis.com \
                       run.googleapis.com \
                       storage.googleapis.com

그런 다음 프로젝트의 기본 Compute 서비스 계정에 필요한 권한을 할당합니다. 먼저 Cloud Shell 터미널에서 다음 명령어를 실행하여 PROJECT_NUMBER를 가져옵니다.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

기본 Compute 서비스 계정에 권한을 할당합니다.

# Grant Cloud Run service account access to GCS
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/artifactregistry.writer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
--role="roles/artifactregistry.repoAdmin"

# Grant Vertex AI User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"

# Grant Vertex AI Model User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.modelUser"

에이전트를 도구에 연결

에이전트를 도구에 연결합니다. ADK의 맥락에서 도구는 AI 에이전트에게 제공되는 특정 기능을 나타내며, 이를 통해 에이전트는 핵심 텍스트 생성 및 추론 능력을 넘어 작업을 수행하고 세상과 상호작용할 수 있습니다.

이 경우 데이터베이스용 MCP 도구 상자에서 구성한 도구를 에이전트에 장착합니다.

Cloud Shell 편집기를 사용하여 sports-agent-adk-mcp-alloydb/src/backend/ 로 이동하고 다음 코드로 'finn_agent.py' 파일을 수정합니다. 이전 단계에서 배포된 MCP ToolBox 서버의 Cloud Run 서비스 URL을 사용하고 있습니다.

Cloud Run에 에이전트 배포

마지막으로 구성된 AI 에이전트를 Cloud Run에 배포하여 HTTP 엔드포인트를 통해 액세스할 수 있도록 합니다.

먼저 Artifact Registry에 에이전트의 컨테이너 이미지를 저장할 Docker 저장소를 만듭니다. Cloud Shell에서 다음 명령어를 실행합니다.

gcloud artifacts repositories create finn-agent-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-agent images"

다음으로 Cloud Build를 사용하여 에이전트의 Docker 이미지를 빌드합니다. 클론된 프로젝트 (sports-agent-adk-mcp-alloydb/)의 루트 디렉터리에서 다음 명령어를 실행합니다.

gcloud builds submit src/backend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent

이제 에이전트 서비스를 배포합니다. 이 명령어는 Cloud Run 서비스를 만들고, Artifact Registry에서 이미지를 가져오고, 환경 변수를 구성합니다.

gcloud run deploy finn-agent \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=us-central1,GOOGLE_GENAI_USE_VERTEXAI=TRUE"

참고: GOOGLE_CLOUD_PROJECT를 비롯한 환경 변수를 동적으로 설정합니다 (셸 변수 $PROJECT_ID 사용).

다음과 비슷한 출력이 표시되어 에이전트가 성공적으로 배포되었음을 나타냅니다.

Deploying container to Cloud Run service [finn-agent] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-agent] revision [finn-agent-00005-476] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-agent-359225437509.us-central1.run.app

마지막으로 Cloud Shell 터미널에서 다음 curl 명령어를 실행하여 에이전트를 테스트합니다.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}' \
  https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app/chat

다음과 비슷한 출력이 표시됩니다.

'안녕하세요! 저는 AI 스포츠 쇼핑 어시스턴트인 Finn입니다. 스포츠 제품, 장비, 용품을 찾을 수 있도록 도와드릴 수 있습니다. 무엇을 도와드릴까요?'

이제 AlloyDB, MCP 도구 상자, ADK를 사용하여 빌드한 에이전트의 배포가 검증되었습니다.

8. 프런트엔드 배포

이 섹션에서는 Cloud Run에 AI 어시스턴트의 대화형 사용자 인터페이스를 배포합니다. 이 프런트엔드는 React와 JavaScript를 사용하여 빌드됩니다.

배포하기 전에 배포된 에이전트의 URL과 OAuth 클라이언트 ID로 프런트엔드의 소스 코드를 업데이트해야 합니다.

Cloud Shell 편집기를 사용하여 sports-agent-adk-mcp-alloydb/src/frontend/src/pages/로 이동하고 Home.jsx 파일을 엽니다. 에이전트의 Cloud Run 서비스 URL 자리표시자를 업데이트해야 합니다. 그런 다음 이전 단계의 에이전트 Cloud Run 서비스 URL (예: https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app)에 복사합니다.

이제 sports-agent-adk-mcp-alloydb/src/frontend/src/components/로 이동하여 GoogleSignInButton.jsx 파일을 엽니다. '승인 서비스 설정' 섹션에서 획득한 OAuth 클라이언트 ID로 이 파일을 업데이트합니다.

Cloud Run에 프런트엔드 배포

이제 프런트엔드 애플리케이션이 구성되었으므로 Cloud Run에 배포할 수 있습니다.

루트 디렉터리 (sports-agent-adk-mcp-alloydb/)에서 Cloud Shell 터미널에 다음 명령어를 실행하여 프런트엔드 이미지용 Artifact Registry에 Docker 저장소를 만듭니다.

gcloud artifacts repositories create finn-frontend-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-frontend images"

다음으로 Cloud Build를 사용하여 프런트엔드 애플리케이션의 Docker 이미지를 빌드합니다. 프로젝트의 루트 디렉터리에서 다음 명령어를 실행합니다.

gcloud builds submit src/frontend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend

마지막으로 다음 명령어를 사용하여 Cloud Run에 프런트엔드를 배포합니다.

gcloud run deploy finn-frontend \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID

프런트엔드의 배포가 성공했음을 나타내는 다음과 비슷한 출력이 표시됩니다.

Deploying container to Cloud Run service [finn-frontend] in project [sport-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-frontend] revision [finn-frontend-00002-mwc] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-frontend-535807247199.us-central1.run.app

웹브라우저를 열고 이전 단계의 서비스 URL을 사용하여 AI 에이전트가 지원하는 새로 배포된 애플리케이션을 엽니다.

9. 에이전트 실행

이제 스포츠 스토어 에이전트 AI 어시스턴트인 Finn이 완전히 배포되어 구매를 지원할 수 있습니다.

웹브라우저를 열고 이전 단계의 프런트엔드 애플리케이션의 서비스 URL로 이동합니다. URL은 https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app 형식을 따릅니다.

프런트엔드가 로드되면 오른쪽 상단의 버튼 (일반적으로 '로그인' 또는 이와 유사한 메시지)을 클릭하여 Google 사용자 인증 정보를 사용하여 인증합니다. 이 작업은 이전에 설정한 OAuth 구성을 활용합니다.

인증에 성공하면 Finn과 상호작용할 수 있습니다. '지금 쇼핑하기' 버튼을 클릭하여 대화형 쇼핑 환경을 시작하세요.

다음 스크립트를 사용하여 AI 에이전트의 다양한 기능을 테스트합니다. 다음 프롬프트를 채팅 인터페이스에 하나씩 복사하여 붙여넣습니다.

핀, 안녕!
울트라 트레일용 러닝화를 찾고 있어.
Ultra Glide에 대해 자세히 알려줘
쇼핑 목록에 Ultra Glide, 사이즈 40, 색상 Red/Grey 추가해 줘
쇼핑 목록 보여 줘
내 주변 매장 찾기
내 쇼핑 목록을 사용해 Sports Diagonal Mar 매장에서 주문해 줘.
주문 상태 확인
Sports Diagonal Mar 매장의 배송 방법을 나열해 줘.
주문 [YOUR_ORDER_NUMBER]의 배송 방법을 특급 배송으로 업데이트해 줘.
주문 상태 확인
고마워요, 핀.

배포된 Finn Agent 및 해당 기능을 시각적으로 보여주는 데모는 아래 동영상을 확인하세요.

AlloyDB 기반 스포츠 에이전트 AI 어시스턴트 데모

10. 결과

이전 스크립트를 실행하여 ADK 에이전트의 완전한 통합, AlloyDB와의 연결, MCP 도구 상자의 활용을 검증했습니다. 이 섹션에서는 구현한 핵심 기능을 강조 표시합니다.

승인 서비스

데이터베이스용 MCP 도구 상자는 승인 서비스 (이 Codelab에서는 특히 Google 로그인)를 제휴하여 애플리케이션 내에서 사용자를 인증하는 기능을 제공합니다. MCP 도구 상자를 사용하면 도구가 호출될 때 OAuth 클라이언트 ID가 사용자 ID를 검증하는 데 사용됩니다.

이 강력한 인증 메커니즘은 악의적인 입력이 에이전트의 의도된 동작을 우회하거나 조작하려는 공격 유형인 프롬프트 인젝션으로부터 에이전트 애플리케이션을 보호하는 데 탁월한 솔루션을 제공합니다. 자세한 내용은 위키백과의 프롬프트 인젝션 문서를 참고하세요.

이 애플리케이션에서는 사용자가 '주문 상태 확인' 또는 '쇼핑 목록 표시'를 요청할 때 이 기법이 활용됩니다. 에이전트는 인증된 사용자의 주문만 표시하도록 설계되어 주문 정보에 대한 무단 액세스를 방지합니다.

벡터 검색

에이전트 애플리케이션은 PostgreSQL용 AlloyDB를 활용하여 특히 벡터 검색을 통해 고급 쿼리 기능을 제공합니다. AlloyDB는 SQL 함수를 사용하여 데이터베이스 내에서 직접 온라인 임베딩 생성을 지원합니다.

이 강력한 기능을 사용하면 에이전트가 사용자의 자연어 입력을 숫자 임베딩 표현으로 변환할 수 있습니다. 그런 다음 이러한 임베딩을 기반으로 제품 카탈로그 (또는 기타 관련 데이터)에 대해 유사성 검색을 실행하여 관련성이 높은 검색 결과를 제공할 수 있습니다.

애플리케이션에서 '울트라 트레일용 러닝화를 찾고 있어'라고 Finn에게 물으면 이 기법을 경험할 수 있습니다.

지리 공간 기능 (PostGis)

PostgreSQL용 AlloyDB는 표준 PostgreSQL 기능과 100% 호환됩니다. 이 애플리케이션에서는 널리 사용되는 PostgreSQL 확장 프로그램 PostGIS를 활용하여 에이전트에게 지리 공간적 위치 기능을 제공합니다.

사용자가 에이전트에게 '가까운 매장 찾아줘'라고 요청하면 에이전트는 데이터베이스 내에서 PostGIS 색인을 활용하는 도구를 실행하여 사용자가 지정하거나 추론한 위치와 가장 가까운 매장을 효율적으로 찾습니다.

11. (선택사항) AlloyDB AI 자연어-SQL 테스트

이 섹션에서는 PostgreSQL용 AlloyDB의 고급 GA 전 기능인 자연어에서 SQL로를 소개합니다. 이 기능을 사용하면 데이터베이스 내에서 AI의 기능을 활용하여 자연어 프롬프트에서 직접 SQL 쿼리를 생성할 수 있습니다.

중요: GA 전 기능이므로 가입하고 Google Cloud 프로젝트, AlloyDB 클러스터, 데이터베이스에 대한 액세스를 사용 설정해야 합니다.

액세스 신청: 이 양식에 따라 프로젝트 액세스를 요청하세요.
문서: 공식 문서에서 AlloyDB AI 자연어-SQL 활용에 대해 자세히 알아볼 수 있습니다.

프로젝트에 가입하고 액세스 권한을 확인한 후 AlloyDB Studio에서 다음 단계를 진행합니다.

클러스터를 만들 때 만든 사용자 인증 정보를 사용하여 AlloyDB에 로그인합니다.

사용자 이름: 'postgres'
데이터베이스: 'store'
비밀번호: 'alloydb'

1. alloydb_ai_nl 확장 프로그램을 만듭니다. 이 확장 프로그램은 AlloyDB AI 자연어 기능에 필요한 함수를 제공합니다.

CREATE EXTENSION alloydb_ai_nl cascade;

2. 애플리케이션의 구성을 만듭니다. 구성에서는 AI 모델이 데이터베이스를 이해하는 데 사용할 스키마 컨텍스트를 정의합니다.

SELECT
 alloydb_ai_nl.g_create_configuration(
   'finn_app_config'        -- configuration_id
 );

3. 구성으로 스키마 / 테이블을 등록합니다. 애플리케이션의 에이전트가 상호작용할 특정 테이블과 스키마를 구성에 추가합니다.

SELECT alloydb_ai_nl.g_manage_configuration(
   operation => 'register_table_view',
   configuration_id_in => 'finn_app_config',
   table_views_in=>'{public.products, public.products_variants, public.orders, public.orders_items, public.users, public.inventory, public.stores}'
);

4. 스키마 / 테이블의 컨텍스트를 생성합니다. 이 단계에서는 등록된 테이블을 처리하여 AI 모델에 필요한 컨텍스트를 생성합니다. 이 과정은 약 2~3분 정도 걸릴 수 있습니다.

SELECT alloydb_ai_nl.generate_schema_context(
 'finn_app_config',
 TRUE
);

5. 특정 표와 열에 대해 자동 생성된 컨텍스트를 확인합니다 (선택사항). 생성된 컨텍스트를 검사하여 AI 모델이 스키마를 해석하는 방식을 파악할 수 있습니다.

SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.inventory';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.name';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.popularity_score';

에이전트의 'tools.yaml'에서 'check-inventory-by-store-brand-category'라는 도구를 확인할 수 있습니다. 이 도구는 AlloyDB 자연어-SQL을 사용합니다.

웹브라우저를 열고 서비스 URL을 사용하여 애플리케이션을 엽니다('https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app').

그런 다음 채팅 인터페이스에서 다음 스크립트를 사용하여 이 새로운 기능을 테스트합니다.

핀, 안녕!
'Sports Diagonal Mar' 매장에 재고가 있는 Salomon의 'Running' 카테고리 제품의 총 수량은 얼마인가요?

AlloyDB AI가 자연어 입력에서 생성한 실제 SQL 쿼리를 확인하려면 AlloyDB Studio로 돌아가 다음 쿼리를 실행하세요.

SELECT
   alloydb_ai_nl.get_sql(
       'finn_app_config',
       'What is the total quantity of category Running products of Salomon in stock at the "Sports Diagonal Mar" store?'
   ) ->> 'sql';

그러면 AlloyDB AI에서 생성된 SQL 문이 표시됩니다.

12. 삭제

이 실습에서 사용한 리소스의 비용이 Google Cloud 계정에 청구되지 않도록 하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 리소스 관리 페이지로 이동합니다.
프로젝트 목록에서 삭제할 프로젝트를 선택하고 '삭제'를 클릭합니다.
대화상자에서 프로젝트 ID를 입력한 후 종료를 클릭하여 프로젝트를 삭제합니다.

13. 축하합니다

축하합니다. ADK, 데이터베이스용 MCP 도구 상자, PostgreSQL용 AlloyDB를 사용하여 데이터 기반 에이전트 AI 애플리케이션을 만들었습니다.

자세한 내용은 제품 문서(에이전트 개발 키트, 데이터베이스용 MCP 도구 상자, PostgreSQL용 AlloyDB)를 참고하세요.