구글이 ‘google/agents-cli’를 공개했습니다. 이름만 보면 또 하나의 AI 에이전트 도구처럼 보이지만, 저는 조금 다르게 봤습니다. 이건 Codex나 Claude Code 같은 코딩 도구를 대체하는 물건이 아니라, 그런 도구가 Google Cloud 위에서 ADK 에이전트를 만들고, 평가하고, 배포할 때 덜 추측하게 만드는 절차 묶음에 가깝습니다.

요즘은 에이전트 데모 하나 만드는 일 자체는 예전보다 훨씬 쉬워졌습니다. 문제는 그 다음입니다. 이 에이전트가 어떤 문서를 읽어도 되는지, 틀린 답은 어떻게 잡을지, 누가 승인할지, 배포 뒤 로그는 어디서 볼지, 문제가 생기면 어떻게 되돌릴지. 이 부분이 흐리면 에이전트는 편한 도구가 아니라 새 운영 리스크가 됩니다.

이 글을 쓰게 된 배경

저는 이제 “AI 에이전트를 만든다”는 말에 예전만큼 반응하지 않습니다. 첫 버전은 금방 나옵니다. 진짜 문제는 둘째 주에 옵니다. 왜 어제와 다른 답을 했는지, 근거 문서는 맞는지, 누가 수정해야 하는지 물어보기 시작할 때입니다.

그래서 ‘agents-cli’에서 먼저 본 건 설치 명령이 아니었습니다. 공식 GitHub FAQ는 이 도구가 Codex, Claude Code, Antigravity CLI의 대체재가 아니라고 못박습니다. 이 도구는 그런 코딩 에이전트가 ADK 에이전트를 만들고, 평가하고, 배포할 때 필요한 명령과 스킬을 제공하는 쪽입니다.

말은 덜 화려하지만, 실무에서는 이쪽이 더 중요합니다. 에이전트 자체보다 에이전트를 둘러싼 절차가 보이는지가 관건입니다.

실제로 놓고 본 업무

저라면 고객에게 바로 노출되는 상담봇부터 만들지 않습니다. 먼저 내부 triage agent를 하나 잡겠습니다. 예를 들어 협력사 문의나 정책 예외 요청이 들어왔을 때, 다음 정보를 받아 처리하는 작은 에이전트입니다.

  • 들어온 요청 한 건
  • 현재 정책 문서
  • 고객 또는 프로젝트 상태 메모
  • 결과가 나가야 할 형식

에이전트가 해야 할 일도 좁혀야 합니다. 답변 초안을 쓰고, 근거 문단을 표시하고, 사람이 확인해야 하는지 표시하고, 다음 담당자를 지정합니다. 이 정도면 실제 업무에 가까우면서도 실패를 잡아내기 쉽습니다.

실제로 비교한 기준

저는 ‘agents-cli’를 만능 제작기가 아니라 lifecycle wrapper로 봤습니다.

단계도구에서 기대한 것아직 믿으면 안 되는 것
설치Python 3.11+, ‘uv’, Node.js, 스킬 설치가 반복 가능하게 남는가누군가 기억으로 명령을 복사해 오는 방식
Scaffoldagent code, test, eval, deploy 파일이 분리되는가generated file이 한 폴더에 쌓이고 아무도 안 보는 상태
ADK 코드tool, callback, state, agent behavior가 보이는가프롬프트만 길고 경계가 없는 에이전트
평가test case, grading, version compare, failure analysis가 가능한가샘플 하나 맞췄으니 된다는 판단
배포Agent Runtime, Cloud Run, GKE 같은 배포 경로가 보이는가권한과 비용 책임자가 없는 cloud deploy
관측실패를 설명할 로그와 trace가 남는가첫날 이후 아무도 보지 않는 production agent

공식 설치 예시는 ‘uvx google-agents-cli setup’입니다. 코딩 에이전트에 스킬만 붙일 때는 ‘npx skills add google/agents-cli’도 제시되어 있습니다. 시작은 가볍습니다. 다만 저는 시작이 가벼운 도구일수록 운영 기준을 더 먼저 봅니다.

제가 본 체크 항목

첫 파일럿 옆에는 세 가지를 붙여야 한다고 봅니다.

첫째, 실패 사례 파일입니다. 애매한 요청, 오래된 정책, 근거가 빠진 요청을 일부러 넣어야 합니다. 깨끗한 예시만 통과하는 건 별 의미가 없습니다.

둘째, 검토자입니다. 결과를 사람이 승인한다면, 그 사람이 무엇을 보고 통과시킬지 알아야 합니다.

셋째, 되돌리는 방법입니다. 배포 뒤 동작이 바뀌면 회의부터 열 게 아니라 일단 멈출 방법이 있어야 합니다.

운영에서 걸리는 부분

막히는 곳은 CLI 명령이 아닙니다. 보통 “믿어도 되는가”에서 막힙니다.

생성된 에이전트는 보기에는 그럴듯해도 이런 식으로 무너질 수 있습니다.

  • 정책 문단은 맞게 인용했지만 버전 날짜를 놓침
  • 예외 요청을 엉뚱한 담당자에게 배정함
  • 내부 검토용 사안을 고객에게 보낼 문장으로 작성함
  • 쉬운 eval set은 통과했지만 실제 문의에서는 흔들림
  • 배포는 됐는데 첫날 이후 로그를 보는 사람이 없음

그래서 저는 scaffold보다 eval 쪽을 더 봅니다. 공식 문서에는 eval 생성, grading, version compare, failure analysis, metric list, prompt optimize 흐름이 나옵니다. 이 루프를 건너뛰면 CLI는 더 깔끔한 첫 초안을 만들어 줄 뿐입니다.

다음에는 이렇게 고른다

제가 이 도구를 보겠다고 판단하는 조건은 세 가지입니다.

팀이 Google Cloud에 익숙해야 합니다. 에이전트가 ADK, Agent Runtime, Cloud Run, GKE, Gemini Enterprise 근처에 놓일 가능성이 있어야 합니다. 그리고 배포 이후에도 evaluation case를 관리할 사람이 있어야 합니다.

반대로 로컬 자동화 하나, 단발성 스크립트 하나, 단순 챗봇 하나라면 굳이 여기까지 갈 필요는 없어 보입니다. 도구가 업무보다 커지면 그때부터는 자동화가 아니라 운영 부담입니다.

좁게 시작하는 편이 낫습니다. 내부 triage agent 하나, source set 하나, output format 하나, deployment target 하나, 그리고 일부러 까다로운 eval case 10개에서 50개. 저는 이 정도가 첫 실험의 적정선이라고 봅니다.

자동화 스택에 넣을 때와 미룰 때

처음에는 사람이 마지막 확인을 하는 내부 triage, 정책 검토, 운영 요청 분류 같은 곳에만 쓸 만한 경우라고 봅니다. 반대로 고객에게 최종 답변을 보내거나, 기록을 바꾸거나, 예외 승인을 처리하는 일까지 바로 맡기는 건 과합니다.

제가 먼저 보는 건 “명령이 잘 실행되느냐”가 아니라 “실패했을 때 멈출 지점이 보이느냐”입니다. 이 지점이 안 보이면 좋은 CLI도 운영에서는 부담으로 돌아옵니다.

적용 전 체크리스트

  • 팀의 Windows 사용 방식이 괜찮은지 확인하세요. 현재 문서는 native Windows보다 WSL 2 쪽을 말합니다.
  • 로컬 AI Studio 개발이면 충분한지, Google Cloud 배포까지 필요한지 먼저 나누세요.
  • scaffold를 믿기 전에 eval case를 먼저 쓰세요.
  • 실패한 요청 하나는 반드시 repo에 남기세요.
  • 검토자, cloud project owner, 비용 책임자를 이름으로 정하세요.
  • 로그 경로가 보이기 전에는 실행 권한이나 배포 권한을 넓히지 마세요.
  • LLM-as-judge는 선별 도구로만 두고, 민감한 판단의 최종 기준으로 두지 마세요.

확인한 자료

2026년 7월 6일 기준으로 공식 GitHub repo, getting started 문서, CLI reference, evaluation guide, deployment guide, Google Cloud quickstart, Google Developers Blog 글, PyPI package page를 확인했습니다. 이 도구는 변화가 빠르기 때문에, ADK와 Agent Platform과 agents-cli가 섞여 설명되는 2차 요약글보다 공식 문서를 우선했습니다.

짧게 결론부터

ADK 에이전트를 Google Cloud에 올릴 가능성이 이미 있다면 ‘agents-cli’는 테스트할 만합니다. 반대로 “로컬에서 작은 작업 하나 자동화하면 된다”면 과할 가능성이 큽니다.

제가 파일럿 카드에 적을 문장은 이겁니다.

‘agents-cli’는 에이전트 생애주기를 보이게 만드는 데 쓰는 도구지, 생애주기를 고민하지 않게 해주는 도구는 아닙니다.

이 차이가 중요합니다. CLI는 코딩 에이전트가 올바른 절차를 덜 잊게 해줄 수 있습니다. 하지만 이 에이전트를 만들어도 되는지, eval set이 정직한지, 조직이 운영할 준비가 됐는지는 여전히 사람이 결정해야 합니다.

두 시간짜리 파일럿이라면

저라면 production 권한 없이 두 시간만 줍니다.

첫 한 시간은 스킬 설치, 좁은 agent scaffold, design spec 작성입니다. 업무는 일부러 단순한 게 좋습니다. 내부 triage agent 예시가 괜찮은 이유는 기대 출력이 뚜렷하기 때문입니다. 근거 문단, 검토 표시, 담당자, 다음 행동. 이 네 가지가 틀리면 바로 보입니다.

두 번째 한 시간은 eval set 작성과 grading입니다. 정상 요청, 근거가 부족한 요청, 오래된 정책 요청, 거절해야 하는 요청을 섞습니다. 그 뒤 prompt나 policy를 하나만 바꾸고, 첫 버전보다 어디가 나아졌고 어디가 나빠졌는지 대조해 봅니다.

두 번째 시간에 의미 있는 실패 메모가 안 나오면 배포하지 않는 편이 낫습니다. 엄격해 보이지만, 실제 업무에 들어간 뒤 실패 패턴을 발견하는 것보다 훨씬 싸게 먹힙니다.

rollout note에 남길 질문

질문넓히기 전 제 답
에이전트가 읽어도 되는 자료는 무엇인가지정한 정책 문서와 source bundle만
에이전트가 하면 안 되는 일은 무엇인가최종 답변 발송, 기록 변경, 예외 승인
개선됐다고 볼 증거는 무엇인가수정 횟수는 늘지 않고 검토 시간이 줄어드는 것
파일럿 중단 기준은 무엇인가근거 hallucination, 담당자 오배정, 로그 누락
다음 버전 책임자는 누구인가“AI팀”이 아니라 이름이 있는 editor 또는 platform owner

이 정도 메모가 있어야 도구가 쓸모 있어집니다. 없으면 ‘agents-cli’는 조직이 운영할 수 있는 속도보다 더 빨리 소프트웨어를 만드는 또 다른 방법이 됩니다.

FAQ

google/agents-cli는 Codex나 Claude Code 대체재인가요?

아닙니다. 공식 FAQ는 이 도구가 coding agent 자체가 아니라 coding agent를 위한 도구라고 설명합니다. 저는 ADK 에이전트 작업을 도와주는 skill과 command layer로 보는 편이 맞다고 봅니다.

Google Cloud 없이도 쓸 수 있나요?

로컬 개발은 가능합니다. 문서상 AI Studio API key로 로컬 개발을 할 수 있습니다. 다만 배포와 cloud 기능까지 가면 Google Cloud가 필요합니다.

production agent가 자동으로 안전해지나요?

아닙니다. 구조, 평가, 배포, 로그에는 도움을 줄 수 있지만 eval set, 권한, source policy, review boundary는 팀이 직접 책임져야 합니다.

어디서 시작하는 게 좋나요?

고객에게 바로 노출되지 않는 내부 triage agent부터 시작하는 편이 낫습니다. 작지만 까다로운 eval set을 통과하지 못하면 권한을 넓히지 않는 게 맞습니다.

에이전트 요구사항이 스캐폴드, ADK 코드, 평가, 배포, 로그 확인으로 이어지는 운영 흐름도
제가 보는 핵심은 첫 생성물이 아닙니다. 단계 사이의 확인 지점입니다. 약한 에이전트는 보통 거기서 비용을 만들기 때문입니다.

업무 흐름

이 글이 속한 업무 흐름

지금 읽는 글이 어떤 업무 흐름에 연결되는지 확인하고, 관련 글로 이어서 볼 수 있습니다.

도구 스택 선택 팀의 운영 성숙도에 맞는 스택을 고릅니다.

자동화 플랫폼, 앱 빌더, 에이전트 빌더, 회계 도구, 범용 AI 어시스턴트는 운영 부담까지 같이 따져야 합니다.

관련 주제 보기
잘 맞는 경우
간단한 도구 구매, 내부 워크플로우 구축, 더 큰 플랫폼 도입 사이에서 결정해야 하는 팀
맞지 않을 수 있는 경우
판단 기준보다 단계별 설정 방법이 먼저 필요한 경우에는 다른 실행형 글이 더 적합합니다.
관련 글

참고한 공개 자료

본문의 보도 사실, 공식 문서, 정책 배경, 제품 정보, 바뀔 수 있는 주장을 확인할 때 참고한 공개 자료입니다.

다음 단계

읽은 내용을 운영 체크리스트로 옮겨보세요.

먼저 리소스 경로에서 업무 flow를 점검하고, 현재 프로세스와 인계 지점을 확인한 뒤 도구를 비교하세요.

도구 업데이트 제보