Google Cloud Agents CLI 출시 – 에이전트 개발·평가·배포를 한 CLI로 통합

 

Google Cloud Agents CLI Stories

AI News

Google Cloud Agents CLI 공개 – 에이전트 개발부터 프로덕션 배포까지 한 번에

ADK 에이전트의 스캐폴딩, 로컬 평가, 배포, 관측까지 하나의 CLI에서 처리하는 Google의 새 개발자 도구

Google Cloud Agents CLI

 

Google Cloud Agents CLI란? – 에이전트 개발·배포를 한 CLI로

 

Google Cloud Agents CLI는 ADK(Agent Development Kit)로 만든 AI 에이전트의 생성, 평가, 배포, 관측까지 하나의 CLI에서 처리하는 개발자 도구입니다.

2026년 4월 22일, Google Developers Blog가 Agent Platform의 Agents CLI를 공식 소개했습니다. ADK로 에이전트 로직을 작성한 뒤 인프라를 따로 세팅하고, 배포 스크립트를 별도로 관리하던 과정을 `create → eval → deploy → publish` 한 줄 흐름으로 연결한 도구입니다.

제가 보기에 Agents CLI의 실질적인 가치는 '에이전트 수명주기 관리'를 CLI 한 곳에 모았다는 점입니다. Google Cloud 위에서 에이전트 PoC를 운영 환경으로 넘겨야 하는 팀이라면, 여러 서비스에 흩어져 있던 설정 파일 작성을 상당 부분 건너뛸 수 있습니다.

현재 google/agents-cli GitHub 저장소에서 Apache 2.0 라이선스로 공개되어 있고, 5월 6일 기준 v0.1.3까지 나온 초기 단계입니다. 4월 9일 Google Cloud Next '26에서 Gemini Enterprise Agent Platform(기존 Vertex AI 리브랜딩)이 발표된 직후 2주 만에 CLI가 뒤따른 점이 눈에 띕니다. InfoQ는 4월 말 보도에서 개발자가 터미널에서 직접 명령을 실행하는 Human Mode에 대한 긍정적 반응을 전했습니다.

 

 

ADK와 Agents CLI의 관계 – 7개 스킬과 두 가지 운영 모드

 

ADK는 에이전트 로직을 작성하는 Python SDK이고, Agents CLI는 그 에이전트의 수명주기(생성·평가·배포·관측)를 관리하는 명령줄 도구입니다.

처음 접하면 ADK와 Agents CLI의 역할 분담이 헷갈릴 수 있는데, 구분은 단순합니다.

• ADK(Agent Development Kit): 에이전트의 로직, 도구 연결, 멀티 에이전트 구조를 코드로 작성하는 Python 프레임워크
• Agents CLI: ADK로 만든 에이전트를 생성(scaffold)하고, 평가(eval)하고, 배포(deploy)하고, 모니터링(observability)하는 명령줄 도구

ADK로 에이전트의 로직을 짜고, Agents CLI로 그 에이전트를 운영 환경까지 밀어 넣는 구조라고 보면 됩니다. 번들로 포함된 7개 스킬은 아래와 같습니다.

스킬	역할
workflow	전체 파이프라인 오케스트레이션
adk-code	ADK 기반 에이전트 코드 작성 지원
scaffold	프로젝트 생성·구조 설정
eval	로컬 평가 실행·결과 비교
deploy	Agent Runtime / Cloud Run / GKE 배포
publish	Gemini Enterprise 등록
observability	Cloud Trace 기반 실행 추적

여기서 볼 부분은 Agent Mode입니다. Gemini CLI, Claude Code, Cursor 같은 코딩 어시스턴트에 이 7개 스킬이 자동 설치되면, 대화 중에 '에이전트를 Cloud Run에 배포해 줘'라고 요청하는 것만으로 CLI 명령이 순차 실행됩니다. Human Mode는 터미널에서 직접 명령을 입력하는 방식이고, 명령어 체계는 두 모드에서 동일합니다.

 

 

Agents CLI 설치와 사용법 – 첫 에이전트 실행까지

 

`uvx google-agents-cli setup` 한 줄로 CLI와 7개 스킬이 설치됩니다. Python 3.11 이상, uv, Node.js가 사전 요구 사항입니다.

실제로 설치부터 로컬 테스트까지 거치는 단계입니다.

```bash
# 1. CLI 설치 (uv가 설치된 상태에서)
uvx google-agents-cli setup

# 2. 첫 에이전트 프로젝트 생성
agents-cli create my-agent --prototype --yes

# 3. 의존성 설치
cd my-agent && agents-cli install

# 4. 로컬 플레이그라운드 실행 (localhost:8080)
agents-cli playground

# 5. 단일 프롬프트 테스트
agents-cli run '테스트 프롬프트'
```

uv 대신 pip이나 pipx를 쓸 수도 있습니다(`pip install google-agents-cli && agents-cli setup`). 코딩 어시스턴트에 스킬만 따로 넣으려면 `npx skills add google/agents-cli` 명령도 가능합니다.

실제로 확인할 부분은 `pyproject.toml`의 `[tool.agents-cli]` 섹션입니다. `deployment-target`(agent_runtime / cloud_run / gke), `project`, `region` 값을 여기서 설정하는데, 이 파일 하나가 배포 흐름 전체를 결정합니다. Google Cloud 인증은 `gcloud auth application-default login` 또는 `GEMINI_API_KEY` 환경변수로 설정하면 됩니다.

로컬 플레이그라운드와 평가까지는 `GEMINI_API_KEY`만 있어도 진행할 수 있고, 배포 단계부터 Google Cloud SDK와 Terraform이 추가로 필요합니다.

 

배포 대상 비교 – Agent Runtime vs Cloud Run vs GKE

 

Agents CLI는 Agent Runtime(관리형), Cloud Run(서버리스), GKE(Kubernetes) 세 가지 배포 대상을 지원합니다. 팀 규모와 운영 요구에 따라 선택이 달라집니다.

배포 대상	특징	적합한 경우
Agent Runtime	관리형 인프라, 내장 인증·보안, Cloud Trace 자동 연결	엔터프라이즈 운영, 보안 요구가 높은 팀
Cloud Run	서버리스, `gcloud beta run deploy`로 빠른 배포, 종량제	PoC·스타트업, 빠른 검증이 필요한 팀
GKE	Terraform + Docker + kubectl, 커스텀 인프라 제어	기존 Kubernetes 클러스터를 운영하는 팀

> Agent Runtime에 배포하면 Gemini Enterprise Agent Platform의 관리형 인프라, 내장 인증, Cloud Trace 관측성, 엔터프라이즈 보안을 자동으로 상속합니다.

다만 조심할 점이 있습니다. Agent Runtime의 한국 리전(asia-northeast3) 지원 여부는 2026년 5월 기준 공식 문서에서 확인되지 않았습니다. Cloud Run은 서울 리전을 지원하므로, 한국 팀이 PoC를 먼저 시작하려면 Cloud Run 경로가 현실적입니다.

배포 전에 dry run으로 설정을 검증할 수 있습니다:

```bash
agents-cli deploy --dry-run
```

멀티 환경이 필요하면 `agents-cli infra setup-cicd`로 dev/staging/prod CI/CD 파이프라인을 한 번에 구성하고, 단일 프로젝트 인프라는 `agents-cli infra single-project`로 프로비저닝합니다.

 

 

 

에이전트 평가(eval)와 품질 추적

 

`agents-cli eval run`으로 로컬 평가를 실행하고, `eval compare`로 이전 결과와 비교합니다. LLM-as-judge 방식으로 에이전트 품질을 자동 채점합니다.

프롬프트를 수정하거나 모델을 교체할 때마다 에이전트 응답 품질이 유지되는지 확인하는 건 운영에서 빠질 수 없는 과정입니다. Agents CLI에서는 이 과정이 명령어 두 줄로 끝납니다.

```bash
agents-cli eval run
agents-cli eval compare evals/run_v1.json evals/run_v2.json
```

LLM-as-judge는 평가 대상 에이전트의 응답을 별도 LLM이 채점하는 방식입니다. 이 평가를 CI 파이프라인에 연결하면, 에이전트 코드를 수정할 때마다 품질 저하를 자동 감지하는 게이트 역할을 하게 됩니다. 제가 보기에 이 eval compare가 Agents CLI에서 실무적으로 가장 쓸모 있는 기능 중 하나인데, 에이전트를 수동으로 테스트하면 놓치기 쉬운 미묘한 품질 저하를 JSON 비교로 수치화할 수 있기 때문입니다.

코드 품질 검사도 내장되어 있습니다. `agents-cli lint`는 ruff, codespell, mypy를 한 번에 실행하므로, 타입 안전성과 맞춤법까지 한 명령으로 확인됩니다.

 

한국 개발팀 실무 도입 시 확인할 포인트

 

Google Cloud에서 에이전트 PoC를 운영으로 넘기는 단계에 있는 한국 팀이라면, Agents CLI로 인프라 반복 설정을 줄일 수 있는지가 가장 중요한 판단 기준입니다.

한국 팀이 Google Cloud Agents CLI 도입 여부를 판단할 때, 먼저 확인해야 할 것들입니다.

리전과 인프라: Cloud Run은 서울(asia-northeast3) 리전을 지원하지만, Agent Runtime의 서울 리전 가용성은 아직 공식 확인되지 않았습니다. 국내 서비스 레이턴시가 중요하다면 Cloud Run 배포부터 검증하는 게 합리적입니다.

코딩 어시스턴트 통합: Gemini CLI, Claude Code, Cursor를 이미 사용하는 팀이라면 Agent Mode를 통해 에이전트 생성→배포를 대화형으로 처리할 수 있습니다. 별도 명령어를 외우지 않아도 기존 작업 흐름 위에서 바로 쓸 수 있는 구조입니다.

함께 쓰면 효과적인 도구:

• google/adk-python: 에이전트 로직 작성. Agents CLI가 감싸는 핵심 프레임워크
• Gemini CLI: Agent Mode에서 대화형 에이전트 생성·배포
• GoogleCloudPlatform/agent-starter-pack: 프로덕션 수준 에이전트 템플릿(CI/CD, 평가, 관측성 내장)
• Terraform: `agents-cli infra` 명령이 자동 생성하는 IaC 코드의 기반 도구

제가 보기에 이 도구가 가장 도움이 되는 시점은, ADK로 에이전트 PoC를 이미 만들어 놓고 운영 배포로 넘기는 단계입니다. 아직 어떤 에이전트 프레임워크를 쓸지 정하지 않은 상태라면, CLI 도입 판단은 이릅니다.

 

도입 전 확인할 점 – v0.1.x 한계와 건너뛰어야 할 경우

 

Google Cloud Agents CLI는 v0.1.x 초기 단계이고, 아직 모든 팀이 바로 쓸 수 있는 상태는 아닙니다.

v0.1.x 초기 단계: 파괴적 변경(breaking changes)이 발생할 가능성이 있습니다. `agents-cli scaffold upgrade` 명령으로 마이그레이션을 지원하지만, 프로덕션보다는 PoC 수준에서 먼저 써 보는 게 맞습니다.

pre-built wheel 배포: Apache 2.0 라이선스이지만, PyPI에는 바이너리 wheel로 배포됩니다. 전체 소스를 직접 확인하려면 .whl 파일을 추출해야 합니다.

비용 정보 미공개: Google Cloud 비용(Agent Runtime 호스팅, Cloud Run 인스턴스 등)의 구체적 가격이 아직 공개되지 않았습니다. 운영 비용은 테스트 배포를 돌려 보고 직접 가늠해야 합니다.

건너뛰어야 할 경우:

• Google Cloud를 사용하지 않는 팀(AWS/Azure 전용 환경에서는 배포 기능 활용 불가)
• LangChain, CrewAI 등 ADK 외 에이전트 프레임워크를 이미 쓰고 있는 경우
• Python 3.11+ 환경을 구성할 수 없는 레거시 시스템
• 금융·의료 등 규제 산업에서 GA 전 도구 사용이 제한되는 경우
• 단순 LLM API 호출만 필요한 경우(에이전트 수명주기 관리가 오버헤드)

 

자주 묻는 질문

 

Q. Agents CLI와 ADK(Agent Development Kit)는 어떤 관계입니까?
A. ADK는 에이전트의 로직·도구 연결·멀티 에이전트 구조를 Python으로 작성하는 프레임워크이고, Agents CLI는 그 ADK 에이전트의 수명주기(생성·평가·배포·관측)를 관리하는 명령줄 도구입니다. ADK 없이 Agents CLI만으로 에이전트를 만들 수는 없고, ADK 에이전트를 Agents CLI 없이 수동으로 배포하는 것은 가능합니다.

Q. agents-cli setup 실행 시 Google Cloud 프로젝트가 반드시 필요합니까?
A. 설치와 로컬 테스트(playground, eval run)까지는 GEMINI_API_KEY만 있으면 Google Cloud 프로젝트 없이 진행할 수 있습니다. 배포(deploy) 단계부터 Google Cloud 프로젝트, gcloud SDK, 인증 설정이 필요합니다.

Q. Agent Runtime 배포 시 한국 리전(asia-northeast3)을 사용할 수 있습니까?
A. 2026년 5월 기준으로 Agent Runtime의 한국 리전 지원 여부가 공식 문서에서 확인되지 않았습니다. Cloud Run은 서울 리전(asia-northeast3)을 지원하므로, 한국 서비스 레이턴시가 중요하다면 Cloud Run 배포 경로부터 검증하는 것을 권장합니다. 최신 리전 가용성은 Google Cloud 공식 문서에서 확인하시기 바랍니다.

Q. v0.1.x 단계에서 프로덕션 에이전트에 바로 적용해도 됩니까?
A. 권장하지 않습니다. v0.1.x는 초기 단계로 파괴적 변경(breaking changes)이 발생할 가능성이 있습니다. PoC나 내부 도구 수준에서 먼저 시작하고, GA(정식 출시) 이후 프로덕션 적용을 검토하는 것이 안전합니다.

참조 링크

 

• Agents CLI in Agent Platform: create to production in one CLI — Agents CLI 공식 소개 원본 발표
• google/agents-cli (GitHub Repository) — Agents CLI 공식 GitHub 저장소. 설치, 릴리스, 이슈 트래커
• Agents CLI Documentation — CLI 명령어 레퍼런스, Getting Started, 스킬 설명
• Build an agent with ADK and Agents CLI in Agent Platform (Quickstart) — ADK와 Agents CLI를 결합한 공식 빠른 시작 가이드
• Introducing Gemini Enterprise Agent Platform — Agents CLI가 속한 상위 플랫폼 공식 소개
• Google Cloud Introduces Agents CLI to Streamline AI Agent Development Lifecycle — 개발자 커뮤니티 반응과 Human Mode 분석

Google Cloud Agents CLI 이 글은 실제 사례를 바탕으로 작성되었습니다