Modul 5: Membangun Agen ADK dengan agents-cli¶

📖 Sumber: GitHub agents-cli · Dokumentasi agents-cli · ADK · PyPI

Apa itu agents-cli?¶

agents-cli bukanlah agen pengodean. Ini adalah toolkit untuk agen pengodean — ini memberikan sesi Antigravity CLI Anda skill dan perintah untuk membangun, mengevaluasi, dan men-deploy agen ADK (Agent Development Kit) di Google Cloud.

Anggap saja seperti ini: agy adalah tangan Anda, agents-cli adalah perkakas mesinnya.

5.1 — Pengaturan 10 min¶

Prasyarat¶

• Python 3.11+
• uv (manajer paket Python)
• Node.js (untuk instalasi skill)
• Proyek Google Cloud atau kunci API AI Studio

Instal agents-cli¶

uvx google-agents-cli setup

Ini melakukan tiga hal:

1. Menginstal berkas biner agents-cli
2. Menginstal 7 skill ke dalam agen pengodean Anda (Antigravity CLI, Gemini CLI, Claude Code)
3. Mengonfigurasi autentikasi

Verifikasi¶

agents-cli info

5.2 — Siklus Hidup 7 Fase 10 menit¶

agents-cli menerapkan siklus hidup pengembangan yang terstruktur. Setiap fase memiliki skill khusus yang dimuat oleh agen pengodean Anda saat mencapai tahap tersebut:

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

Wawasan utama: Fase 4 (Evaluasi) adalah yang paling kritis. Perkirakan 5–10+ iterasi dari loop evaluasi-perbaikan. Hal ini normal dan dari sinilah kualitas agen berasal.

5.3 — Membangun Kerangka Proyek 10 min¶

Pola Mengutamakan Prototipe¶

Selalu mulai dengan --prototype untuk melewati CI/CD dan Terraform. Buat agen berfungsi terlebih dahulu, lalu tambahkan penerapan nanti:

# 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

Opsi Templat¶

Target Penerapan¶

Apa yang Dibuat oleh Kerangka¶

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 — Membangun Kode Agen 15 min¶

Pola Definisi Agen¶

app/agent.py yang telah di-scaffold adalah titik awal Anda:

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],
)

Definisi Alat¶

Alat adalah fungsi Python biasa dengan parameter bertipe dan docstring:

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"}

Pengujian Cepat¶

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

# Interactive playground (web UI)
agents-cli playground

5.5 — Loop Evaluasi 20 min¶

Ini adalah bagian yang paling penting. Evaluasi adalah apa yang membedakan sebuah demo dari agen produksi.

Flywheel Kualitas¶

┌─ 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

Format Dataset Evaluasi¶

Kasus evaluasi adalah file JSON dengan prompt dan perilaku yang diharapkan opsional:

{
  "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?"}]
      }
    }
  ]
}

Metrik Bawaan¶

Menjalankan Evaluasi¶

# 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

Ketika Skor Gagal¶

Metrik Kustom¶

Ketika metrik bawaan tidak mencakup domain Anda, tentukan metrik kustom di 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 — Deployment 10 min¶

Setelah evaluasi berhasil, tambahkan deployment dan rilis:

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

# Deploy
agents-cli deploy

Menambahkan CI/CD¶

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

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

Matriks Keputusan Target Deployment¶

5.7 — Menggunakan agents-cli dari Antigravity CLI 5 min¶

Kekuatan sebenarnya adalah menggabungkan agy + agents-cli. Dalam sesi Antigravity CLI:

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

agy akan:

1. Memuat skill google-agents-cli-workflow
2. Mengajukan pertanyaan klarifikasi kepada Anda (Fase 0)
3. Memeriksa kecocokan adk-samples (Fase 1)
4. Menjalankan agents-cli scaffold create expense-tracker --agent adk --prototype
5. Mengimplementasikan kode agen menggunakan pola ADK (Fase 3)
6. Menyiapkan kasus evaluasi dan menjalankannya (Fase 4)
7. Melakukan iterasi hingga ambang batas kualitas terpenuhi

Anda memandu niat tingkat tinggi; skill agents-cli menangani detail implementasi.

Referensi Skill¶

7 skill yang diinstal oleh agents-cli setup:

Latihan¶

Selanjutnya: Modul 4 — Multi-Agen & Lanjutan untuk mengorkestrasi beberapa agen, pola sub-agen, dan sistem penjadwalan /btw.