Agen AI Vibe Coding: Mengelola Siklus Proses Agen dengan Agents CLI dan ADK 2.0

1. Ringkasan

Dalam codelab ini, Anda akan mempelajari cara menggunakan Agents CLI untuk mengelola siklus proses pengembangan lokal lengkap agen AI. Baik Anda membungkus model Gemini yang ada atau membuat agen kustom dari awal dengan Agent Development Kit (ADK 2.0), Agents CLI menyediakan alat untuk membuat struktur, membangun, melakukan linting, dan menguji agen Anda secara lokal.

Yang akan Anda pelajari

  • Cara menginstal dan menyiapkan agents-cli serta skill terkaitnya.
  • Cara membuat kerangka project agen baru.
  • Struktur dan file utama project agen alur kerja grafik ADK 2.0.
  • Cara menjalankan linting otomatis dan pembersihan kode.
  • Cara meluncurkan dan menggunakan playground web lokal untuk pengujian interaktif dengan pemuatan ulang otomatis.

Yang Anda perlukan

  • Python 3.11 atau yang lebih tinggi
  • Pengelola paket uv
  • Node.js 18+ (jika menggunakan keterampilan agen coding)
  • Antigravity IDE (instal dan konfigurasi dari Google Antigravity)

Prasyarat

Codelab ini mengasumsikan bahwa Anda sudah memahami:

  • Menggunakan terminal dan command line.

Anda tidak memerlukan pengalaman sebelumnya dengan agen AI atau ADK 2.0.

2. Menyiapkan Autentikasi & Lingkungan

Berikan kredensial autentikasi Anda agar agen dapat memanggil model Gemini.

Opsi 1: Kunci Gemini API (Google AI Studio)

Jika Anda menggunakan kunci Gemini API standar (yang dapat Anda peroleh dari Google AI Studio), ekspor kunci tersebut di sesi terminal IDE Anda:

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

Opsi 2: Kredensial Default Aplikasi Google Cloud

Jika Anda menggunakan Vertex AI di Google Cloud, lakukan autentikasi dengan Kredensial Default Aplikasi (ADC) Google Cloud dan tetapkan project Google Cloud aktif Anda:

gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location

3. Menyiapkan CLI & Keterampilan Agen

Langkah pertama adalah menginstal alat agents-cli. Alat ini menangani tugas berat pengelolaan project agen.

Setelah Antigravity diinstal, jalankan perintah penyiapan langsung di terminal Anda.

👉 Buka terminal dan jalankan:

uvx google-agents-cli setup

Perintah ini akan otomatis menginstal:

  1. Alat Agents CLI secara global di sistem Anda.
  2. Tujuh keterampilan asisten coding khusus domain yang dapat digunakan Antigravity untuk membantu Anda membuat, menyusun, mengevaluasi, dan men-deploy agen. Keterampilan ini diinstal satu kali secara global ke ~/.agents/skills/ dan ditemukan secara otomatis oleh Antigravity.

Catatan: Keterampilan diinstal ke ~/.agents/skills/ dan diambil secara otomatis oleh Antigravity. Anda dapat memverifikasi hal ini menggunakan perintah /skills atau setelan Antigravity Anda.

Output yang Diharapkan (dipangkas):

█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`

`Your coding agent just got an upgrade.`

`1. Authentication`

`─────────────────`

`✓ Authenticated with Google Cloud`

`2. CLI Installation`

`───────────────────`

`▸ uv tool install google-agents-cli`

`✓ Installed google-agents-cli`

`3. Skills Installation`

`──────────────────────`

`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`

`◇ Found 7 skills`

`~/.agents/skills/google-agents-cli-adk-code`

`~/.agents/skills/google-agents-cli-deploy`

`~/.agents/skills/google-agents-cli-eval`

`~/.agents/skills/google-agents-cli-observability`

`~/.agents/skills/google-agents-cli-publish`

`~/.agents/skills/google-agents-cli-scaffold`

`~/.agents/skills/google-agents-cli-workflow`

4. Buat Project Agen Anda

Di bagian ini, Anda akan membuat direktori project yang terstruktur sepenuhnya menggunakan template prototipe.

👉 Perintah Antigravity:

Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.

Antigravity akan otomatis menjalankan perintah scaffolding (agents-cli scaffold create customer-support-agent --prototype --yes) dan menyiapkan file project untuk Anda.

5. Mempelajari Kode Agen

👉 Minta Antigravity menjelaskan kode yang dihasilkan:

Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.

Di Antigravity IDE, file dan artefak project yang baru dibuat ditampilkan langsung di panel tambahan (sisi kiri). Anda dapat melihat app/agent.py di sana, atau membukanya dari penjelajah file IDE untuk menjelajahi kode yang di-scaffold.

# app/agent.py

from __future__ import annotations

from typing import Any, Literal

from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field


class InquiryCategory(BaseModel):
  category: Literal['shipping', 'unrelated'] = Field(
      description=(
          'Determine if the user query is related to shipping (rates, tracking,'
          ' delivery times, returns) or unrelated.'
      )
  )


def save_query(node_input: str):
  """Saves user query in state for downstream nodes."""
  yield Event(data=node_input, state={'user_query': node_input})


categorize_agent = LlmAgent(
    name='categorize',
    model='gemini-3.1-flash-lite',
    instruction='You are an expert classifier. Categorize the user query.',
    output_key='inquiry_category',
    output_schema=InquiryCategory,
)


@node
def route_inquiry(ctx: Context, node_input: Any):
  """Routes the workflow based on the classified category."""
  category_data = ctx.state.get('inquiry_category', {})
  category = category_data.get('category', 'unrelated')
  query = ctx.state.get('user_query', '')
  yield Event(data=query, route=category)


faq_agent = LlmAgent(
    name='shipping_faq',
    model='gemini-3.1-flash-lite'',
    instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
    
    SHIPPING FAQ:
    - Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
      over $50 qualify for free standard shipping.
    - Tracking: You can track your order by entering your tracking number on
      our website's tracking page.
    - Delivery Times: Standard delivery takes 3-5 business days. Express
      delivery takes 1-2 business days.
    - Returns: We offer free returns within 30 days of delivery. Please make
      sure the item is in its original condition.
    """,
)


@node
def handle_unrelated(ctx: Context, node_input: Any):
  """Handles unrelated inquiries politely."""
  yield Event(
      data=(
          'I am sorry, I am a shipping customer support assistant and can only'
          ' answer questions related to our shipping FAQ.'
      )
  )


root_agent = Workflow(
    name='customer_support_workflow',
    edges=[
        *Edge.chain('START', save_query, categorize_agent, route_inquiry),
        (route_inquiry, faq_agent, 'shipping'),
        (route_inquiry, handle_unrelated, 'unrelated'),
    ],
)

app = App(
    name='customer_support_agent',
    root_agent=root_agent,
)

Konsep Utama

  • Alur Kerja & Edge: Di ADK 2.0, aplikasi agen diatur sebagai grafik menggunakan Workflow. Daftar edges menentukan alur eksekusi, menghubungkan node dari START dan memungkinkan percabangan bersyarat berdasarkan rute (misalnya, perutean ke faq_agent di "shipping" atau handle_unrelated di "unrelated").
  • LlmAgent: Node deklaratif yang menentukan tugas yang didukung LLM dengan petunjuk, model, dan output terstruktur tertentu (output_schema).
  • Node & Konteks: Fungsi Python yang dihiasi dengan @node (atau fungsi standar) yang melakukan logika, mengakses status eksekusi melalui Context, dan menghasilkan objek Event untuk meneruskan data dan sinyal perutean di sepanjang grafik.
  • Model: `gemini-3.1-flash-lite' digunakan sebagai model penalaran cepat default.
  • Wrapper Aplikasi: Objek App tingkat teratas membungkus alur kerja root. Alat eksternal seperti playground lokal, alat evaluasi ADK, dan Agent Runtime menemukan serta menjalankan alur kerja Anda melalui antarmuka app standar ini.

6. Linting Otomatis

Sebelum menjalankan atau menguji agen, sebaiknya pastikan kode Anda bersih dan diformat dengan benar.

👉 Perintah Antigravity:

Run linting on my agent project to verify its health.

Antigravity akan menjalankan agents-cli lint di balik layar untuk menjalankan pemeriksaan yang telah dikonfigurasi sebelumnya, memverifikasi impor, sintaksis, dan konsistensi pemformatan di seluruh file Anda.

7. Pengujian Interaktif dengan Playground

Playground web lokal adalah cara tercepat untuk memverifikasi perilaku agen Anda. Panel ini menyediakan antarmuka chat interaktif tempat Anda dapat melakukan chat dengan agen dan memeriksa eksekusi alat secara real-time.

👉 Perintah Antigravity:

Launch the local development playground for my agent.

Antigravity akan memulai server pengembangan lokal (agents-cli playground). Buka URL yang diberikan (biasanya http://127.0.0.1:8080/dev-ui/?app=app) di browser web Anda, pilih folder app dari dropdown untuk mulai melakukan percakapan dengan agen Anda.

Mulai chat dengan agen Anda di antarmuka web. Coba ajukan pertanyaan terkait pengiriman:

How much is standard shipping?

Perhatikan bagaimana alur kerja berhasil mengategorikan dan mengarahkan ke faq_agent untuk menjawab. Coba juga ajukan pertanyaan yang tidak terkait untuk memverifikasi bahwa alur kerja diarahkan ke handle_unrelated dan menolak untuk menjawab dengan benar:

What is the weather like?

Menguji Isi Ulang Otomatis Real-Time

Anda dapat melihat bagaimana pengeditan real-time pada agen Anda tercermin di Playground.

  1. Ubah petunjuk faq_agent di app/agent.py dengan bertanya kepada Antigravity: 
    Modify the faq_agent instruction in app/agent.py to make the shipping rates
response more playful and enthusiastic. Add some emojis and highlight the
free shipping threshold.
  2. Kirim pesan baru ke agen di playground untuk menguji pemuatan ulang otomatis: 
    How much is standard shipping?
    Playground akan otomatis memuat ulang dan mengeksekusi kode yang telah diupdate secara real-time tanpa perlu memulai ulang server. Sekarang Anda akan melihat beberapa emoji dalam respons.

8. Eksekusi Command Line

Untuk pengujian cepat, otomatisasi, atau pembuatan skrip, Anda dapat meminta Antigravity untuk menjalankan agen Anda langsung dari terminal.

👉 Perintah Antigravity:

Run a CLI query asking my agent how long standard delivery takes.

Antigravity akan menjalankan perintah kueri (agents-cli run "How long does standard delivery take?"). Perintah ini menjalankan inferensi satu giliran yang cepat dan mencetak respons akhir agen beserta detail eksekusi alat.

9. Pembersihan

Untuk menghindari resource yang tidak diinginkan di lingkungan lokal Anda, ikuti langkah-langkah pembersihan berikut:

  1. Hentikan Server Lokal: Jika server agents-cli playground Anda masih berjalan, hentikan di terminal dengan menekan Ctrl + C.
  2. Hapus File Project Lokal: Hapus direktori project agen yang di-scaffold dari mesin lokal Anda.
rm -rf customer-support-agent

10. Ringkasan & Langkah Selanjutnya

Selamat! Anda telah berhasil mengelola siklus proses pengembangan lokal end-to-end agen AI menggunakan CLI Agen dan ADK 2.0.

Yang telah Anda pelajari

  • Siapkan Alat Anda: Menginstal Agents CLI dan mengonfigurasi keterampilan alur kerja khusus domain untuk Antigravity.
  • Membuat Struktur Project: Membuat project customer-support-agent yang terstruktur sepenuhnya menggunakan template standar.
  • Menganalisis Struktur ADK 2.0: Menjelajahi alur kerja grafik, agen LLM, node, tepi, dan perutean bersyarat.
  • Managed Local Health: Menjalankan pemeriksaan kualitas kode otomatis menggunakan agents-cli lint.
  • Perilaku Terverifikasi: Menguji agen secara interaktif dengan hot-reloading real-time melalui playground, dan menjalankan pengujian cepat di command line.

Apa Langkah Selanjutnya?

Setelah menguasai loop pengembangan lokal, berikut cara memperluas dan memproduksi agen Anda:

  • Evaluasi: Beri skor pada agen Anda terhadap evalset menggunakan agents-cli eval run untuk mengukur akurasi dan menemukan regresi.
  • Skala Cloud untuk Perusahaan: Deployment & Kemampuan Observasi: Kemas dan deploy agen Anda ke lingkungan produksi seperti Agent Runtime atau Cloud Run menggunakan agents-cli deploy. Siapkan telemetri produksi untuk melakukan streaming log dan rekaman aktivitas eksekusi ke Cloud Trace dan BigQuery.

Referensi Tambahan