개요
커맨드라인 도구와 스킬 세트로, 모든 프로그래밍 어시스턴트를 Google Cloud에서 AI 에이전트를 생성, 평가 및 배포하는 전문가로 만들어줍니다. 스캐폴딩, 평가, 배포, 관측 가능성 등의 명령어를 제공하며 ADK 프레임워크와 통합됩니다.
README 미리보기
\n \n agents-cli\n The CLI and skills for building agents on Gemini Enterprise Agent Platform.\n\n \n Get Started | \n Skills | \n Commands | \n PyPI | \n Issues | \n Docs | \n Release Notes | \n Star us\n \n\n\n---\n\nTurn your favorite coding assistant into an expert at building and deploying agents on Google Cloud.\n\n**Agents CLI in Agent Platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.\n\n**Works seamlessly with:**\n[Antigravity CLI](https://antigravity.google/) • [Claude Code](https://docs.anthropic.com/en/docs/claude-code) • [Codex](https://github.com/openai/codex) • *and any other coding agent.*\n\n## Get Started\n\n**Prerequisites:** Python 3.11+, [uv](https://docs.astral.sh/uv/getting-started/installation/), and [Node.js](https://nodejs.org/en/download).\n\n### 1. Install\n\n```bash\nuvx google-agents-cli setup\n```\n\n\nOr just the skills — your coding agent will handle the rest\n\n```bash\nnpx skills add google/agents-cli\n```\n\n\n\n### 2. Open your coding agent\n\nLaunch [Antigravity CLI](https://antigravity.google/), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or any coding agent you prefer.\n\n### 3. Build your first agent\n\nAsk your coding agent to build something — e.g. *"Use agents-cli to build a caveman-style agent that compresses verbose text into terse, technical grunts"*\n\nSee the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tutorial/) for a step-by-step walkthrough.\n\n**[Browse the full documentation →](https://google.github.io/agents-cli/)**\n\n---\n\n## Agent Skills\n\n| Skill | What you
FAQ (5)
문제 해결Windows에서 agents-cli setup 또는 기타 명령을 실행할 때 PermissionError [WinError 5] Access denied 오류가 발생하는 경우 어떻게 해결하나요?
이 문제는 uv.exe와 같은 도구가 디스크에서 발견되지만 AppLocker, Defender 또는 NTFS 권한 정책 때문에 Windows가 실행을 차단하는 경우, agents-cli 1.9.0 이전 버전에서 발생합니다. shutil.which()는 Windows에서 실행 파일을 실제로 실행할 수 있는지 확인하지 않고 찾아내며, 이전 subprocess 헬퍼는 그 결과 발생하는 PermissionError를 처리하지 못했습니다.
agents-cli를 1.9.0 이상으로 업그레이드하여 해결하세요:
python -m pip install --upgrade agents-cli설치를 확인하세요:
agents-cli info업그레이드 후에는 CLI가 원시 Python traceback 대신 깔끔한 도구 확인 오류를 보고합니다. 명령이 성공하려면 uv.exe가 실행되도록 허용되어 있는지도 확인해야 합니다:
uv --version그래도 "Access is denied"가 반환되면 IT 관리자에게 AppLocker/Defender에서 uv.exe를 허용하도록 요청하거나, 허용된 위치에 uv를 다시 설치하거나, uv가 차단되지 않은 환경에서 CLI를 실행하세요. 동일한 subprocess runner를 공유하므로 setup, lint, login, deploy, publish 및 scaffold 명령에도 같은 문제가 영향을 줄 수 있습니다.
문제 해결setup을 실행한 후에도 agents-cli info에 "Installed skills: none"이 표시되는 이유는 무엇인가요?
이것은 agents-cli v1.9.0의 버그로, agents-cli info가 -g 플래그 없이 npx skills list --json을 실행하기 때문에 프로젝트 범위의 스킬만 감지하고 전역으로 설치된 스킬(agents-cli setup에 의해 ~/.agents/skills/에 설치된)을 누락합니다. 스킬은 실제로는 올바르게 설치되어 있습니다 — ls ~/.agents/skills/google-agents-cli-*/SKILL.md 또는 npx -y skills list -g --json으로 확인할 수 있습니다. 이 버그는 v1.12.0에서 수정되었으므로 CLI를 업그레이드하세요: uv tool install google-agents-cli --upgrade (또는 uvx google-agents-cli@latest setup을 다시 실행하세요).
문제 해결Agent Runtime 배포 가이드와 관찰성 가이드에서 배포 전에 agents-cli infra single-project를 실행하는 것에 대해 서로 상충하는 지침을 제공하는 이유는 무엇인가요?
이 모순은 agents-cli v1.8.0에서 수정된 문서 버그였습니다. 다음 순서 규칙을 따르세요:
- **Basic Agent Runtime / Cloud Run:** 바로 배포하세요. 먼저 infra single-project를 실행하지 마세요.
- **GKE:** 배포를 정상적으로 실행하세요. 배포 프로세스가 필요한 대상 Terraform 작업을 수행합니다.
- **Terraform으로 관리되는 옵저버빌리티, 모든 대상:** 첫 번째 배포 전에 agents-cli infra single-project --apply를 실행하세요.
- **기존 명령형 배포:** 소유권을 전환하기 전에 기존 리소스를 먼저 가져오거나 삭제하지 않는 한, 이후에 Terraform을 적용하지 마세요. 그렇지 않으면 명령형 소유권을 유지하고 옵저버빌리티를 수동으로 구성하세요.
명령형 Agent Runtime 배포 후 Terraform을 적용하면 두 번째 Runtime이 생성되거나 두 번째 Runtime이 대상으로 지정될 수 있습니다. 수정된 README, 마이그레이션 가이드 및 스킬 문서를 확인하려면 v1.8.0 이상으로 업그레이드하세요.
문제 해결동시에 실행되는 `agents-cli deploy --no-wait` 프로세스가 서로의 대기 중인 Agent Runtime 작업을 덮어쓰지 않도록 하려면 어떻게 해야 하나요?
고유한 owner ID로 deployment_metadata.json을 원자적으로 점유하고, Runtime 재검증 및 원격 제출 중에 프로세스 간 잠금을 유지하며, cleanup/finish 작업이 소유자를 인식하도록 하여 v1.3.1 race를 수정한 **agents-cli v1.8.0 이상**으로 업그레이드하세요.
python -m pip install --upgrade agents-cli==1.8.0즉시 업그레이드할 수 없는 경우에는 에이전트 프로젝트당 하나의 CLI 프로세스만 실행되도록 배포를 직렬화하세요:
flock -n /tmp/my-agent-deploy.lock agents-cli deploy --no-waitCI에서 병렬 배포 작업을 실행하지 마세요. 원격 제출 후 결과를 알 수 없는 상태로 프로세스가 실패하면, 메타데이터를 지우지 말고 작업을 fail-closed state=starting 상태로 유지한 채 수동으로 조정하세요.
문제 해결agents-cli가 원격 Git 템플릿에서 스캐폴딩할 때 심볼릭 링크된 공유 파일을 누락시켜 ImportError를 발생시키는 이유는 무엇인가요?
이는 agents-cli 1.4.1–1.5.0에서 발생한 회귀(regression)입니다: 원격 템플릿 스캐폴딩이 모든 심볼릭 링크를 보안 경고로 처리해 건너뛰면서도 여전히 성공으로 보고했기 때문에 app/shared -> ../../shared와 같은 디렉터리가 누락되었습니다. agents-cli 1.7.0 이상으로 업그레이드한 다음 스캐폴드 명령을 다시 실행하고, 예를 들어 demo/app/shared/config.py처럼 대상이 존재하는지 확인하세요. 업그레이드할 수 없는 경우 저장소 내부 심볼릭 링크를 물리적으로 복사된 디렉터리로 교체하고, 스크립트와 CI drift 검사로 동기화 상태를 유지하세요. local@ 테스트에만 의존하지 마세요: 이는 pre-copy 과정에서 심볼릭 링크를 역참조하므로 원격 템플릿 실패를 숨길 수 있습니다.