google/agents-cli 딥다이브
— 내 코딩 에이전트를 'GCP 에이전트 개발 전문가'로 만드는 스킬 + CLI

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

공식 한 줄 설명은 "Turn your favorite coding assistant into an expert at building and deploying agents on Google Cloud". FAQ는 못을 박는다 — 이건 코딩 에이전트가 아니며, adk CLI의 대체재도 아니다. 다른 코딩 에이전트를 "잘 쓰게 만드는" 도구다. 그래서 제품의 본체는 7개의 SKILL.md이고, 파이썬 CLI는 그 스킬들이 uvx로 불러 쓰는 실행기다.

2왜 주목받는가

TrendShift 상승 이유 · 다른 에이전트 도구 대비 차별점.

2026년 상반기 깃허브 트렌딩은 "에이전트 스킬" 천지다. TrendShift 월간만 봐도 mattpocock/skills, addyosmani/agent-skills, obra/superpowers, phuryn/pm-skills … 죄다 .claude 폴더에서 꺼낸 스킬 모음이다. 이 흐름 한복판에 구글이 직접 내놓은 공식 스킬 묶음이 agents-cli다. "구글 공식 + ADK·Gemini Enterprise 전용 + 풀 라이프사이클"이라는 조합이 주목의 핵심이다.

포지셔닝이 거꾸로다

대부분의 트렌딩 도구는 "또 하나의 코딩 에이전트" 또는 "또 하나의 게이트웨이"다. agents-cli는 반대다 — 새 에이전트가 되려 하지 않고, 네가 이미 쓰는 에이전트를 더 똑똑하게 만든다. 이 "미들웨어" 전략 덕분에 Claude Code 플러그인, Gemini CLI 확장, npx skills 생태계에 동시에 올라탄다. 한 번 만들어 여러 에이전트에 꽂는다.

경쟁 방식 비교

3기술 스택 전체 지도

CLI 본체 · 배포 채널 · 생성되는 프로젝트 · GCP 연동면 전부.

CLI 본체 (이 저장소의 파이썬 코드)

※ 이 저장소는 "소스 미러"라 루트에 pyproject.toml이 없다(아래 5번 참고). 위 의존성은 실제 코드의 import에서 역추적한 것이다.

3가지 배포(설치) 정체성

생성되는 프로젝트의 스택 (scaffold 결과물)

4아키텍처 심화 분석

"스킬이 머리, CLI가 손발, GCP가 무대" — 3층 구조.

가장 헷갈리는 점부터 풀자. 이 시스템에는 세 명의 행위자가 있다. ① 사용자가 쓰는 코딩 에이전트(Claude Code 등), ② 그 에이전트가 읽는 스킬(SKILL.md), ③ 스킬이 호출하는 agents-cli 명령. 명령은 다시 GCP 서비스를 부른다. 데이터 흐름을 그림으로 보면:

핵심 설계 패턴 5가지

① 지연 명령 로딩 (Click LazyGroup)

모든 서브명령은 main.add_lazy_command("deploy", "google.agents.cli.deploy.cmd_deploy:cmd_deploy", "Deploy the agent.") 식으로 등록된다. 실제로 그 명령을 실행할 때만 해당 모듈을 import한다. agents-cli --help는 짧은 설명 문자열만 읽어 모듈 import 0회로 빠르게 뜬다. CLI 시작 속도를 지키는 흔하고 강력한 기법이다.

# src/google/agents/cli/_click.py (요약)
def get_command(self, ctx, cmd_name):
    if cmd_name in self._lazy_commands and cmd_name not in self.commands:
        module_path, attr = self._lazy_commands[cmd_name][0].split(":")
        cmd = getattr(importlib.import_module(module_path), attr)  # 이제서야 import
        patch_source_in_help(cmd)
        self.commands[cmd_name] = cmd
    return super().get_command(ctx, cmd_name)

② 스스로 출처를 밝히는 --help

patch_source_in_help()가 각 명령의 도움말 끝에 "Source: <실제 소스 파일 절대경로>"를 붙인다. 어떤 명령이 어느 파일에서 구현됐는지 --help만 봐도 안다. 코드를 읽거나 디버깅할 때 길잡이가 된다.

③ 패키지 데이터로서의 템플릿 (cookiecutter + Jinja2)

스캐폴딩은 {{cookiecutter.*}}·{%- if ... %} 같은 Jinja2 플레이스홀더가 박힌 템플릿 묶음이다. 4개 언어 × 4개 배포타깃 행렬(base_templates/ × deployment_targets/)에 공용 Terraform(_shared/)을 더해, create 시점에 실제 파일로 펼쳐진다. 사용자의 선택(배포타깃·세션종류·CI러너 등)은 agents-cli-manifest.yaml에 기록돼, 나중에 enhance/upgrade가 그 선택을 다시 읽는다.

④ 스테이징된 러너 스크립트 (버전 격리)

eval/_inference_runner.py 같은 스크립트는 CLI 패키지에 동봉돼 있다가, 사용자의 프로젝트 폴더(.agents-cli-scripts/)로 복사돼 사용자 자신의 uv 가상환경(=올바른 ADK 버전)에서 실행된다. CLI의 환경이 아니라 프로젝트의 환경에서 돌려야 평가가 정확하기 때문이다.

⑤ 재구현하지 않고 감싼다

agents-cli는 uv·npx skills·gcloud·kubectl·terraform을 직접 다시 만들지 않고 _runner 추상화로 감싸서 호출한다. CLOUDSDK_CORE_DISABLE_PROMPTS=1을 설정해 gcloud가 멈춰 서서 입력을 기다리지 않게 한다(--interactive일 때만 예외). 자동화에 최적화된 선택이다.

5디렉토리 구조 해부

스킬은 어디 있고, CLI 코드는 어떻게 나뉘는가.

반대로, 생성되는 프로젝트는 테스트가 풍부하다. 모든 스캐폴드가 tests/unit·tests/integration(실서버 e2e)·tests/load_test(Locust)를 4개 언어 각각에 깔아주고, eval/ 하니스와 데이터셋까지 붙여준다. "도구 본체는 가볍게, 만들어주는 결과물은 탄탄하게"라는 철학이 보인다.

6학습 포인트 (기술별)

이 저장소 하나로 배울 수 있는 것 + 각자 실습 아이디어.

6-1. 에이전트 스킬 설계 (SKILL.md)

가장 값진 학습 포인트. 각 스킬의 머리말은 단순 설명이 아니라 "언제 쓰고, 언제는 쓰지 말지"를 명시한다. 예컨대 scaffold 스킬의 description은 "이럴 때 써라"를 트리거 문구로 나열한 뒤, "코드 작성은 adk-code 스킬, 배포는 deploy 스킬을 써라(Do NOT use for…)"라고 다른 스킬과의 경계를 못 박는다. 스킬끼리 겹치지 않게 하는 설계다.

# skills/google-agents-cli-scaffold/SKILL.md (머리말)
---
name: google-agents-cli-scaffold
description: >
  "create an agent project", "start a new ADK project" 같은 요청에 사용.
  scaffold create / enhance / upgrade, 템플릿 옵션, 배포 타깃을 다룬다.
  Do NOT use for 코드 작성(use ...-adk-code) or 배포(use ...-deploy).
metadata:
  author: Google
  license: Apache-2.0
  version: 0.6.1
  requires: { bins: [agents-cli] }
---

본문은 사람용 문서가 아니라 에이전트용 가드레일이다. workflow 스킬은 "STOP — Do NOT write code yet. 프로젝트가 없으면 scaffold create부터."라는 강한 단계 게이트로 시작한다. "Vertex AI Agent Engine → --deployment-target agent_runtime" 같은 제품명 매핑표까지 들어 있다.

6-2. 파이썬 CLI 잘 만들기 (Click + LazyGroup)

Click으로 서브명령 그룹을 만드는 법, 그리고 지연 로딩으로 시작 속도를 지키는 실전 패턴을 통째로 배운다. add_lazy_command(name, "module:obj", short_help) → 실행 시점 import. --help에 소스 경로를 자동으로 붙이는 메타 트릭, UTF-8 강제(윈도우 호환), Ctrl-C를 exit 130으로 처리하는 견고한 최상위 에러 핸들링도 좋은 교재다.

6-3. 코드 생성기 (cookiecutter + Jinja2)

"프로젝트 뼈대를 찍어내는 도구"를 만드는 법. {{cookiecutter.agent_directory}} 같은 변수와 {%- if deployment_target == "cloud_run" %} 같은 조건 블록으로, 하나의 템플릿이 사용자 선택에 따라 다른 결과물을 낳는다. 선택값을 manifest.yaml로 저장해 두면 나중에 "업그레이드"도 가능하다는 설계가 특히 배울 만하다.

6-4. Google ADK로 에이전트 만들기

스캐폴드가 찍어주는 에이전트 코드 자체가 ADK 입문서다. Agent(이름·모델·지시문·도구), App(루트 에이전트를 감싸는 실행 단위), Gemini(모델 + 재시도 옵션), 함수 도구(tools=[get_weather, ...])의 조립을 보여준다.

# scaffold/agents/adk/app/agent.py (Jinja2 템플릿)
root_agent = Agent(
    name="root_agent",
    model=Gemini(model="gemini-flash-latest",
                 retry_options=types.HttpRetryOptions(attempts=3)),
    instruction="You are a helpful AI assistant ...",
    tools=[get_weather, get_current_time],
)
app = App(root_agent=root_agent, name="{{cookiecutter.agent_directory}}")

6-5. 평가 주도 개발 (Quality Flywheel)

agents-cli의 진짜 차별점. "만들고 끝"이 아니라 측정→개선 루프를 코드로 제공한다. eval generate(데이터셋으로 에이전트 추론 → 트레이스) → eval grade(LLM 심판이 메트릭으로 채점) → eval dataset synthesize(LLM이 가상 사용자로 멀티턴 시나리오 생성) → eval compare(두 결과 비교) → eval analyze(실패 군집화) → eval optimize(평가 데이터로 프롬프트 자동 튜닝).

6-6. GCP 배포 & A2A 등록

같은 에이전트를 cloud_run·agent_runtime·gke 세 환경에 올려보며 차이를 익힌다. uv sync --frozen으로 빌드해 uvicorn으로 8080에 서빙하는 컨테이너, Terraform의 Workload Identity Federation·Cloud Build, 그리고 publish가 REST로 Gemini Enterprise에 A2A 에이전트 카드를 등록하는 흐름까지. 엔터프라이즈 네트워킹(PSC, DNS 피어링) 옵션도 노출된다.

# scaffold/base_templates/python/Dockerfile
FROM python:3.12-slim
RUN pip install --no-cache-dir uv==0.8.13
RUN uv sync --frozen
CMD ["uv","run","uvicorn","{{cookiecutter.agent_directory}}.fast_api_app:app",
     "--host","0.0.0.0","--port","8080"]

7하드웨어 / 시스템 요구사항

로컬 실습은 가볍다 — GPU도, 무거운 서버도 필요 없다.

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — 위에서부터 차례로.

9관련 기술 심화 학습 로드맵

이 저장소를 출발점으로, 6주 코스.

10핵심 키워드 사전

문서·코드에서 계속 마주칠 용어들.

11참고 링크

더 깊이 파고들기 위한 공식 자료.