Agents CLI를 사용하여 Agent Runtime에 ADK 에이전트 배포

1. 개요

이 실습은 Kaggle의 5일간의 AI 에이전트: Google의 집중 바이브 코딩 과정 의 일부입니다. 이벤트 사이트에서 제공되는 추가 Codelab 및 리소스를 확인할 수 있습니다.

이 Codelab에서는 ADK 2.0 에이전트 를 로컬 개발 환경에서 프로덕션 등급 배포로 전환합니다. agents-cli를 사용하여 Google Cloud의 Agent Runtime에서 그래프 기반 워크플로를 패키징, 확인, 호스팅합니다.

이 배포 프로세스를 살펴보려면 클라우드에 배포하기 전에 Ambient Expense Agent 의 로컬 프로토타입을 처음부터 빌드합니다. (이 에이전트의 핵심 로직 설계에 관한 자세한 내용은 Kaggle 이벤트 사이트의 기본 Codelab을 참고하세요.) Ambient Expense Agent는 표준 청구를 즉시 승인하는 동시에 더 큰 비용에 인간 참여형 검토를 위한 플래그를 지정하여 직원 비용 보고를 간소화합니다. 내부적으로 ADK 2.0 그래프 기반 워크플로 를 사용하여 이러한 자동 승인 및 위험 분석 단계를 조정합니다.

학습할 내용

• 클라우드 호스팅을 위해 로컬 Ambient Expense Agent 프로젝트를 준비하는 방법
• 필요한 배포 설명자와 프로덕션 래퍼를 스캐폴딩하는 방법
• 드라이 런을 실행하고 코드를 Agent Runtime 에 직접 배포하는 방법
• Cloud Trace를 사용하여 프로덕션 에이전트의 실행 trace를 모니터링하는 방법

필요한 항목

• 결제가 사용 설정된 활성 Google Cloud 프로젝트
• gcloud SDK가 설치되고 인증됨
• uv 패키지 관리자가 설치됨
• Google Antigravity IDE가 설치됨

기본 요건

이 Codelab에서는 다음 사항에 익숙하다고 가정합니다.

• 터미널을 사용하여 시스템 탐색
• 기본 Python 개발 개념
• 기본적인 Google Cloud 개념

2. Google Cloud 환경 설정

배포하기 전에 Google Cloud 프로젝트를 구성하고 필요한 API를 사용 설정해야 합니다.

👉 Antigravity 프롬프트:

Help me set up my Google Cloud environment. Connect to my project
`YOUR_PROJECT_ID` in the global region, authenticate, and enable the necessary
generative platform APIs (aiplatform.googleapis.com, cloudtrace.googleapis.com,
cloudbuild.googleapis.com, agentregistry.googleapis.com).

Antigravity가 이 프롬프트를 실행하면 프로젝트를 구성하고 서비스를 사용 설정하는 데 필요한 gcloud 터미널 명령어를 제안하고 실행합니다. 인증 단계에서 Antigravity는 터미널에 승인 URL을 표시합니다. 링크를 클릭하여 웹브라우저를 통해 로그인하고 액세스 권한을 부여합니다. 브라우저 로그인을 완료하면 Antigravity가 실행을 재개하여 프로젝트 환경 변수를 설정하고 필요한 API를 사용 설정합니다.

참고: 새 프로젝트인 경우 gcloud에서 먼저 Service Usage API를 사용 설정하라는 메시지를 표시할 수 있습니다. 요청이 있는 경우 터미널에 제공된 링크를 따라 Cloud 콘솔에서 사용 설정합니다.

3. Agents CLI 및 ADK 기술 설정

Antigravity가 ADK 에이전트를 잘 빌드하고 배포하려면 ADK 기술 세트 가 필요합니다. 이는 ADK API, 프로젝트 스캐폴딩, agents-cli 배포 워크플로, 평가를 위한 번들 참조입니다. agents-cli 도구 모음을 설치하면 이러한 스킬이 코딩 에이전트에도 설치되어 로컬 스캐폴딩에서 클라우드 배포에 이르기까지 에이전트의 전체 수명 주기를 관리할 수 있습니다.

👉 다음 프롬프트를 복사하여 Antigravity에 붙여넣습니다.

Install the agents-cli toolchain and its ADK skills so you can help me build
an ADK agent. Run "uvx google-agents-cli setup", then confirm with
"agents-cli info" and tell me which skills are now available.

Antigravity가 이 프롬프트를 실행하면 터미널에서 uvx google-agents-cli setup을 실행하여 CLI 및 관련 기술을 설치합니다. 그런 다음 agents-cli info를 실행하여 설치를 확인하고 새로 설치된 도메인 기술 (예: google-agents-cli-deploy 및 google-agents-cli-workflow)을 채팅에 직접 나열합니다.

Antigravity 사용자 참고사항: 이 Codelab 중에 Antigravity는 명령어를 실행하거나 코드를 작성하기 전에 구현 계획을 생성하거나 팝업을 표시할 수 있습니다. Antigravity가 작업을 진행할 수 있도록 이러한 계획 또는 팝업을 검토하고 승인 해야 합니다.

할당량 도움말: 테스트 또는 개발 중에 할당량이 부족하면 Antigravity에서 모델을 사용 가능한 다른 모델로 전환합니다.

4. 에이전트 프로젝트 만들기

클라우드 환경이 구성되고 CLI 기술이 설치되면 에이전트의 로컬 코드베이스를 생성할 수 있습니다. 이 단계에서는 Antigravity를 사용하여 ADK 2.0과 호환되는 완전한 기능을 갖춘 Ambient Expense Agent 프로토타입을 스캐폴딩합니다.

Kaggle 5일간의 AI 에이전트 사용자 참고사항: 4일차에 이 Vibecode Ambient Expense Agent Codelab을 완료하고 기존 커스텀 에이전트 코드베이스를 배포하려는 경우 이 스캐폴딩 단계를 건너뛰고 다음 단계로 이동할 수 있습니다.

👉 Antigravity 프롬프트:

Use Agents CLI to build a local prototype for an ambient expense agent that
streamlines employee expense reporting by instantly approving standard claims
while flagging larger expenses for review. Ensure the graph workflow is
compatible with ADK 2.0 and includes an `auto_approve` node that automatically
approves expenses under $100, and a `review_agent` node that triggers a
human-in-the-loop pause (`RequestInput`) for expenses of $100 or more.

Antigravity가 이 프롬프트를 실행하면 새로 설치된 스캐폴딩 기술을 활용하여 터미널에서 agents-cli scaffold create expense-agent --adk를 실행합니다. 그런 다음 생성된 프로토타입 코드를 확인하고 조정하여 expense-agent가 $100 자동 승인 기준점과 인간 참여형 검토 흐름을 에이전트 개발 키트 (ADK) 그래프 워크플로 내에서 올바르게 구현하도록 합니다.

5. 프로덕션 배포 준비

Agent Runtime은 프로덕션에서 AI 에이전트를 배포, 관리, 확장할 수 있는 완전 관리형 Google Cloud 서비스입니다. Agent Runtime은 호스팅의 운영 복잡성을 처리하며 세션 관리, 장기 메모리, 보안 코드 실행 샌드박스와 같은 기능을 갖춘 스테이트풀(Stateful) 환경을 제공합니다.

Agent Runtime에 배포하는 이유는 무엇인가요?

Antigravity를 사용하여 로컬에서 에이전트를 빌드하면 에이전트가 localhost에 대해 로컬 머신에서 실행됩니다. 빠른 프로토타입 제작에 적합하지만 로컬 에이전트는 노트북을 닫는 순간 실행을 중지합니다.

에이전트를 Agent Runtime에 배포하면 워크플로가 완전 관리형의 항상 사용 가능한 Google Cloud 환경으로 이동합니다. 이렇게 하면 연중무휴 24시간 활성 상태로 유지되는 안전한 실시간 백엔드 엔드포인트가 설정됩니다. 다음 Codelab에서는 이 클라우드 엔드포인트에 직접 연결되는 웹 프런트엔드를 빌드하여 에이전트에 공개 URL을 제공합니다.

또한 Agent Runtime은 AI 에이전트에 맞게 특별히 최적화된 전용 인프라를 제공하며 다음과 같은 기본 제공 기능을 제공합니다.

• 관리형 스테이트풀(Stateful) 실행: 대화 턴 전반에 걸쳐 기본 제공 세션 관리 및 장기 메모리 지속성
• 보안 샌드박싱: 격리된 환경에서 동적 도구 호출 및 에이전트 생성 코드를 안전하게 실행
• 엔터프라이즈 모니터링 가능성: Cloud Trace 및 Cloud Logging으로 직접 전송되는 기본 제공 원격 분석 스트리밍

Agent Runtime에서 에이전트를 호스팅하려면 프로덕션 설명자, 스키마, 엔드포인트 래퍼를 사용하여 로컬 프로젝트 디렉터리를 개선해야 합니다.

👉 Antigravity 프롬프트:

Scaffold the production deployment files for Agent Runtime.

Antigravity가 이 프롬프트를 실행하면 프로젝트 루트에서 agents-cli scaffold enhance --deployment-target agent_runtime --yes를 실행합니다. 이 명령어는 디렉터리를 스캔하고 다음을 자동으로 생성합니다.

• app/agent_runtime_app.py: 프로덕션 등급 서비스 래퍼
• deployment_metadata.json: Agent Runtime에서 리소스를 가동하는 데 사용하는 레이아웃 스키마

app/agent.py의 핵심 에이전트 로직은 완전히 그대로 유지됩니다.

6. 패키징 및 로컬 확인

클라우드 업로드를 시작하기 전에 패키지를 잠그고 로컬 드라이 런을 실행하여 잠재적인 종속성 충돌을 식별합니다.

👉 Antigravity 프롬프트:

Lock my python dependencies and run a dry-run deployment to check for any
configuration or dependency issues.

Antigravity가 이 프롬프트를 실행하면 먼저 터미널에서 uv lock을 실행하여 결정적 잠금 파일을 생성하고 클라우드에서 일관된 라이브러리 버전을 보장합니다. 그런 다음 agents-cli deploy --dry-run을 실행하여 구성 유효성을 확인하고 클라우드 리소스를 프로비저닝하지 않고 배포 단계를 미리 봅니다. 터미널에서 드라이 런 출력을 검토하여 모든 파일과 설정이 올바른지 확인할 수 있습니다.

7. Agent Runtime에 배포

Ambient Expense Agent를 Agent Runtime에 배포합니다.

👉 Antigravity 프롬프트:

Deploy this agent to Agent Runtime.

Antigravity가 이 프롬프트를 실행하면 google-agents-cli-deploy 스킬을 활성화하고 agents-cli deploy --project YOUR_PROJECT_ID --region us-west1을 실행합니다. 패키징, 업로드, Agent Runtime 프로비저닝 프로세스는 일반적으로 5~10분 정도 걸립니다. Antigravity는 터미널에서 배포 진행 상황을 모니터링하고 완료되면 실시간 엔드포인트 URL을 표시합니다.

💡 전문가 팁 (제한 시간 창 관리): 긴 배포 중에 터미널을 잠그지 않으려면 Antigravity에 --no-wait 플래그를 사용하여 배포를 비동기식으로 시작하고 나중에 agents-cli deploy --status를 사용하여 진행 상황을 확인하도록 지시할 수 있습니다.

에이전트 배포에 문제가 있는 경우 다른 리전을 사용하는 것이 좋습니다. Google Cloud 리전 선택 도구를 사용하면 지연 시간, 가격, 탄소 발자국을 기준으로 프로젝트에 가장 적합한 리전을 결정할 수 있습니다.

8. 에이전트 테스트

에이전트가 배포되면 소액 비용을 자동으로 승인하고 더 큰 비용에 인간 참여형 확인을 위한 플래그를 올바르게 지정하는지 확인할 수 있습니다.

👉 Antigravity에 실시간 배포된 엔진을 확인하도록 프롬프트합니다.

Test my deployed Agent Runtime engine with two test cases: first a standard
meal expense of $50 to verify automatic approval, and second, a client dinner
expense of $150 to verify that the human-in-the-loop pause is triggered.

참고: Antigravity가 실시간 엔드포인트에 대해 이 테스트 프롬프트를 실행할 때 배포 또는 실행 오류가 발생하면 문제를 자동으로 디버그하고 필요한 코드 수정사항을 적용하며 에이전트를 다시 배포합니다.

또는 Cloud 콘솔 Playground 미리보기를 사용하여 에이전트를 수동으로 테스트할 수 있습니다. Playground를 열려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 탐색 메뉴를 사용하여 Agent Platform > 배포 를 선택합니다.
2. 배포 목록에서 배포된 에이전트를 선택합니다.
3. Playground 버튼을 클릭하여 대화형 테스트 채팅 인터페이스를 엽니다.

👉 자동 승인(<100달러)을 테스트하려면 다음 JSON 페이로드를 채팅창에 붙여넣습니다.

{"data": {"amount": 50.0, "submitter": "[e-mail]", "category": "meals", "description": "Lunch", "date": "2026-06-04"}}

상태가 '승인됨'인 auto_approve 노드의 출력을 보여주는 JSON 응답이 표시됩니다.

👉 인간 참여형 (HITL) 흐름을 테스트하려면 다음 JSON 페이로드를 붙여넣습니다.

{"data": {"amount": 150.0, "submitter": "[e-mail]", "category": "meals", "description": "Client dinner", "date": "2026-06-04"}}

이렇게 하면 review_agent가 트리거되고 경고 알림이 발생한 후 실행이 일시중지되어 승인을 요청하는 RequestInput (인간 참여형)이 생성됩니다.

9. 프로덕션 에이전트 모니터링 및 관찰

Agent Runtime을 사용하면 원격 분석이 자동으로 연결됩니다. 모든 상호작용, 모델 호출, 도구 실행은 실시간 로그와 스팬을 프로젝트로 스트리밍합니다.

1. trace 검사: Cloud Trace 콘솔을 열어 실시간 트랜잭션 맵, 모델 지연 시간, 도구 실행 단계를 감사합니다.
2. 감사 로그: Cloud Logging을 사용하여 실시간 표준 출력 및 진단 스택 trace를 검사합니다.

3. 집계 분석: 스캐폴딩 중에 --bq-analytics 플래그가 사용 설정된 경우 SQL을 사용하여 BigQuery 내에서 로그를 쿼리하여 승인 비율과 대화 턴 추세를 확인합니다.

다음 SQL 쿼리는 승인 비율을 계산하는 예를 제공합니다. Antigravity에 특정 프로젝트 및 BigQuery 데이터 세트에 맞게 이 쿼리를 맞춤설정하도록 프롬프트할 수 있습니다.

SELECT
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')) AS approved_count,
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)rejected')) AS rejected_count,
  COUNT(1) AS total_processed,
  SAFE_DIVIDE(COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')), COUNT(1)) AS approval_ratio
FROM
  `[YOUR_PROJECT_ID].[YOUR_DATASET_ID].v_agent_response`
WHERE
  agent = 'expense_processor';

10. (선택사항) 에이전트 레지스트리에서 등록 확인

조직의 다른 서비스, 개발자 또는 에이전트가 비용 에이전트를 안전하게 검색하고 사용할 수 있도록 하려면 엔터프라이즈 에이전트 레지스트리 (Gemini Enterprise)에 등록해야 합니다.

에이전트를 Agent Runtime에 배포했으므로 에이전트 레지스트리에 자동으로 등록됩니다. Agent Runtime에서 에이전트를 업데이트하거나 삭제하는 경우에도 에이전트 레지스트리에 자동으로 동기화됩니다.

👉 Antigravity에 에이전트의 자동 등록을 확인하도록 프롬프트합니다.

Verify that my deployed expense agent is automatically registered in the Gemini
Enterprise Agent Registry.

Antigravity가 이 프롬프트를 실행하면 터미널에서 agents-cli publish gemini-enterprise --list를 실행합니다. 이렇게 하면 에이전트 레지스트리를 쿼리하고 프로젝트에 등록된 모든 Gemini Enterprise 에이전트를 나열하여 Ambient Expense Agent가 조직 전체에서 활성 상태이고 검색 가능한지 확인할 수 있습니다.

11. 정리

Kaggle 과정 참여자: Kaggle의 5일간의 AI 에이전트 과정의 일부로 이 실습을 완료하고 프런트엔드 클라이언트 및 Pub/Sub 통합을 빌드하기 위해 다음 실습 (ADK 에이전트의 프런트엔드 바이브코딩 및 배포)을 계속 진행할 계획이라면 배포된 에이전트를 삭제하지 마세요. 다음 실습에는 이 활성 클라우드 인프라가 필요합니다.

Google Cloud 계정에 지속적으로 요금이 청구되지 않도록 하려면 완료한 후 배포된 리소스를 종료하고 정리해야 합니다.

👉 Antigravity 프롬프트:

Clean up all my deployed cloud resources. Use the Agent Runtime ID from
deployment_metadata.json to delete the engine from Vertex AI, remove the local
deployment_metadata.json file, and delete the container image repository from
Artifact Registry.

Antigravity가 이 프롬프트를 실행하면 전체 리소스 삭제 프로세스가 자동화됩니다.

1. 배포된 에이전트 삭제: deployment_metadata.json을 읽어 원격 Agent Runtime ID를 가져온 다음 프로그래매틱 방식으로 Vertex AI에서 실시간 엔진 인스턴스를 삭제합니다.
2. 로컬 작업공간 삭제: 프로젝트 루트에서 오래된 deployment_metadata.json 파일을 삭제합니다.
3. Artifact Registry 정리: 클라우드 스토리지 공간을 확보하기 위해 Artifact Registry에서 빌드된 컨테이너 이미지를 정리하는 gcloud artifacts docker images delete를 실행합니다.

12. 축하합니다

축하합니다. Google Cloud에서 프로덕션 등급 Ambient Expense Agent를 배포하고 확인했습니다.

학습한 내용

• Google Cloud 설정: 프로젝트 사용자 인증 정보를 구성하고 필요한 플랫폼 API를 사용 설정했습니다.
• 도구 및 기술: agents-cli를 설치하고 ADK 관련 기술을 Antigravity에 로드했습니다.
• 프로덕션 스캐폴딩: ADK 2.0 에이전트의 Agent Runtime 스캐폴딩을 생성했습니다.
• 로컬 확인: 결정적 잠금 파일 (uv lock)을 만들고 드라이 런 검사를 실행했습니다.
• 클라우드 배포: 관리형 Agent Runtime 인프라에서 에이전트를 실시간으로 호스팅했습니다.
• 모니터링 가능성 및 분석: Cloud Trace에서 실행을 추적하고 BigQuery에서 원격 분석을 분석했습니다.
• 엔터프라이즈 검색: 엔터프라이즈 에이전트 레지스트리에서 자동 등록을 확인했습니다.

다음 단계

• BigQuery 분석 실행: BigQuery에서 에이전트의 원격 분석 로그를 쿼리하여 시간 경과에 따른 승인 비율과 대화 턴 추세를 분석합니다.
• 바이브 투 라이브 Codelab: Google Antigravity를 사용하여 Cloud Run에서 프런트엔드 클라이언트를 개발하고 실시간 Agent Runtime 백엔드 엔드포인트에 직접 연결합니다.

Kaggle 5일간의 AI 에이전트 배지 획득 🎉

Kaggle의 5일간의 AI 에이전트: Google의 집중 바이브 코딩 과정 의 일부로 이 실습을 완료했나요? 완료 배지를 신청하세요.

5일간의 AI 에이전트 배지 받기

참조

• 에이전트 개발 키트 (ADK) 문서
• Gemini Enterprise Agent Platform 런타임
• Agents CLI (agents-cli) 참조 가이드
• Gemini Enterprise Agent Registry 개요
• Google Cloud Trace 문서