Cloud Run으로 A2UI 에이전트 호스팅

이 튜토리얼에서는 Google 에이전트 개발 키트 (ADK) 및 A2UI 확장 프로그램으로 빌드된 에이전트 간 (A2A) 에이전트를 Cloud Run에 배포하는 방법을 설명합니다. 배포된 에이전트를 Gemini Enterprise에 등록하는 방법도 알아봅니다.

이 튜토리얼의 샘플 코드에는 다음과 같은 폴더 구조가 있습니다.

튜토리얼 폴더 구조

프로젝트의 폴더 구조는 다음과 같습니다.

파일/디렉터리 설명
examples/0.8/ 예시 구성 또는 데이터가 포함된 디렉터리입니다.
__init__.py 디렉터리를 Python 패키지로 표시합니다.
agent.py 에이전트, 기술, 동작을 정의합니다.
agent_executor.py 실행 흐름과 도구 상호작용을 관리합니다.
contact_data.json 에이전트가 사용하는 샘플 데이터 (예: 모의 연락처)
deploy.sh 에이전트를 빌드하고 Cloud Run에 배포하는 스크립트
main.py 기본 애플리케이션 진입점 (FastAPI 앱)입니다.
prompt_builder.py 모델의 프롬프트를 구성하는 도우미입니다.
pyproject.toml 프로젝트 구성 및 종속 항목
tools.py 에이전트가 사용할 수 있는 도구 (함수)를 정의합니다.

시작하기 전에

시작하기 전에 다음과 같은 항목이 필요합니다.

  • 검색 엔진 관리자 역할

  • 기존 Gemini Enterprise 앱. 앱을 만들려면 앱 만들기를 참조하세요.

  • 저장소를 클론하고 cloud_run 샘플 디렉터리로 이동합니다.

    git clone https://github.com/google/A2UI.git
cd A2UI/samples/agent/adk/gemini_enterprise/cloud_run

API 사용 설정

프로젝트에 다음 API를 사용 설정합니다.

콘솔

다음 API를 사용 설정합니다.

  • Agent Platform API
  • Cloud Build API
  • Artifact Registry API
  • Cloud Run API
  • Cloud Logging API
  • Discovery Engine API
  • Cloud Storage API
  • Identity and Access Management(IAM) API

API 사용 설정

REST

Google Cloud 콘솔에서 또는 다음 gcloud CLI 명령어를 사용하여 이러한 API를 사용 설정할 수 있습니다.

gcloud services enable aiplatform.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com run.googleapis.com logging.googleapis.com discoveryengine.googleapis.com storage.googleapis.com iam.googleapis.com

권한 부여

Cloud Run 호출자 (roles/run.invoker) 역할에 권한을 부여합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
   --role="roles/run.invoker"

다음을 바꿉니다.

  • PROJECT_ID : 프로젝트의 ID
  • PROJECT_NUMBER: Google Cloud 프로젝트 번호.

에이전트 배포

deploy.sh 스크립트는 배포 프로세스를 자동화합니다. 에이전트를 배포하려면 프로젝트 디렉터리에서 Google Cloud ID와 새 서비스의 이름을 사용하여 스크립트를 실행합니다. 사용할 Gemini 모델을 선택적으로 지정할 수도 있습니다.

스크립트는 다음 작업을 실행합니다.

  1. 소스 코드에서 컨테이너 이미지를 빌드합니다.
  2. 이미지를 Artifact Registry로 푸시합니다.
  3. Cloud Run에 이미지를 배포합니다.
  4. MODEL 및 서비스 자체의 공개 AGENT_URL를 비롯한 환경 변수를 설정합니다.
chmod +x deploy.sh
./deploy.sh YOUR_PROJECT_ID contacts-agent MODEL_NAME

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트의 ID입니다.
  • MODEL_NAME: 선택사항. 스크립트의 세 번째 인수입니다. 지원되는 값은 gemini-2.5-pro 및 gemini-2.5-flash입니다. 제공되지 않으면 스크립트의 기본값은 gemini-2.5-flash입니다.

스크립트가 완료되면 배포된 에이전트의 서비스 URL이 출력됩니다. 다음 단계에서 이 서비스 URL이 필요합니다.

Gemini Enterprise에 에이전트 등록

이제 에이전트가 배포되었으므로 Gemini Enterprise에 등록하여 검색 가능하도록 해야 합니다.

다음 curl 명령어를 실행하고 자리표시자를 자신의 값으로 바꿉니다.

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents -d '{
"name": "contacts-agent",
"displayName": "Contacts Agent",
"description": "This is a test agent which lists the contacts.",
"a2aAgentDefinition": {
  "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"contacts-agent\", \"description\": \"This is a test agent which lists the contacts.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.8\", \"description\": \"Ability to render A2UI\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://a2ui.org/specification/v0_8/standard_catalog_definition.json\"]}}]}, \"skills\": [], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
}
}'

다음을 바꿉니다.

  • PROJECT_NUMBER: Google Cloud 프로젝트 번호.
  • LOCATION: 데이터 스토어의 멀티 리전입니다(global, us 또는 eu).
  • ENGINE_ID: 에이전트를 등록할 앱의 ID입니다.
  • AGENT_URL: 배포된 에이전트의 서비스 URL입니다.

Gemini Enterprise 웹 앱에서 에이전트 사용하기

에이전트를 만들고 등록한 후 Gemini Enterprise 웹 앱에서 에이전트를 사용하고 상호작용할 수 있습니다.

웹 앱 URL 가져오기

에이전트를 사용하려면 먼저 웹 앱 URL을 가져와야 합니다. Gemini Enterprise 관리자는 다음 단계에 따라 웹 앱 URL을 가져와 공유할 수 있습니다.

  1. Google Cloud 콘솔에서 Gemini Enterprise 페이지로 이동합니다.

    Gemini Enterprise

  2. 에이전트를 등록한 앱의 이름을 클릭합니다.

  3. 통합을 클릭합니다.

  4. 웹 앱 링크:를 복사하여 조직의 사용자와 공유합니다.

에이전트 사용

에이전트를 사용하고 상호작용하려면 다음 단계를 따르세요.

  1. 새 브라우저 탭에서 웹 앱 URL을 엽니다.
  2. 웹 앱 탐색 메뉴에서 상담사를 클릭합니다.
  3. 조직에서 섹션으로 이동하여 생성한 에이전트를 클릭합니다.
  4. 그러면 에이전트의 대화형 인터페이스가 열립니다. 질문을 하고 에이전트와 상호작용합니다.

예를 들어 에이전트에게 모든 연락처를 나열해 달라고 요청할 수 있습니다. 에이전트는 list_contacts 도구를 사용하여 contact_data.json에서 연락처를 가져오고 다음 예와 같이 맞춤 UI 요소를 사용하여 채팅에 목록을 렌더링합니다.

Contacts Agent Example(연락처 에이전트 예)