모듈 5: agents-cli를 사용하여 ADK 에이전트 구축하기¶

📖 출처: agents-cli GitHub · agents-cli 문서 · ADK · PyPI

agents-cli란 무엇인가요?¶

agents-cli는 코딩 에이전트가 아닙니다. 이것은 코딩 에이전트를 위한 툴킷입니다. Antigravity CLI 세션에 Google Cloud에서 ADK (Agent Development Kit) 에이전트를 빌드, 평가 및 배포할 수 있는 스킬과 명령어를 제공합니다.

이렇게 생각해 보세요. agy가 여러분의 손이라면, agents-cli는 전동 공구입니다.

5.1 — 설정 10분¶

사전 요구 사항¶

• Python 3.11+
• uv (Python 패키지 관리자)
• Node.js (스킬 설치용)
• Google Cloud 프로젝트 또는 AI Studio API 키

agents-cli 설치¶

uvx google-agents-cli setup

이 작업은 다음 세 가지를 수행합니다:

1. agents-cli 바이너리 설치
2. 코딩 에이전트(Antigravity CLI, Gemini CLI, Claude Code)에 7개의 스킬 설치
3. 인증 구성

확인¶

agents-cli info

5.2 — 7단계 수명 주기 10분¶

agents-cli는 구조화된 개발 수명 주기를 강제합니다. 각 단계에는 코딩 에이전트가 해당 단계에 도달했을 때 로드하는 전용 스킬이 있습니다:

graph LR
    P0[Phase 0<br/>Understand] --> P1[Phase 1<br/>Study Samples]
    P1 --> P2[Phase 2<br/>Scaffold]
    P2 --> P3[Phase 3<br/>Build]
    P3 --> P4[Phase 4<br/>Evaluate]
    P4 --> P5[Phase 5<br/>Deploy]
    P5 --> P6[Phase 6<br/>Publish]
    P6 --> P7[Phase 7<br/>Observe]
    P4 -.->|fix & iterate| P3

핵심 인사이트: 4단계(평가)가 가장 중요합니다. 평가-수정 루프를 5~10회 이상 반복할 것으로 예상하십시오. 이는 정상적인 과정이며 에이전트의 품질은 여기서 비롯됩니다.

5.3 — 프로젝트 스캐폴딩 10 min¶

프로토타입 우선 패턴¶

항상 --prototype으로 시작하여 CI/CD 및 Terraform을 건너뛰세요. 에이전트가 작동하도록 한 다음, 나중에 배포를 추가하세요:

# Step 1: Create a prototype
agents-cli scaffold create my-agent --agent adk --prototype

# Step 2: Iterate on agent code...

# Step 3: Add deployment when ready
agents-cli scaffold enhance . --deployment-target agent_runtime

템플릿 옵션¶

배포 대상¶

스캐폴드가 생성하는 것¶

my-agent/
├── app/
│   ├── __init__.py          ← App entry point (name must match directory)
│   ├── agent.py             ← Agent definition (instruction, tools, model)
│   └── tools.py             ← Custom tool functions
├── tests/
│   └── eval/
│       ├── datasets/
│       │   └── basic-dataset.json  ← Starter eval cases
│       └── eval_config.yaml        ← Metrics configuration
├── .env                     ← Environment variables (project ID, API keys)
├── agents-cli-manifest.yaml ← Project metadata (CLI reads this)
├── pyproject.toml           ← Python dependencies
├── GEMINI.md                ← Coding agent guidance file
└── Makefile                 ← Common task shortcuts

5.4 — 에이전트 코드 빌드 15분¶

에이전트 정의 패턴¶

스캐폴딩된 app/agent.py가 시작점입니다:

from google.adk import Agent

root_agent = Agent(
    name="my_agent",
    model="gemini-3.5-flash",
    instruction="""You are a helpful assistant that...""",
    tools=[my_tool_function],
)

도구 정의¶

도구는 타입이 지정된 매개변수와 독스트링(docstring)이 있는 일반 Python 함수입니다:

def get_weather(city: str) -> dict:
    """Get current weather for a city.

    Args:
        city: The city name to look up weather for.

    Returns:
        A dict with temperature and conditions.
    """
    # Your implementation here
    return {"temp_f": 72, "conditions": "sunny"}

빠른 테스트¶

# One-off smoke test
agents-cli run "What's the weather in Tokyo?"

# Interactive playground (web UI)
agents-cli playground

5.5 — 평가 루프 20분¶

이것은 가장 중요한 섹션입니다. 평가는 데모와 프로덕션 에이전트를 구분하는 기준입니다.

품질 플라이휠¶

┌─ 1. Prepare Data ─────── Write eval cases or synthesize them
│
├─ 2. Run Inference ────── agents-cli eval generate
│
├─ 3. Grade Traces ─────── agents-cli eval grade
│
├─ 4. Analyze Failures ──── Read results, identify root causes
│
└─ 5. Fix & Iterate ────── Fix agent code, go back to step 2

평가 데이터셋 형식¶

평가 케이스는 프롬프트와 선택적인 예상 동작이 포함된 JSON 파일입니다:

{
  "eval_cases": [
    {
      "eval_case_id": "greeting",
      "prompt": {
        "role": "user",
        "parts": [{"text": "Hello, what can you help me with?"}]
      }
    },
    {
      "eval_case_id": "weather_query",
      "prompt": {
        "role": "user",
        "parts": [{"text": "What's the weather in San Francisco?"}]
      }
    }
  ]
}

내장 메트릭¶

평가 실행¶

# One command: generate traces + grade them
agents-cli eval run

# Or two-step for more control
agents-cli eval generate
agents-cli eval grade

# Compare before/after a fix
agents-cli eval compare baseline.json candidate.json

점수가 낮을 때¶

사용자 정의 메트릭¶

내장 메트릭이 도메인을 포괄하지 못하는 경우, eval_config.yaml에 사용자 정의 메트릭을 정의하세요:

metrics_to_run:
  - multi_turn_task_success
  - response_politeness    # custom metric below

custom_metrics:
  - name: response_politeness
    prompt_template: |
      Rate the agent's response 1-5 for professional politeness.
      Prompt: {prompt}
      Response: {response}
      Return JSON: {"score": <1|2|3|4|5>, "explanation": "<reason>"}

5.6 — 배포 10분¶

평가를 통과하면 배포를 추가하고 출시합니다:

# Add deployment support (if prototype)
agents-cli scaffold enhance . --deployment-target agent_runtime

# Deploy
agents-cli deploy

CI/CD 추가¶

# GitHub Actions
agents-cli scaffold enhance . --cicd-runner github_actions

# Google Cloud Build
agents-cli scaffold enhance . --cicd-runner google_cloud_build

배포 대상 결정 매트릭스¶

5.7 — Antigravity CLI에서 agents-cli 사용하기 5분¶

진정한 강력함은 agy와 agents-cli를 결합할 때 나타납니다. Antigravity CLI 세션에서:

> Use agents-cli to scaffold an ADK agent called "expense-tracker"
  that processes receipts and categorizes expenses.
  Start with a prototype.

agy는 다음을 수행합니다:

1. google-agents-cli-workflow 스킬 로드
2. 명확한 이해를 위한 질문하기 (0단계)
3. 일치하는 adk-samples 확인 (1단계)
4. agents-cli scaffold create expense-tracker --agent adk --prototype 실행
5. ADK 패턴을 사용하여 에이전트 코드 구현 (3단계)
6. 평가(eval) 케이스 설정 및 실행 (4단계)
7. 품질 임계값을 통과할 때까지 반복

사용자는 상위 수준의 의도를 안내하고, agents-cli 스킬이 구현 세부 사항을 처리합니다.

스킬 참조¶

agents-cli setup으로 설치되는 7가지 스킬:

연습 문제¶

다음: 여러 에이전트 오케스트레이션, 서브에이전트 패턴 및 /btw 스케줄링 시스템을 위한 모듈 4 — 다중 에이전트 및 고급.