Google agents-cli: 코딩 에이전트를 엔터프라이즈 에이전트 운영자로 바꾸는 도구

Google agents-cli · ADK 2.0 · Gemini Enterprise Agent Platform

Google의 agents-cli를 그냥 “ADK 프로젝트를 만들어주는 CLI” 정도로 보면 핵심을 놓친다. 이 저장소가 흥미로운 이유는 CLI 자체보다, 코딩 에이전트에게 에이전트 개발 생애주기를 가르치는 패키지라는 점에 있다.

GitHub Trending에서 2026년 7월 1일 기준 새로 강하게 떠오른 google/agents-cli는 README에서 스스로를 “Gemini Enterprise Agent Platform에서 에이전트를 만들기 위한 CLI와 스킬”이라고 설명한다. 더 직접적으로는 “좋아하는 코딩 에이전트를 Google Cloud 위에서 엔터프라이즈급 에이전트를 만들고, 확장하고, 거버넌스하고, 최적화하는 전문가로 바꾼다”고 말한다.

이 문장은 과장이 섞인 마케팅처럼 보이지만, 최근 릴리스 노트와 문서를 같이 보면 꽤 명확한 방향이 보인다. Google은 ADK 2.0, Agent Runtime, 평가, 배포, 관측, Gemini Enterprise 등록을 하나의 반복 루프로 묶고 있다. 즉 모델이 좋아지는 이야기가 아니라, 에이전트 앱을 제품처럼 운영하기 위한 개발 라인에 가깝다.

기준 시점: 이 글은 2026-07-01에 확인한 google/agents-cli README, RELEASE_NOTES, gemini-extension.json, ADK README, Google Cloud Agent Platform 문서를 기준으로 썼다.

핵심 논점: 이제 에이전트 개발의 병목은 “프롬프트”가 아니라 운영 루프다

지난 1년 동안 AI 에이전트 논의는 대체로 세 갈래였다. 첫째, 모델이 얼마나 긴 작업을 버티는가. 둘째, 툴 콜링이 얼마나 안정적인가. 셋째, 브라우저·터미널·코드베이스 같은 실행 환경을 얼마나 잘 다루는가.

그런데 실제 팀이 부딪히는 문제는 조금 다르다.

• 이 에이전트가 어떤 도구를 써도 되는지 명세가 있는가?
• 실패 케이스를 배포 전에 잡을 평가 데이터셋이 있는가?
• 배포 타깃이 Agent Runtime인지 Cloud Run인지 GKE인지 팀이 합의했는가?
• 운영 중 trace와 로그가 남고, 다음 eval 데이터로 되돌아오는가?
• 다른 팀이나 다른 에이전트가 이 에이전트를 찾아 호출할 수 있는가?

agents-cli가 건드리는 지점은 여기다. README의 명령 목록은 setup, scaffold, eval generate, eval grade, deploy, publish gemini-enterprise, update로 이어진다. 단순히 “코드를 만들어준다”가 아니라, 스펙 → 프로젝트 구조 → 평가 → 배포 → 등록 → 관측을 반복시키는 구조다.

agents-cli는 CLI이면서 동시에 스킬 번들이다

google/agents-cli의 gemini-extension.json은 이 프로젝트를 “Google ADK로 AI 에이전트를 스캐폴드, 개발, 평가, 배포하는 도구”이며 “에이전트 개발 생애주기를 위한 7개 스킬을 번들로 제공한다”고 설명한다. README에도 비슷한 구조가 나온다.

핵심 스킬은 대략 이렇게 나뉜다.

여기서 중요한 건 agents-cli가 사람을 위한 CLI만이 아니라는 점이다. README는 Antigravity CLI, Claude Code, Codex, “any other coding agent”와 함께 쓸 수 있다고 적는다. 다시 말해 Google은 특정 코딩 에이전트 하나를 밀기보다, 어떤 코딩 에이전트든 Google Cloud의 에이전트 운영 방식에 맞춰 움직이게 하는 지식 패키지를 내놓은 셈이다.

이 접근은 꽤 현실적이다. 팀마다 쓰는 코딩 에이전트는 다르다. 어떤 팀은 Claude Code를 쓰고, 어떤 팀은 Codex를 쓰고, 어떤 팀은 사내 에이전트를 쓴다. 플랫폼 입장에서는 모든 사용자를 하나의 에이전트 UI로 끌고 오기보다, 그 에이전트들이 공통의 배포·평가·관측 규칙을 따르게 만드는 편이 더 유리하다.

최근 릴리스의 방향: Agent Runtime과 ADK 등록을 더 강하게 묶는다

가장 신선한 신호는 2026-06-28의 0.6.1 릴리스다. 릴리스 노트에 따르면 publish gemini-enterprise는 이제 Agent Runtime 배포를 기본적으로 ADK 방식으로 등록한다. Gemini Enterprise가 이를 더 안정적으로 네이티브 호출할 수 있게 하기 위한 변화다. Cloud Run과 GKE에서는 A2A 등록이 기본으로 남지만, Agent Runtime에서 A2A를 요청하면 경고하고 ADK를 추천한다.

이건 작은 구현 변경처럼 보이지만, 제품 방향을 보여준다.

1. Agent Runtime은 단순 호스팅이 아니라 플랫폼 네이티브 런타임으로 밀고 있다.
2. Gemini Enterprise에서 호출 가능한 에이전트는 등록 방식까지 표준화하려 한다.
3. Cloud Run/GKE는 범용 컨테이너 배포 경로로 남기되, Agent Runtime에는 더 강한 플랫폼 통합을 준다.

6월 23일의 0.6.0도 같은 방향이다. 릴리스 노트는 Agent Runtime 배포가 ADK web, A2A, reasoning engine을 “single unified container app”으로 제공한다고 적는다. 동시에 Cloud Trace spans가 LLM prompt와 response를 캡처하지 않도록 바뀌었다. 즉 런타임 통합과 프라이버시/관측 경계를 같이 다듬고 있다.

이런 변화는 한국 개발팀에도 의미가 있다. 많은 팀이 “에이전트 하나 만들어서 Cloud Run에 올리면 끝”이라고 생각하지만, 엔터프라이즈 환경에서는 호출 표준, 권한, 추적, 재배포, 등록, 감사가 같이 붙는다. agents-cli는 그 복잡도를 명령과 스킬로 감추려는 시도다.

평가가 앞에 온다: eval generate와 eval grade가 제품화의 출발점

에이전트가 데모에서 제품으로 넘어갈 때 가장 먼저 깨지는 것은 “그럴듯한 답변”이다. 한두 번 잘 되는 프롬프트는 많다. 문제는 반복 실행, 멀티턴 도구 사용, 예외 상황, 비용, 지연시간, 잘못된 도구 선택이다.

agents-cli 문서의 평가 가이드는 이 지점을 정면으로 다룬다. 기본 흐름은 단순하다.

agents-cli eval generate
agents-cli eval grade

generate는 평가 데이터셋에 대해 에이전트를 실행하고 trace를 만든다. grade는 그 trace를 metric으로 평가한다. 문서에 언급된 대표 metric은 general_quality, instruction_following, tool_use_quality, multi_turn_tool_use_quality, multi_turn_trajectory_quality, multi_turn_task_success, hallucination, grounding, safety 등이다.

이 목록이 중요한 이유는 평가가 더 이상 “답이 맞았나?”로 끝나지 않기 때문이다. 에이전트 제품에서는 최종 답만큼이나 중간 궤적이 중요하다.

• 올바른 도구를 골랐는가?
• 불필요한 도구 호출을 반복하지 않았는가?
• 멀티턴에서 목적을 잃지 않았는가?
• RAG 문맥을 벗어난 주장을 하지 않았는가?
• 안전 정책을 위반하지 않았는가?

특히 운영자 입장에서는 multi_turn_trajectory_quality 같은 지표가 중요하다. 최종 답이 우연히 맞더라도, 경로가 비효율적이면 비용과 지연시간이 폭발한다. 반대로 답은 틀렸지만 trace가 잘 남아 있으면, 어느 도구 설명을 고쳐야 하는지 알 수 있다.

ADK 2.0과 맞물리면 “코드 프레임워크”보다 “작업 그래프”에 가까워진다

agents-cli는 ADK 위에 올라간다. 그래서 ADK 2.0의 변화도 같이 봐야 한다. google/adk-python README는 ADK 2.0의 핵심으로 두 가지를 내세운다.

• Workflow Runtime: routing, fan-out/fan-in, loop, retry, state management, dynamic node, human-in-the-loop, nested workflow를 다루는 graph 기반 실행 엔진
• Task API: multi-turn task mode, controlled output, delegation pattern, human-in-the-loop, task agent를 workflow node로 쓰는 구조

이 변화는 “에이전트 = 프롬프트 + 도구 목록”이라는 초반식 정의에서 멀어진다. 실제 업무 에이전트는 대부분 그래프다. 예를 들어 장애 대응 에이전트라면 로그 조회, 메트릭 확인, 런북 검색, 위험 판단, 사람 승인, 조치 실행, 보고서 작성이 순차·분기·반복으로 엮인다.

agents-cli의 생애주기 문서도 이 방향과 맞다. 스펙을 쓰고, 스캐폴드하고, 빌드하고, 오케스트레이션하고, 평가하고, 배포하고, 게시하고, 관측하는 8단계 루프를 제시한다. 즉 ADK가 작업 그래프를 표현하는 프레임워크라면, agents-cli는 그 그래프를 제품으로 굴리는 외곽 공정에 가깝다.

배포 타깃 선택이 전략이다: Agent Runtime, Cloud Run, GKE

agents-cli의 배포 가이드는 세 가지 타깃을 분리한다.

릴리스 노트에서 Agent Runtime 쪽 변경이 집중되는 것도 우연이 아니다. Agent Runtime은 Google이 에이전트 플랫폼의 네이티브 경로로 밀고 있는 타깃이다. 반면 Cloud Run과 GKE는 더 범용적이고, 기존 클라우드 운영 체계와 잘 맞는다.

한국 팀에서 실무적으로는 이렇게 나누는 편이 좋다.

• 빠르게 Agent Platform 기능을 검증하고 싶다면 Agent Runtime을 먼저 본다.
• 이미 Cloud Run 중심으로 배포·IAM·로그·비용 체계가 잡혀 있다면 Cloud Run을 선택한다.
• 사내 표준이 GKE이고 네트워크/보안 정책이 Kubernetes 단위로 강하게 묶여 있다면 GKE가 맞다.

중요한 건 “어디에 올릴 수 있나”보다 “평가·관측·등록 루프가 깨지지 않는가”다. 에이전트는 한번 배포하고 끝나는 API 서버보다 훨씬 더 자주 조정된다. 배포 타깃은 그 반복 속도를 견뎌야 한다.

관측은 선택 기능이 아니라 다음 평가 데이터의 원천이다

agents-cli 관측 문서는 Cloud Trace, prompt-response logging, BigQuery Agent Analytics 같은 계층을 나눈다. 기본적으로 Cloud Trace는 실행 흐름, 지연시간, 에러를 span으로 보여준다. 더 강한 감사나 분석이 필요하면 prompt-response logging이나 BigQuery 분석 계층을 붙인다.

여기서 흥미로운 점은 0.6.0 릴리스에서 Cloud Trace spans가 LLM prompt와 response를 캡처하지 않도록 바뀌었다는 사실이다. 관측은 필요하지만, 프롬프트와 응답 본문이 무조건 trace에 남는 것은 기업 환경에서 위험하다. 특히 고객 데이터, 내부 문서, 보안 로그, 개인정보가 섞인 에이전트라면 trace 설계가 제품 리스크가 된다.

좋은 에이전트 운영은 모든 것을 기록하는 게 아니다. 문제를 재현할 만큼 충분히 남기되, 민감한 내용을 불필요하게 퍼뜨리지 않는 것이다. agents-cli가 이 경계를 문서와 릴리스에서 다루는 것은 꽤 좋은 신호다.

실무 해석: Google은 “에이전트 앱스토어”보다 먼저 “에이전트 생산 라인”을 만들고 있다

Gemini Enterprise에 에이전트를 등록한다는 말만 보면 내부 에이전트 마켓플레이스처럼 들린다. 하지만 agents-cli의 더 큰 의미는 그 앞단에 있다. 등록 가능한 에이전트를 만들려면, 먼저 스펙, 평가, 배포, 관측이 있어야 한다.

즉 순서는 이렇다.

1. 에이전트를 만든다.
2. 평가 데이터셋으로 실패를 잡는다.
3. 선택한 런타임에 배포한다.
4. Gemini Enterprise에 등록한다.
5. 운영 trace와 로그를 본다.
6. 그 데이터를 다음 eval과 수정으로 돌린다.

이 루프가 없으면 에이전트 카탈로그는 금방 데모 모음이 된다. 누가 만들었는지, 어떤 권한을 쓰는지, 어떤 실패 모드가 있는지, 어떤 버전이 배포됐는지 모르는 에이전트가 늘어나는 것이다.

agents-cli가 흥미로운 이유는 이 문제를 “관리자 콘솔”이 아니라 “코딩 에이전트가 읽는 스킬과 CLI”로 풀려고 한다는 점이다. 앞으로 에이전트 개발의 상당 부분을 또 다른 에이전트가 수행한다면, 운영 규칙도 사람 문서가 아니라 에이전트가 실행 가능한 형태로 배포돼야 한다.

한국 개발팀이 바로 가져갈 만한 체크리스트

agents-cli를 당장 도입하지 않더라도, 이 릴리스가 보여주는 운영 원칙은 가져갈 만하다.

1) 먼저 .agents-cli-spec.md 같은 스펙 파일을 둔다

에이전트의 목적, 도구, 제약, 성공 기준을 한 화면 안에 쓴다. 코딩 에이전트에게 바로 “구현해줘”라고 하지 말고, 스펙을 먼저 만들게 한다. 이 파일이 없으면 다음 주에 프롬프트와 도구가 왜 이렇게 되었는지 아무도 설명하지 못한다.

2) 배포 전에 최소 5~10개의 평가 케이스를 만든다

처음부터 거대한 벤치마크를 만들 필요는 없다. 가장 중요한 정상 케이스 2개, 실패 케이스 2개, 권한/보안 케이스 1개만 있어도 데모와 제품의 차이가 난다. 이후 운영 trace에서 자주 나온 실패를 eval 데이터셋으로 승격하면 된다.

3) tool-use 품질을 별도 지표로 본다

에이전트의 최종 답만 보지 말고, 어떤 도구를 어떤 순서로 호출했는지 본다. 특히 비용이 비싼 검색, 브라우저, 코드 실행, 배포 도구는 경로 품질이 곧 비용과 리스크다.

4) 런타임을 기술 취향이 아니라 운영 루프로 고른다

Agent Runtime, Cloud Run, GKE 중 무엇이 더 멋진지가 아니다. 우리 팀의 IAM, 네트워크, CI/CD, 로그, 비용 모니터링, 장애 대응과 잘 맞는지를 봐야 한다. 에이전트는 상태와 도구 권한을 가진 소프트웨어이므로, 일반 API보다 운영 면적이 넓다.

5) trace에 민감정보가 남는지 먼저 확인한다

관측은 필수지만, 무조건적인 prompt/response 로깅은 위험하다. 에이전트가 고객 데이터나 내부 문서를 다룬다면 trace, 로그, BigQuery export, 외부 관측 도구로 무엇이 나가는지 먼저 검토해야 한다.

결론: agents-cli의 본질은 “Google판 에이전트 CLI”가 아니라 에이전트 운영 규칙의 배포다

google/agents-cli는 아직 빠르게 움직이는 프로젝트다. 6월 한 달만 봐도 ADK 2.0 템플릿, eval 흐름, Agent Runtime 배포, Cloud Trace 정책, Gemini Enterprise 등록 방식이 계속 바뀌었다. 그래서 지금 당장 모든 팀의 표준이라고 말하기는 이르다.

하지만 방향은 분명하다. 에이전트 개발은 더 이상 “좋은 프롬프트를 쓰고 툴을 붙이는 일”로 끝나지 않는다. 스펙, 평가, 배포, 등록, 관측, 개선이 하나의 루프로 묶여야 한다. Google은 이 루프를 사람이 읽는 문서가 아니라, 코딩 에이전트가 실행할 수 있는 CLI와 스킬 묶음으로 배포하고 있다.

한국의 개발자와 기술 운영자에게 이 신호는 꽤 실용적이다. 앞으로 에이전트 프로젝트를 검토할 때 질문을 바꿔야 한다.

“이 에이전트가 똑똑한가?”보다 먼저 “이 에이전트를 반복적으로 평가하고 배포하고 관측할 수 있는가?”를 물어야 한다.

그 질문에 답하지 못하면, 아무리 멋진 데모도 제품이 되기 어렵다.

참고한 주요 출처

• google/agents-cli GitHub README
• google/agents-cli RELEASE_NOTES
• google/agents-cli gemini-extension.json
• Agents CLI documentation
• Google ADK Python README
• Gemini Enterprise Agent Platform — Agent Runtime / Scale documentation