배포 가이드

ADK로 개발한 에이전트를 Agent Engine에 배포하는 방법

Agent Engine은 GCP에 에이전트를 배포하기 위한 완전 관리형 서비스입니다. ADK로 빌드된 에이전트를 Agent Engine에 배포하는 방법을 다룹니다.

1. 사전 준비

필수 요구사항

Google Cloud 프로젝트 생성 및 결제 활성화
Vertex AI API 활성화
Python 3.9 이상 설치
Google Cloud CLI 설치 및 인증

API 활성화

# 필수 API 활성화
gcloud services enable aiplatform.googleapis.com
gcloud services enable cloudresourcemanager.googleapis.com
gcloud services enable cloudbuild.googleapis.com

Python 패키지 설치

pip install google-cloud-aiplatform
pip install google-adk

GCS 버킷 생성

에이전트 배포 시 스테이징용 GCS 버킷이 필요합니다.

gsutil mb -l us-central1 gs://YOUR_PROJECT_ID-agent-staging

2. 에이전트 정의

기본 에이전트 구조

# adk/agent.py
from google.adk.agents import Agent
from google.adk.tools import FunctionTool

# 도구 정의
def list_dataset_ids(project_id: str) -> list:
    """BigQuery 프로젝트의 모든 데이터셋 ID를 조회합니다."""
    from google.cloud import bigquery
    client = bigquery.Client(project=project_id)
    datasets = list(client.list_datasets())
    return [dataset.dataset_id for dataset in datasets]

def execute_sql(query: str) -> dict:
    """BigQuery에서 SQL 쿼리를 실행합니다."""
    from google.cloud import bigquery
    client = bigquery.Client()
    query_job = client.query(query)
    results = query_job.result()
    return [dict(row) for row in results]

# 도구 등록
list_datasets_tool = FunctionTool(list_dataset_ids)
execute_sql_tool = FunctionTool(execute_sql)

# 에이전트 정의
root_agent = Agent(
    name="bigquery-nl2sql-agent",
    model="gemini-2.0-flash",
    instruction="""
    당신은 BigQuery 데이터 분석 전문가입니다.
    자연어를 SQL로 변환하고 데이터를 시각화하는 에이전트입니다.
    """,
    tools=[list_datasets_tool, execute_sql_tool]
)

requirements.txt

google-cloud-aiplatform>=1.38.0
google-adk>=0.1.0
google-cloud-bigquery>=3.0.0

3. 에이전트 배포

기본 배포 코드

import vertexai
from adk.agent import root_agent
import os

# 환경 변수 설정
PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT", "your-project-id")
LOCATION = os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1")
STAGING_BUCKET = f"gs://{os.getenv('GOOGLE_CLOUD_STORAGE_BUCKET', 'your-staging-bucket')}"

# Vertex AI 클라이언트 초기화
client = vertexai.Client(
    project=PROJECT_ID,
    location=LOCATION,
)

# 에이전트 배포
remote_app = client.agent_engines.create(
    agent=root_agent,
    config={
        "display_name": "bigquery-nl2sql-agent",
        "staging_bucket": STAGING_BUCKET,
        "requirements": open("requirements.txt").readlines(),
        "extra_packages": ["./adk"],
        "env_vars": {
            "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
            "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "true"
        }
    }
)

print(f"배포 완료: {remote_app.api_resource.name}")

배포 설정 옵션

옵션	설명	필수
`display_name`	에이전트 표시 이름	O
`staging_bucket`	스테이징용 GCS 버킷	O
`requirements`	Python 패키지 의존성	O
`extra_packages`	추가 패키지 경로	X
`env_vars`	환경 변수	X

환경 변수 설명

환경 변수	설명
`GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY`	텔레메트리 활성화 (true/false)
`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`	메시지 내용 캡처 활성화

배포 완료 확인

배포가 완료되면 다음과 같은 출력이 표시됩니다:

배포 완료: projects/123456789/locations/us-central1/reasoningEngines/9876543210

4. 배포된 에이전트 테스트

기본 테스트

import vertexai
from vertexai import agent_engines

# 배포 시 출력된 ID
REASONING_ENGINE_ID = "projects/xxx/locations/us-central1/reasoningEngines/xxx"

vertexai.init(project="your-project-id", location="us-central1")

# 배포된 에이전트 가져오기
remote_agent = agent_engines.get(REASONING_ENGINE_ID)

# 테스트 실행
response = remote_agent.stream_query(
    user_id="test_user",
    message="BigQuery 데이터셋 목록을 보여줘"
)

for event in response:
    if event.get("content"):
        print(event["content"])

세션 기반 테스트

# 새 세션 생성
session = remote_agent.create_session(
    user_id="test_user",
    display_name="테스트 세션"
)

# 첫 번째 질문
response1 = remote_agent.stream_query(
    session_id=session.id,
    message="sales 데이터셋의 테이블 목록을 보여줘"
)

# 두 번째 질문 (이전 맥락 유지)
response2 = remote_agent.stream_query(
    session_id=session.id,
    message="그 중에서 orders 테이블의 스키마를 알려줘"
)

5. 에이전트 관리

배포된 에이전트 목록 조회

gcloud ai reasoning-engines list --region=us-central1

특정 에이전트 상세 조회

gcloud ai reasoning-engines describe REASONING_ENGINE_ID --region=us-central1

에이전트 삭제

# Python SDK
client.agent_engines.delete(REASONING_ENGINE_ID)

# gcloud CLI
gcloud ai reasoning-engines delete REASONING_ENGINE_ID --region=us-central1

6. 배포 모범 사례

환경 분리

# 개발 환경
DEV_CONFIG = {
    "display_name": "my-agent-dev",
    "staging_bucket": "gs://my-project-dev-staging",
}

# 프로덕션 환경
PROD_CONFIG = {
    "display_name": "my-agent-prod",
    "staging_bucket": "gs://my-project-prod-staging",
}

텔레메트리 설정

프로덕션 환경에서는 반드시 텔레메트리를 활성화하여 모니터링합니다.

config = {
    ...
    "env_vars": {
        "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
        "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "true"
    }
}

7. 트러블슈팅

일반적인 오류

오류	원인	해결 방법
`Permission denied`	IAM 권한 부족	Vertex AI User 역할 부여
`Bucket not found`	스테이징 버킷 없음	GCS 버킷 생성
`Invalid package`	requirements.txt 오류	패키지 버전 확인
`Timeout`	배포 시간 초과	네트워크 확인 후 재시도

로그 확인

# Cloud Logging에서 에이전트 로그 확인
gcloud logging read "resource.type=aiplatform.googleapis.com/ReasoningEngine" \
    --project=YOUR_PROJECT_ID \
    --limit=50

Agent Engine Workbook