agents-cli 소개
Claude Code나 Codex, Antigravity CLI 같은 코딩 에이전트는 범용 코드는 능숙하게 다루지만, 빠르게 바뀌는 특정 클라우드의 에이전트 스택 앞에서는 오래된 API와 잘못된 관례를 답습하기 쉽습니다. Google Cloud에서 에이전트를 만들어 운영하려면 ADK 코드 패턴부터 평가 방법론, Agent Runtime·Cloud Run·GKE 배포, Gemini Enterprise 등록까지 알아야 할 것이 많은데, 이를 사람이 전부 익혀서 코딩 에이전트에게 일일이 지시하는 것은 도구를 쓰는 의미를 반감시킵니다.
agents-cli 는 Google이 공개한 CLI와 스킬 묶음으로, 어떤 코딩 어시스턴트든 Google Cloud 위에서 AI 에이전트를 만들고 평가하고 배포하는 전문가로 바꾸는 것을 목표로 합니다. 그 자체가 코딩 에이전트는 아닙니다. 프로젝트 FAQ는 "agents-cli는 코딩 에이전트를 위한 도구이지, 코딩 에이전트가 아니다" 라고 선을 긋습니다. 스캐폴딩·평가·배포 같은 반복 작업은 CLI 명령으로 제공하고, ADK API 패턴이나 평가 방법론 같은 도메인 지식은 스킬 7종으로 코딩 에이전트에게 주입하는 구조입니다.
설치는 uvx google-agents-cli setup 한 번이면 CLI와 스킬이 코딩 에이전트에 함께 설치되고, Antigravity CLI·Claude Code·Codex를 비롯한 어떤 코딩 에이전트와도 함께 동작합니다. 본 게시물에서는 agents-cli의 스킬 구성과 평가 워크플로우, 이 도구가 얹혀 있는 Google Cloud 스택을 정리합니다.
ADK와 agents-cli의 관계
ADK(Agent Development Kit)는 에이전트를 만드는 프레임워크이고, agents-cli는 그 위의 작업 도구입니다. FAQ에 따르면 ADK만으로는 개발자가 프레임워크 사용법을 직접 익혀야 하지만, agents-cli는 코딩 에이전트가 ADK 에이전트를 만들고 평가하고 배포하는 전 과정을 대신 수행할 수 있도록 스킬과 도구를 제공합니다. 로컬 개발(scaffold · run · eval)에는 Google Cloud 계정이 필요 없고 AI Studio API 키로 Gemini를 로컬에서 쓸 수 있으며, 배포와 클라우드 기능을 쓸 때만 Google Cloud가 필요합니다.
누구에게 유용한가
Google Cloud에서 ADK 기반 에이전트를 배포·운영할 계획이 있는 팀에게는 스캐폴딩부터 CI/CD 인프라 구성까지 이어지는 일관된 경로가 생기므로 도입 가치가 큽니다. 로컬에서 에이전트 실험만 하는 개인도 AI Studio 키만으로 scaffold 와 eval 워크플로우를 쓸 수 있습니다. 반면 AWS나 자체 인프라 중심으로 배포하는 팀이라면 배포·퍼블리시·인프라 스킬 대부분이 Google Cloud 전용이라 활용 폭이 좁습니다. 배포 시 자원은 사용자 본인의 Google Cloud 프로젝트에 생성되고 그 비용과 관리는 사용자 책임이라는 점도 문서에 명시되어 있습니다.
agents-cli의 스킬 구성
스킬은 코딩 에이전트가 읽는 도메인 지식 문서로, 개발 수명주기 전체를 나눠 담고 있습니다.
| 스킬 | 코딩 에이전트가 배우는 것 |
|---|---|
google-agents-cli-workflow |
개발 수명주기, 코드 보존 규칙, 모델 선택 |
google-agents-cli-adk-code |
ADK Python API: 에이전트·도구·오케스트레이션·콜백·상태 |
google-agents-cli-scaffold |
프로젝트 스캐폴딩: create · enhance · upgrade |
google-agents-cli-eval |
평가 방법론: 지표, 데이터셋, LLM 판사, 적응형 루브릭 |
google-agents-cli-deploy |
배포: Agent Runtime, Cloud Run, GKE, CI/CD, 시크릿 |
google-agents-cli-publish |
Gemini Enterprise 등록 |
google-agents-cli-observability |
관측성: Cloud Trace, 로깅, 서드파티 연동 |
agents-cli의 CLI 명령과 평가 워크플로우
CLI는 코딩 에이전트 없이 단독으로도 쓸 수 있습니다. 눈에 띄는 것은 평가 명령군의 폭입니다. eval generate 로 평가 데이터셋에 대한 추론 트레이스를 만들고 eval grade 로 채점하는 기본 흐름 외에, 로컬 에이전트에 맞는 멀티턴 평가 시나리오를 합성하는 eval dataset synthesize, 채점 결과에서 실패 유형을 군집화하는 eval analyze, 평가 데이터를 이용해 에이전트 프롬프트를 자동 튜닝하는 eval optimize 까지 이어집니다.
agents-cli scaffold my-agent # 새 에이전트 프로젝트 생성
agents-cli run "prompt" # 단일 프롬프트로 에이전트 실행
agents-cli eval generate # 평가 케이스에 대한 추론 실행
agents-cli eval grade # 트레이스를 지표 기준으로 채점
agents-cli eval optimize # 평가 데이터 기반 프롬프트 자동 튜닝
agents-cli deploy # Google Cloud에 배포
agents-cli publish gemini-enterprise # Gemini Enterprise 등록
기존 프로젝트에는 scaffold enhance 로 배포·CI/CD·RAG 구성을 덧붙일 수 있고, infra cicd 는 스테이징·프로덕션 인프라와 CI/CD 파이프라인을 함께 준비합니다.
agents-cli가 얹혀 있는 Google Cloud 스택
에이전트 오케스트레이션은 Google의 ADK와 A2A로 구성하고, 모델은 Model Garden, 평가는 Agent Platform Evaluation, 배포는 Agent Runtime 또는 Cloud Run·GKE가 담당합니다. 여기에 벡터 스토어·모니터링 같은 데이터 계층, OpenTelemetry 기반 관측성·로깅, Terraform 기반 IaC와 CI/CD가 주변을 받칩니다. agents-cli의 스킬과 명령은 이 스택의 각 구성 요소를 코딩 에이전트가 다룰 수 있게 연결하는 역할입니다.
agents-cli 설치 및 시작하기
Python 3.11 이상, uv, Node.js가 필요합니다.
uvx google-agents-cli setup
스킬만 설치하려면 npx skills add google/agents-cli 를 사용합니다. 설치 후 코딩 에이전트를 열고 "agents-cli로 장황한 텍스트를 짧고 기술적인 원시인 말투로 압축하는 에이전트를 만들어줘" 같은 요청을 던지는 것이 공식 튜토리얼의 첫 예제입니다. 단계별 안내는 공식 퀵스타트 튜토리얼에 있습니다.
agents-cli의 라이선스
agents-cli는 Apache License 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
agents-cli 데모 영상
agents-cli 문서 사이트
agents-cli GitHub 저장소
이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다. 
이 도구를 직접 설치해 사용해보셨다면, 
파이토치 한국 사용자 모임
회원들을 위해 경험이나 팁을 댓글로 남겨주세요! 