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

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

이 예시에서는 공개적으로 사용 가능한 샘플 코드를 사용합니다. 이 튜토리얼의 샘플 코드에는 다음과 같은 폴더 구조가 있습니다.

시작하기 전에

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

• 검색 엔진 관리자 역할

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

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

  git clone https://github.com/a2ui-project/a2ui.git
  cd a2ui/samples/community/agent/adk/gemini_enterprise/v0_9
  

API 사용 설정

프로젝트에 대해 다음 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 PROJECT_ID a2ui-demo-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": "a2ui-demo-agent",
  "displayName": "A2UI v0.9 Demo Agent",
  "description": "A demo agent that showcases A2UI v0.9 UI templates.",
  "a2aAgentDefinition": {
      "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"A2UI v0.9 Demo\", \"description\": \"A demo agent that showcases A2UI v0.9 UIs built from the Material component catalog and Gemini Enterprise custom components (Canvas, Iframe). Ask it what can you do? to see the available demos.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"preferredTransport\": \"JSONRPC\", \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.9\", \"description\": \"Ability to render A2UI v0.9\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://www.gstatic.com/vertexaisearch/a2ui/v0_9/gemini_enterprise_composite_catalog.json\"]}}]}, \"skills\": [{\"id\": \"a2ui_demo\", \"name\": \"A2UI v0.9 Component Demo\", \"description\": \"Demonstrates A2UI v0.9 UIs built from the Material catalog and Gemini Enterprise custom components: cards, forms & inputs, tabs, tables, progress indicators, dialogs & menus, the Canvas side panel, and the Iframe (IFrameSrcdoc / IFrameUrl) components.\"}], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
    }
}'

다음을 바꿉니다.

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

에이전트 등록 취소 (선택사항)

에이전트를 등록 취소하려면 다음 curl 명령어를 실행합니다.

curl -X DELETE -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/AGENT_ID

다음을 바꿉니다.

• PROJECT_NUMBER: 프로젝트 번호 Google Cloud .
• LOCATION: 데이터 스토어의 멀티 리전입니다(global, us 또는 eu).
• ENGINE_ID: 에이전트가 등록된 앱의 ID입니다.
• AGENT_ID: 삭제하려는 에이전트의 ID입니다.

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

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

웹 앱 URL 가져오기

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

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

   Gemini Enterprise

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

3. 통합 을 클릭합니다.

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

에이전트 사용

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

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

예를 들어 Show me the recent orders table과 같은 프롬프트를 사용하여 샘플 데이터의 일부인 최근 주문에 대한 정보를 가져올 수 있습니다. 에이전트는 material_table_orders.json에서 주문 정보를 가져오고 다음 예시와 같이 커스텀 UI 구성요소를 사용하여 채팅에 목록을 렌더링합니다.