Google Agents CLI 해설: ADK로 에이전트를 만들기보다 배포 수명주기 CLI부터 고정해야 하는 이유

발행일: 2026-05-12 | 카테고리: 개발정보

Google이 2026년 4월 공개한 Agents CLI는 단순한 개발 보조 도구가 아닙니다. 핵심은 ADK로 에이전트를 만들고 끝내는 것이 아니라, 스캐폴딩·평가·배포·관측성을 하나의 운영 경로로 묶는 데 있습니다. 이 글은 왜 지금 팀이 프롬프트보다 먼저 이 수명주기 계층을 봐야 하는지 실무 기준으로 해설합니다.

1. 한 줄 문제 정의

핵심 요약: 에이전트 프로젝트가 실패하는 가장 흔한 이유는 모델 성능 부족보다 로컬 실험과 운영 배포 사이의 틈을 방치하는 데 있습니다.

요즘 팀들은 ADK, LangGraph, OpenAI SDK 같은 프레임워크로 에이전트 프로토타입을 빠르게 만듭니다. 문제는 그 다음입니다. 누가 프로젝트 뼈대를 만들고, 어떤 방식으로 평가 데이터를 붙이고, 배포용 인프라와 CI/CD를 어떻게 연결할지 정하지 않으면 프로토타입은 금방 늘어나지만 운영 가능한 서비스는 남지 않습니다. 특히 코딩 에이전트에게 작업을 맡길수록 이 틈은 더 커집니다. 문서를 많이 읽혀도, 실제 배포 경로가 기계가 이해할 만큼 구조화돼 있지 않으면 토큰만 쓰고 반복 루프에 빠집니다.

이 글의 대상 독자는 Google Cloud에서 사내 업무용 에이전트, 지원 자동화 에이전트, 코딩 보조 에이전트를 검토하는 개발자와 플랫폼 엔지니어입니다. 범위는 Google Agents CLI + ADK + Agent Platform 조합을 어떻게 읽어야 하는지입니다. 반대로 모델 성능 순위 경쟁이나 일반적인 프롬프트 엔지니어링 요령은 다루지 않습니다.

2. 먼저 결론

핵심 요약: Agents CLI는 새 프레임워크라기보다 에이전트 개발 수명주기를 표준화하는 운영 인터페이스로 보는 편이 맞습니다.

• 지금 잘 맞는 팀: ADK 기반 에이전트를 만들고 있고, 평가·배포·관측성을 한 경로로 묶고 싶은 팀
• 아직 과한 팀: 로컬 데모 1개만 만들면 되고, Cloud Run·GKE·Agent Runtime 배포가 당장 필요 없는 팀
• 제 판단: 이번 발표의 진짜 가치는 에이전트를 더 쉽게 "코딩"하게 한 것이 아니라, 코딩 에이전트가 실수 없이 운영 경로를 밟게 하는 기계 친화적 계약을 제공한 데 있습니다.

따라서 도입 순서도 바뀌어야 합니다. 먼저 ADK 예제를 많이 만드는 것이 아니라, 1) 프로젝트 템플릿, 2) 평가 기준, 3) 배포 대상, 4) 관측성 경계를 먼저 고정하고 그 안에서 에이전트를 늘리는 편이 낫습니다. 그렇지 않으면 팀마다 다른 폴더 구조, 다른 평가 방식, 다른 배포 스크립트가 생겨 나중에 통제가 어려워집니다.

3. 핵심 구조 분해

핵심 요약: Agents CLI는 ADK를 대체하지 않고, ADK 바깥의 반복 업무를 네 층으로 묶습니다.

1. 코드 생성 층: agents-cli create로 프로젝트 뼈대와 템플릿을 만듭니다. 여기서 중요한 것은 파일 생성 자체보다, 코딩 에이전트가 같은 기본 구조를 보게 만든다는 점입니다.
2. 개발/실험 층: agents-cli install, agents-cli playground 같은 흐름으로 로컬 개발과 ADK 웹 플레이그라운드를 연결합니다. 초보 개발자 기준으로는 "샘플 코드"보다 한 단계 위인 실험 작업대라고 보면 됩니다.
3. 평가 층: Google 문서는 7개의 번들 스킬 중 하나를 평가 전용으로 두고, 블로그에서는 agents-cli eval run, agents-cli eval compare를 예시로 듭니다. 즉 에이전트를 만든 뒤 품질을 수치로 비교하는 경로가 처음부터 들어 있습니다.
4. 운영 층: agents-cli infra single-project, agents-cli deploy, agents-cli publish gemini-enterprise까지 이어집니다. 이 부분이 핵심입니다. 로컬 에이전트를 Cloud Run, GKE, Agent Runtime, Gemini Enterprise 등록까지 한 경로로 묶어 줍니다.

쉽게 비유하면 ADK는 엔진이고, Agents CLI는 조립 라인입니다. 엔진만 좋아도 조립 라인이 없으면 생산성이 흔들립니다. 이번 발표는 바로 그 조립 라인을 기계가 읽기 쉬운 형태로 만든 것입니다.

4. 설계 의도 해설

핵심 요약: Google은 에이전트를 더 똑똑하게 만드는 것보다 코딩 에이전트가 문서 폭탄 없이 올바른 경로를 타게 하는 것에 집중한 것으로 보입니다.

공식 블로그는 문제를 아주 직접적으로 말합니다. 에이전트 개발 인프라가 분절돼 있고, 코딩 어시스턴트가 로컬에서 클라우드로 넘어가는 방법을 이해하려면 너무 많은 문서를 먹어야 한다는 점입니다. 그래서 Agents CLI는 단순 CLI가 아니라, Gemini CLI·Claude Code·Codex 같은 코딩 에이전트에 설치되는 번들 스킬 묶음까지 함께 제공합니다.

여기서 설계 의도가 드러납니다. Google은 사람만 쓰는 터미널 도구를 만든 것이 아닙니다. 사람과 코딩 에이전트가 같은 수명주기 명령을 공유하게 만드는 인터페이스를 만든 것입니다. 이 방식의 장점은 분명합니다.

• 얻는 것: 템플릿 일관성, 배포 경로 표준화, 평가와 관측성의 초기 내장
• 포기하는 것: 완전 자유로운 프로젝트 구조, 클라우드 중립성, 프레임워크 무관성 일부
• 실무 해석: 에이전트 품질만이 아니라 팀 운영 편차까지 줄이려는 시도입니다

Agents CLI가 ADK를 전제로 한다는 점도 중요합니다. 즉 Google의 메시지는 "새 에이전트 프레임워크를 또 배워라"가 아닙니다. 이미 있는 ADK 위에 운영 계층을 얹어라에 가깝습니다. 이것은 팀 입장에서 훨씬 현실적입니다.

5. 근거 및 비교

핵심 요약: 비교 기준은 모델 품질이 아니라 수명주기 표준화 범위, 배포 마찰, 운영 자유도입니다.

공식 자료를 보면 차이가 더 선명합니다.

• Google 블로그(2026-04-22): uvx google-agents-cli setup로 스킬을 주입하고, agents-cli eval run, agents-cli deploy 같은 수명주기 명령을 제시합니다.
• Agents CLI 문서: 7개의 번들 스킬, Python 3.11+, uv, Node.js 요구사항, Cloud Run/GKE/Agent Runtime/Observability 경로를 명시합니다.
• Gemini CLI 서브에이전트 글(2026-04-15): Google이 코딩 에이전트의 병렬 서브에이전트와 격리 컨텍스트를 강조하고 있어, Agents CLI가 이 흐름과 자연스럽게 맞물립니다.
• AWS AgentCore 문서: TypeScript 시작 경로에서도 Docker 또는 원격 CodeBuild, AWS 계정·권한·리전 설정이 전제됩니다. 즉 배포 계약은 분명하지만 진입 경로의 감각은 Google보다 인프라 친화적입니다.

제 해석은 이렇습니다. Google은 코딩 에이전트가 수명주기 전체를 더 적은 문맥으로 밟도록 만드는 쪽에 무게를 두고 있고, AWS는 런타임과 배포 제어를 더 명시적으로 드러내는 쪽에 무게를 둡니다. 어느 쪽이 낫다는 문제가 아니라, 팀의 현재 병목이 어디인지가 중요합니다.

6. 실제 동작 흐름 / 단계별 실행 방법

핵심 요약: 시작은 새 에이전트 코드를 많이 쓰는 것이 아니라 템플릿-평가-배포 순서를 고정하는 것입니다.

1. 템플릿을 하나로 통일합니다.
   초기에는 agents-cli create my-agent --prototype --yes 같은 최소 템플릿만 허용하는 편이 좋습니다. 팀마다 폴더 구조가 달라지면 코딩 에이전트도 헤맵니다.
2. ADK 플레이그라운드에서 로컬 동작을 확인합니다.
   agents-cli install 후 agents-cli playground로 실험 환경을 올립니다. 이 단계에서 도구 호출과 입력 구조를 먼저 다듬으십시오.
3. 평가 데이터셋을 먼저 만듭니다.
   블로그 예시처럼 agents-cli eval run, agents-cli eval compare를 붙이십시오. 데모가 잘 되는 것과 운영에서 품질이 유지되는 것은 다릅니다.
4. 배포 대상을 미리 좁힙니다.
   Cloud Run인지 GKE인지 Agent Runtime인지 먼저 정하십시오. 하나의 글에서 모두 가능하다고 해도, 팀의 첫 경로는 하나여야 합니다.
5. 관측성을 기본값으로 둡니다.
   문서가 Cloud Trace와 BigQuery 플러그인까지 안내하는 이유가 여기에 있습니다. 에이전트는 실패 원인이 프롬프트인지 도구인지 배포인지 구분하기 어려워 로그가 특히 중요합니다.

# 설치
uvx google-agents-cli setup

# 최소 프로젝트 생성
agents-cli create support-agent --prototype --yes
cd support-agent

# 로컬 개발 환경 준비
agents-cli install
agents-cli playground

# 평가 실행
agents-cli eval run
agents-cli eval compare evals/run_v1.json evals/run_v2.json

# 배포 인프라/배포
agents-cli infra single-project
agents-cli deploy

초보 개발자 기준으로 정리하면, 이 흐름의 핵심은 "클라우드 배포가 된다"가 아니라 에이전트가 성장해도 같은 순서로 검증하게 만든다는 점입니다.

7. 실수/함정(Pitfalls)

핵심 요약: Agents CLI를 도입해도 팀이 흔히 망가지는 지점은 여전히 표준 미고정과 과도한 병렬화입니다.

• 실수 1: Agents CLI를 설치만 하고 각 팀이 제멋대로 템플릿을 바꾸는 것
  예방: 초기에는 허용 템플릿과 디렉터리 규칙을 1~2개로 제한합니다.
  복구: 이미 만든 프로젝트를 기준 템플릿으로 역정렬하고 차이를 문서화합니다.
• 실수 2: 평가 없이 바로 배포하는 것
  예방: 최소한 실패 사례 10~20개라도 고정 데이터셋을 만듭니다.
  복구: 운영 로그에서 반복 실패 질문을 추출해 eval 세트로 승격합니다.
• 실수 3: Cloud Run, GKE, Agent Runtime을 동시에 열어두는 것
  예방: 첫 배포 경로는 하나로 제한합니다.
  복구: 실제 트래픽이 있는 경로만 남기고 나머지는 실험 브랜치로 분리합니다.
• 실수 4: 코딩 에이전트 병렬 작업을 과신하는 것
  예방: Gemini CLI 서브에이전트 문서가 경고하듯, 무거운 코드 수정 병렬화는 충돌과 사용량 급증을 부를 수 있습니다.
  복구: 탐색·평가·문서화는 병렬, 코드 수정과 배포는 직렬로 되돌립니다.
• 실수 5: Agents CLI를 클라우드 중립 도구처럼 오해하는 것
  예방: ADK와 Google Cloud 결합을 전제로 설계를 시작합니다.
  복구: 멀티클라우드 요구가 커지면 공통 도메인 로직과 배포 경로를 분리합니다.

8. 강점과 한계

핵심 요약: Agents CLI의 강점은 운영 일관성이고, 한계는 모든 팀에 필요한 보편 툴은 아니라는 점입니다.

• 강점: 코딩 에이전트와 사람이 같은 수명주기 명령을 공유할 수 있습니다.
• 강점: ADK를 버리지 않고, 그 바깥의 반복 작업을 구조화합니다.
• 강점: 평가와 관측성을 개발 초기부터 끼워 넣기 쉽습니다.
• 한계: Google Cloud와 ADK에 대한 의존성이 있어 완전한 클라우드 중립을 원하면 부담이 됩니다.
• 한계: 단순 챗봇 데모만 필요한 팀에는 템플릿과 인프라 계층이 과할 수 있습니다.
• 반례: 이미 Terraform, 별도 CI/CD, LangGraph 중심 내부 플랫폼이 단단한 팀은 Raw ADK나 다른 런타임을 유지하는 편이 더 나을 수 있습니다.

제 의견은 명확합니다. Agents CLI는 에이전트를 처음 배우는 도구라기보다, 에이전트를 여러 개 운영하기 시작한 팀이 표준화를 위해 검토할 도구입니다.

9. 더 깊게 공부할 포인트

핵심 요약: 다음 단계는 새 모델 비교보다 수명주기 어느 구간을 플랫폼이 맡고 어느 구간을 팀이 맡을지를 정하는 일입니다.

• 우리 팀은 평가 세트를 어디에 저장하고 누가 승인할 것인가
• Cloud Run, GKE, Agent Runtime 중 첫 기본 경로는 무엇인가
• 관측성은 Cloud Trace만으로 충분한가, BigQuery 분석이 필요한가
• 코딩 에이전트가 수정할 수 있는 파일 경계와 사람이 승인할 경계는 어디인가
• ADK 코드와 배포 자동화 코드를 같은 저장소에 둘지 분리할지

10. 참고자료

• Google Developers Blog - Agents CLI in Agent Platform: create to production in one CLI (작성일: 2026-04-22, 확인일: 2026-05-12)
• Google Agents CLI Docs - Getting Started (확인일: 2026-05-12)
• Google Agents CLI Docs - Home / supported skills overview (확인일: 2026-05-12)
• Google Developers Blog - Subagents have arrived in Gemini CLI (작성일: 2026-04-15, 확인일: 2026-05-12)
• AWS Docs - Get started with the AgentCore CLI in TypeScript (확인일: 2026-05-12)
• AWS Docs - Amazon Bedrock AgentCore Runtime direct code deployment (확인일: 2026-05-12)

11. 실행 체크리스트 + 작성자 관점

핵심 요약: Agents CLI를 잘 쓰는 팀은 프롬프트보다 템플릿, 평가, 배포 경계를 먼저 고정합니다.

• 에이전트 프로젝트 템플릿을 1~2개로 제한했다
• 로컬 실험 후 반드시 통과해야 할 평가 세트가 있다
• 첫 배포 경로를 Cloud Run, GKE, Agent Runtime 중 하나로 좁혔다
• 코딩 에이전트가 자동으로 바꿔도 되는 파일과 사람이 검토할 파일을 나눴다
• 로그·트레이스·평가 결과를 같은 프로젝트 기준으로 모으고 있다
• 병렬 서브에이전트는 탐색/분석에 우선 쓰고, 코드 수정과 배포는 직렬 원칙을 둔다
• 멀티클라우드가 필요하다면 ADK 도메인 코드와 배포 계층을 분리할 계획이 있다

Definition of Done: 팀이 같은 템플릿으로 에이전트를 만들고, 같은 평가 세트를 통과한 뒤, 같은 배포 경로와 관측성 기준으로 운영에 올리는 흐름이 문서화되어 있으면 1차 도입 완료로 봅니다.

제 추천: Google Cloud 중심 팀이라면 Agents CLI를 "편한 생성기"가 아니라 에이전트 운영 표준화 장치로 도입하십시오. 반대로 아직 로컬 데모 단계라면 서두르지 말고 Raw ADK로 개념을 익힌 뒤, 두 번째나 세 번째 에이전트부터 Agents CLI를 붙이는 편이 더 현실적입니다. 처음부터 모든 실험에 과한 인프라를 얹는 것도, 끝까지 수명주기 표준 없이 버티는 것도 둘 다 좋지 않습니다.