Memahami Google Agent Development Kit (ADK): Panduan Pemula hingga Menengah dengan Agents CLI

Ringkasan: Google Agent Development Kit (ADK) adalah framework open-source berbasis kode (code-first) dari Google (tersedia dalam Python, TypeScript, Go, dan Java) untuk membangun, mengevaluasi, dan men-deploy agen AI kelas produksi—mulai dari asisten single-agent sederhana hingga sistem multi-agent hierarkis. Dipadukan dengan Agents CLI (google-agents-cli), developer dapat membuat scaffold prototipe dalam hitungan detik (agents-cli scaffold create), menguji alur percakapan secara visual di browser (agents-cli playground), menjalankan evaluasi perilaku otomatis (agents-cli eval run), dan men-deploy ke Cloud Run atau Vertex AI Agent Engine dengan satu perintah. Panduan ini memandu Anda dari konsep dasar untuk pemula hingga orkestrasi multi-agent tingkat menengah—sekaligus memetakan bagaimana konsep state machine visual dari Dialogflow CX diterjemahkan langsung ke dalam kode Python.

---

1. Apa Itu Google Agent Development Kit (ADK)?

Jika Anda pernah membangun chatbot, voicebot layanan pelanggan, atau asisten AI internal dalam beberapa tahun terakhir, Anda kemungkinan besar pernah menghadapi dua kutub arsitektur yang ekstrem:

1. Skrip Prompt-Loop Mentah: Memanggil API LLM secara langsung di dalam perulangan while. Pendekatan ini sangat cepat untuk demonstrasi di laptop, namun langsung menjadi rapuh (fragile) ketika aplikasi Anda membutuhkan aturan bisnis yang ketat, alur diagnostik multi-langkah yang konsisten, validasi parameter deterministik, atau memori sesi (session state) yang dibagikan lintas giliran percakapan.
2. Visual Drag-and-Drop Flow Builders: Platform seperti Dialogflow CX sangat unggul untuk state machine visual yang terstruktur, intent routing, dan integrasi telephony contact center. Namun, ketika sebuah sistem berkembang melintasi puluhan domain yang saling terhubung—menggabungkan diagnostik teknis, pembelian paket tambahan (add-on), pertanyaan tagihan, serta webhook Cloud Run multi-fungsi—kanvas visual dapat menjadi rumit untuk di-diff di Git, diuji secara otomatis di pipeline CI/CD, atau diorkestrasi secara dinamis ketika pengguna berpindah topik di tengah percakapan.

Google Agent Development Kit (ADK) menjembatani celah tersebut dengan memperlakukan pengembangan agen AI sebagai disiplin software engineering standar. Alih-alih menyambungkan kotak-kotak visual secara manual atau menulis pembungkus prompt yang rentan halusinasi, Anda mendefinisikan agen, fungsi Python bertipe (typed tools), pengontrol alur kerja deterministik, dan safety callbacks langsung di dalam kode yang dikelola dengan Git. Anda mengujinya secara lokal menggunakan pytest serta evaluator trajectory, lalu men-deploy-nya sebagai kontainer standar di Google Cloud Run, Google Kubernetes Engine (GKE), atau Vertex AI Agent Engine.

6 Komponen Inti (Core Primitives) yang Wajib Dipahami Pemula

Sebelum menulis satu baris kode pun, Anda hanya perlu memahami enam komponen fondasi dari arsitektur resmi ADK:

1. Agent (LlmAgent vs. Workflow Agents):
   • LlmAgent (atau alias Agent): Unit pekerja cerdas yang ditenagai oleh model Gemini (seperti gemini-2.5-flash atau gemini-2.5-pro). Anda memberinya name, description, sistem instruction, serta daftar tools atau sub_agents. Agen ini menggunakan penalaran LLM untuk memahami maksud pengguna, memilih tool yang tepat, dan mendelegasikan tugas ke sub-agent spesialis.
   • Workflow Agents (SequentialAgent, ParallelAgent, LoopAgent): Pengontrol eksekusi deterministik yang tidak menggunakan LLM untuk menentukan urutan langkah. SequentialAgent menjalankan sub-agent dalam urutan baku yang terjamin (Langkah 1 $\rightarrow$ Langkah 2 $\rightarrow$ Langkah 3); ParallelAgent menjalankan beberapa sub-agent independen secara bersamaan; dan LoopAgent mengulangi langkah hingga kondisi berhenti terpenuhi.
2. Tool (FunctionTool, AgentTool, MCPToolset, OpenAPIToolset):
   • Tool memberikan kemampuan aksi nyata kepada agen—mulai dari memanggil API REST/gRPC, memeriksa database, mencari dokumen enterprise melalui VertexAiSearchTool, hingga terhubung ke server Model Context Protocol (MCPToolset). Di Python, fungsi standar apa pun yang memiliki type hints dan docstring otomatis dibungkus menjadi FunctionTool.
3. Session & State (ToolContext.state):
   • Setiap percakapan dikelola oleh SessionService (InMemorySessionService untuk pengembangan lokal atau VertexAiSessionService untuk persistensi terkelola di cloud). Di dalam setiap tool atau callback, tool_context.state menyediakan kamus (dictionary) key-value bersama yang bertahan lintas giliran percakapan dan dapat diakses oleh seluruh sub-agent.
4. Callbacks (before_model_callback, before_tool_callback, after_agent_callback):
   • Fungsi hook Python ringan yang dieksekusi pada titik-titik siklus hidup tertentu. Anda menggunakan callbacks untuk menerapkan kebijakan keamanan, memvalidasi argumen tool sebelum menyentuh API backend, atau mencatat audit log terstruktur.
5. Event:
   • Unit rekaman tidak berubah (immutable) dari setiap peristiwa yang terjadi selama sesi berlangsung—baik pesan pengguna, pemanggilan tool, perubahan state (state_delta), maupun respons akhir agen.
6. Runner (Runner.run_async & Runner.run_live):
   • Mesin eksekusi (runtime engine) yang menghubungkan root_agent dan SessionService, menjalankan event loop, mengeksekusi tool, menyimpan perubahan state, serta mengalirkan respons teks atau audio dua arah (bidirectional audio) kembali ke pemanggil.

---

2. Jembatan Model Mental: Dari Alur Visual (Dialogflow CX) ke ADK Berbasis Kode

Dalam sesi diskusi arsitektur baru-baru ini bersama seorang engineer Conversational AI senior yang mengoperasikan voicebot contact center berskala produksi di Dialogflow CX—mencakup diagnostik layanan internet berlapis, aktivasi paket perjalanan, pertanyaan tagihan, hingga handover ke agen manusia—pertanyaan pertama yang muncul sangat praktis:

"Bagaimana konsep Dialogflow CX yang sudah dikuasai tim kami—Flows, Pages, Form Parameters, Route Conditions, Cloud Run Webhooks, Playbooks, Barge-In, dan Live Agent Handover—diterjemahkan ke dalam Google ADK?"

Pertama, penting untuk memperjelas kapan harus menggunakan masing-masing pendekatan. Dialogflow CX dan Google Cloud Customer Engagement Suite (CES) Agent Studio tetap menjadi pilihan tepat ketika desainer percakapan lintas fungsi membutuhkan kanvas visual dengan integrasi telephony contact center siap pakai. Sebaliknya, Anda memilih Google ADK ketika tim engineering menginginkan arsitektur code-first: repositori Python atau TypeScript yang modular, pull request Git yang bersih, tanpa boilerplate JSON webhook, delegasi multi-agent yang dinamis, serta pengujian unit dan evaluasi trajectory otomatis di CI/CD.

Jika Anda sudah memahami cara kerja state machine visual, Anda sebenarnya sudah memahami 80% konsep ADK. Berikut adalah tabel pemetaan arsitektur 1-ke-1 secara lengkap:

Konsep Conversational AI / Dialogflow CX	Padanan di Google ADK	Cara Kerjanya di Dalam Kode Python
Agent & Default Start Flow	Root Coordinator (root_agent: LlmAgent)	Diekspor dari app/agent.py. Menyambut pengguna, menjaga konteks tingkat tinggi, dan mengarahkan permintaan ke sub-agent spesialis.
Domain Flows & Sub-Flows (mis. Diagnostik, Paket Add-On, Tagihan)	Hierarki Multi-Agen (sub_agents=[...] atau AgentTool)	Setiap domain dipisahkan menjadi modul LlmAgent tersendiri dengan instruksi dan tools yang terfokus agar prompt tetap ringkas dan akurat.
Alur Diagnostik Sekuensial Ketat (mis. Pemeriksaan L1 $\rightarrow$ L2 $\rightarrow$ L3)	Workflow Agents (SequentialAgent, LoopAgent, ParallelAgent)	Menjamin urutan eksekusi antar sub-agent secara deterministik tanpa bergantung pada tebakan LLM untuk menentukan langkah berikutnya.
Pages, Form Parameters & Conditional Routes (mis. $session.params.outage_checked = true)	ToolContext.state + Guard Clauses Python	Tools membaca dan menulis tool_context.state["outage_checked"] secara langsung serta memeriksa prasyarat menggunakan logika if/else Python biasa.
Cloud Run Webhooks Multi-Fungsi (Parsing WebhookRequest / sessionInfo.parameters)	Python FunctionTool / MCPToolset / OpenAPIToolset	Fungsi Python bertipe (def check_modem(account_id: str, tool_context: ToolContext) -> dict:) dipanggil langsung di dalam proses tanpa serialisasi JSON manual.
Task Playbooks & Vertex AI Search Data Stores	Instruksi LlmAgent + VertexAiSearchTool	Menggabungkan instruksi bahasa alami dengan Retrieval-Augmented Generation (RAG) yang ter-grounding pada dokumen enterprise di Vertex AI Search.
Voice Barge-In, endpointerSensitivity & Streaming Audio	Runner.run_live() + LiveRequestQueue + Gemini Live API	Mengalirkan audio dua arah secara native lewat WebSocket dengan Voice Activity Detection (VAD) sisi server dan penghentian audio instan (interrupted=True).
Halaman Live Agent Handover + Payload Ringkasan	Escalation FunctionTool + tool_context.actions.escalate = True	Menyimpan ringkasan JSON terstruktur ke tool_context.state["handover_payload"] dan menyetel tool_context.actions.escalate = True untuk mentransfer sesi.

---

3. Level 1 (Pemula): Membangun Agen ADK Stateful Pertama Anda dengan Python

Untuk melihat betapa sederhananya ADK bagi pemula, mari kita bangun aplikasi single-agent lengkap (app/agent.py) yang membantu pelanggan mendiagnosis gangguan koneksi internet rumah mereka.

Di Dialogflow CX, mencegah bot me-reboot modem pelanggan sebelum memeriksa adanya gangguan jaringan area (area outage) mengharuskan kita merangkai beberapa Pages, Form Parameters, dan Conditional Transition Routes. Di ADK, sebagaimana dijelaskan dalam tutorial resmi Build a Multi-Tool Agent, Anda cukup menulis fungsi Python biasa yang membaca dan memperbarui tool_context.state:

# app/agent.py
from google.adk.agents import LlmAgent
from google.adk.tools import ToolContext


def check_area_outage(account_id: str, tool_context: ToolContext) -> dict:
    """Langkah 1: Memeriksa apakah ada gangguan jaringan area pada akun pelanggan.

    Args:
        account_id: ID akun pelanggan (contoh: 'ACC-1042').
    """
    # Simpan ID akun dan status pemeriksaan gangguan ke dalam memori sesi (session state)
    tool_context.state["account_id"] = account_id
    tool_context.state["outage_checked"] = True
    tool_context.state["active_outage"] = False

    return {
        "status": "ok",
        "account_id": account_id,
        "active_outage": False,
        "message": "Tidak ditemukan gangguan jaringan area di lokasi pelanggan.",
    }


def check_modem_telemetry(tool_context: ToolContext) -> dict:
    """Langkah 2: Memeriksa redaman sinyal optik dan packet loss dari modem pelanggan."""
    if not tool_context.state.get("outage_checked"):
        return {
            "status": "blocked_precondition",
            "action_required": "Anda WAJIB memanggil check_area_outage terlebih dahulu sebelum memeriksa telemetri modem.",
        }

    if tool_context.state.get("active_outage"):
        return {
            "status": "skipped_due_to_outage",
            "message": "Gangguan area sedang berlangsung; pemeriksaan modem individu tidak diperlukan.",
        }

    tool_context.state["telemetry_checked"] = True
    tool_context.state["optical_rx_dbm"] = -19.4
    return {
        "status": "ok",
        "optical_rx_dbm": -19.4,
        "packet_loss_pct": 4.2,
        "recommendation": "Sinyal optik normal (-19.4 dBm), namun packet loss tinggi. Disarankan remote reboot.",
    }


def trigger_remote_reboot(tool_context: ToolContext) -> dict:
    """Langkah 3: Mengirim perintah restart jarak jauh ke modem pelanggan untuk memulihkan koneksi."""
    if not tool_context.state.get("outage_checked") or not tool_context.state.get("telemetry_checked"):
        return {
            "status": "blocked_precondition",
            "action_required": "Tidak dapat melakukan reboot sebelum check_area_outage dan check_modem_telemetry selesai dijalankan.",
        }

    tool_context.state["reboot_triggered"] = True
    return {
        "status": "reboot_initiated",
        "account_id": tool_context.state.get("account_id"),
        "estimated_recovery_seconds": 90,
    }


root_agent = LlmAgent(
    name="broadband_support_assistant",
    model="gemini-2.5-flash",
    description="Asisten dukungan teknis yang mendiagnosis koneksi internet secara bertahap.",
    instruction=(
        "Anda adalah asisten dukungan teknis internet rumah. "
        "Ikuti urutan diagnostik secara ketat: "
        "1) Selalu periksa gangguan area dengan check_area_outage terlebih dahulu. "
        "2) Selanjutnya, periksa kualitas sinyal modem dengan check_modem_telemetry. "
        "3) Hanya jalankan trigger_remote_reboot jika telemetri sudah diperiksa dan merekomendasikan reboot."
    ),
    tools=[check_area_outage, check_modem_telemetry, trigger_remote_reboot],
)

Mengapa Pola Ini Sangat Mudah Dipahami oleh Engineer

1. Tanpa Schema Boilerplate: ADK membaca type annotations Python (account_id: str) dan docstring fungsi Anda untuk menyusun deklarasi tool bagi Gemini secara otomatis. Parameter tool_context: ToolContext disuntikkan secara otomatis oleh runtime ADK dan disembunyikan dari skema LLM.
2. Memori Sesi Bersama (tool_context.state): Setiap nilai yang disimpan ke tool_context.state dicatat sebagai state delta di dalam riwayat sesi dan tetap tersedia pada giliran percakapan berikutnya.
3. Safety Guardrails Deterministik: Bahkan jika penelepon yang tidak sabar berkata "Langsung restart saja router saya sekarang!", fungsi trigger_remote_reboot memeriksa tool_context.state di level kode Python dan menolak eksekusi hingga check_area_outage serta check_modem_telemetry selesai dijalankan.

---

4. Mempercepat Siklus Pengembangan dengan agents-cli (google-agents-cli)

Meskipun Anda dapat membuat berkas ADK secara manual dan menjalankan adk web, Google menyediakan Agents CLI (google-agents-cli)—perangkat command-line terpadu dan paket skills pengkodean AI yang terdokumentasi di google.github.io/agents-cli untuk menyederhanakan seluruh siklus hidup agen: Scaffold $\rightarrow$ Run & Playground $\rightarrow$ Evaluate $\rightarrow$ Enhance $\rightarrow$ Deploy.

Tak kalah menarik, menjalankan perintah uvx google-agents-cli setup akan memasang skills resmi pengembangan ADK langsung ke asisten IDE AI seperti Antigravity, Claude Code, dan Cursor (panduan Coding with AI). Dengan begitu, asisten AI di editor Anda langsung memahami pola kode terbaru ADK, struktur berkas evaluasi, hingga konfigurasi deployment Cloud Run dan Vertex AI Agent Engine.

flowchart LR
    subgraph Step1["1. Scaffold (Prototype-First)"]
        S1["agents-cli scaffold create my-agent<br/>--agent adk --prototype"]
    end

    subgraph Step2["2. Run & Visual Debug"]
        S2["agents-cli run '...'<br/>agents-cli playground"]
    end

    subgraph Step3["3. Verifikasi Dua Lapis"]
        S3["uv run pytest (Unit Tests)<br/>agents-cli eval run (Trajectories)"]
    end

    subgraph Step4["4. Enhance & Deploy"]
        S4["agents-cli scaffold enhance .<br/>agents-cli deploy"]
    end

    Step1 --> Step2 --> Step3 --> Step4

Alur Kerja Prototype-First dengan agents-cli

Praktik terbaik utama di dalam agents-cli adalah prototype-first scaffolding: mulailah proyek baru dengan flag --prototype agar Anda mendapatkan struktur direktori yang bersih dan minimalis (app/agent.py, tests/, pyproject.toml) tanpa dibebani berkas Terraform atau CI/CD di awal. Setelah logika agen berjalan mulus di playground lokal, Anda cukup menjalankan agents-cli scaffold enhance untuk menambahkan infrastruktur deployment produksi tanpa merusak kode agen yang sudah Anda tulis.

# 1. Instal google-agents-cli dan pasang ADK skills untuk IDE AI Anda
uv tool install google-agents-cli
uvx google-agents-cli setup

# 2. Buat kerangka proyek prototipe ADK yang ringan
agents-cli scaffold create customer-concierge --agent adk --prototype
cd customer-concierge

# 3. Jalankan uji coba cepat satu giliran (smoke test) langsung dari terminal
agents-cli run "Check if there is an outage for account ACC-1042"

# 4. Buka Web Playground interaktif (inspeksi event, pemanggilan tool, dan session.state secara visual)
agents-cli playground

# 5. Jalankan unit test deterministik yang cepat pada fungsi-fungsi Python Anda
uv run pytest tests/unit

# 6. Buat dataset evaluasi dan nilai akurasi trajectory multi-turn agen Anda
agents-cli eval generate --agent-module app.agent
agents-cli eval run

# 7. Saat siap naik ke cloud, tambahkan konfigurasi Cloud Run atau Vertex AI Agent Engine
agents-cli scaffold enhance . --deployment-target cloud_run

# 8. Deploy ke Google Cloud
agents-cli deploy

Bagaimana pytest dan agents-cli eval Saling Melengkapi

Engineer yang beralih dari visual flow builder sering bertanya bagaimana cara mencegah regresi ketika memperbarui prompt atau menambah tool baru. agents-cli menerapkan piramida pengujian dua lapis yang sangat rapi:

• Lapis 1 — Unit Test Deterministik (uv run pytest): Memanggil fungsi Python Anda (check_area_outage, trigger_remote_reboot) secara langsung menggunakan objek ToolContext di memori. Pengujian ini selesai dalam hitungan milidetik, tidak memakan biaya token LLM, dan memastikan seluruh guardrail prasyarat serta pengolahan data berjalan sempurna.
• Lapis 2 — Evaluasi Perilaku & Trajectory (agents-cli eval run): Menjalankan skenario percakapan multi-turn melalui Runner ADK dan menilai dua metrik utama:
  1. Skor Tool Trajectory: Apakah agen memanggil check_area_outage sebelum check_modem_telemetry sesuai urutan yang diharapkan?
  2. Skor Kualitas Respons (LLM-as-Judge): Apakah jawaban akhir agen akurat dan sesuai dengan data kembalian tool tanpa berhalusinasi?

---

5. Level 2 (Menengah): Mengembangkan Tim Multi-Agen (Multi-Agent Team)

Ketika asisten Anda berkembang dari satu domain menjadi concierge layanan pelanggan utuh—menangani diagnostik teknis, aktivasi paket data perjalanan, penjelasan tagihan, hingga eskalasi ke agen manusia—menumpuk 25 tools di dalam satu LlmAgent akan menurunkan akurasi pemilihan tool dan membuat system prompt membengkak.

Di ADK, masalah ini diselesaikan menggunakan pola Coordinator + Specialist Sub-Agents yang diajarkan pada tutorial resmi Build an Agent Team dan dibahas mendalam di Google Cloud AI Blog. Anda memecah setiap domain menjadi modul LlmAgent spesialis yang fokus, lalu mendaftarkannya di bawah root coordinator melalui sub_agents=[...].

flowchart TB
    subgraph ClientChannels["Kanal Penelepon & Developer"]
        WebPlayground["ADK Web Playground / REST Client"]
        VoiceGateway["Streaming Audio Gemini Live<br/>(Runner.run_live + LiveRequestQueue)"]
    end

    subgraph MultiAgentTeam["Hierarki Multi-Agen Google ADK (app/agent.py)"]
        RootConcierge["Root Coordinator LlmAgent<br/>(support_concierge_root)"]
        DiagnosticsSub["Agen Spesialis Diagnostik<br/>(Tools L1-L3 dengan State Guard)"]
        AddOnPassSub["Agen Spesialis Paket & Add-On<br/>(Tools dengan Konfirmasi Harga)"]
        BillingSub["Agen Spesialis Tagihan & Kontrak<br/>(Cek Tagihan + Grounded Policy RAG)"]
    end

    subgraph SharedRuntime["Memori Sesi Bersama & Handover Enterprise"]
        SessionStore["SessionService<br/>(Memori Bersama ToolContext.state)"]
        EscalationTool["Tool Handover Agen Manusia<br/>(escalate_to_human_agent)"]
    end

    WebPlayground --> RootConcierge
    VoiceGateway --> RootConcierge

    RootConcierge -->|"Kendala Internet / Modem"| DiagnosticsSub
    RootConcierge -->|"Paket Data Perjalanan"| AddOnPassSub
    RootConcierge -->|"Tagihan & Masa Kontrak"| BillingSub
    RootConcierge -->|"Sengketa Kompleks / Eskalasi"| EscalationTool

    DiagnosticsSub <--> SessionStore
    AddOnPassSub <--> SessionStore
    BillingSub <--> SessionStore
    EscalationTool <--> SessionStore

Bedah Kode: Delegasi Multi-Agen, Konfirmasi Transaksi & Handover ke Agen Manusia

Berikut adalah contoh implementasi tingkat menengah yang menggabungkan tiga pola penting kelas produksi:

1. Guardrail Konfirmasi Eksplisit Pengguna sebelum mengeksekusi transaksi berbayar (activate_travel_pass).
2. Handover Terstruktur ke Agen Manusia (escalate_to_human_agent) yang membungkus state sesi menjadi payload ringkasan JSON dan mengaktifkan tool_context.actions.escalate = True.
3. Delegasi Sub-Agen Hierarkis di mana seluruh spesialis berbagi ToolContext.state yang sama.

# app/multi_agent_concierge.py
from google.adk.agents import LlmAgent
from google.adk.tools import ToolContext
from app.agent import (
    check_area_outage,
    check_modem_telemetry,
    trigger_remote_reboot,
)


def activate_travel_pass(
    pass_sku: str,
    customer_confirmed: bool,
    tool_context: ToolContext,
) -> dict:
    """Mengaktifkan paket data perjalanan internasional setelah konfirmasi eksplisit pelanggan.

    Args:
        pass_sku: Kode paket perjalanan (contoh: 'ROAM_7D_ASIA').
        customer_confirmed: Bernilai True HANYA jika pelanggan telah menyetujui harga secara eksplisit.
    """
    price_map = {"ROAM_7D_ASIA": 15.0, "ROAM_14D_GLOBAL": 35.0}
    if pass_sku not in price_map:
        return {"status": "error", "message": f"Kode paket tidak dikenal: {pass_sku}"}

    price_usd = price_map[pass_sku]

    # Guardrail: Jangan pernah menagih pelanggan sebelum harga disebutkan dan dikonfirmasi
    if not customer_confirmed or tool_context.state.get("quoted_pass_sku") != pass_sku:
        tool_context.state["quoted_pass_sku"] = pass_sku
        return {
            "status": "confirmation_required",
            "pass_sku": pass_sku,
            "price_usd": price_usd,
            "instruction": f"Sebutkan harga ${price_usd:.2f} untuk {pass_sku} dan minta konfirmasi pengguna sebelum aktivasi.",
        }

    tool_context.state["active_travel_pass"] = pass_sku
    return {
        "status": "activated",
        "pass_sku": pass_sku,
        "billed_usd": price_usd,
    }


def lookup_contract_and_balance(account_id: str, tool_context: ToolContext) -> dict:
    """Mengambil informasi saldo tagihan berjalan dan tanggal berakhir kontrak pelanggan."""
    tool_context.state["account_id"] = account_id
    return {
        "status": "ok",
        "account_id": account_id,
        "current_balance_usd": 64.50,
        "contract_end_date": "2027-03-15",
        "early_termination_fee_usd": 120.00,
    }


def escalate_to_human_agent(
    reason: str,
    conversation_summary: str,
    tool_context: ToolContext,
) -> dict:
    """Mentransfer percakapan ke agen manusia disertai payload konteks terstruktur.

    Args:
        reason: Kode kategori eskalasi (contoh: 'BILLING_DISPUTE', 'UNRESOLVED_LINE_FAULT').
        conversation_summary: Ringkasan padat 2 kalimat mengenai kendala pelanggan dan langkah yang sudah diambil.
    """
    handover_payload = {
        "escalation_reason": reason,
        "summary": conversation_summary,
        "account_id": tool_context.state.get("account_id", "UNVERIFIED"),
        "diagnostics_completed": bool(tool_context.state.get("telemetry_checked", False)),
        "reboot_triggered": bool(tool_context.state.get("reboot_triggered", False)),
        "active_travel_pass": tool_context.state.get("active_travel_pass"),
    }
    tool_context.state["handover_payload"] = handover_payload
    # Beri sinyal kepada ADK Runner untuk menghentikan eksekusi otonom dan meneruskan ke antrean CCaaS
    tool_context.actions.escalate = True
    return {"status": "handover_ready", "handover_payload": handover_payload}


# --- Sub-Agen Spesialis ---
diagnostics_specialist = LlmAgent(
    name="diagnostics_specialist",
    model="gemini-2.5-flash",
    description="Mendiagnosis kendala internet rumah, memeriksa gangguan area, telemetri modem, dan reboot modem.",
    instruction=(
        "Tangani seluruh kendala koneksi internet. Patuhi urutan baku: "
        "check_area_outage -> check_modem_telemetry -> trigger_remote_reboot."
    ),
    tools=[check_area_outage, check_modem_telemetry, trigger_remote_reboot],
)

travel_pass_specialist = LlmAgent(
    name="travel_pass_specialist",
    model="gemini-2.5-flash",
    description="Memberikan kuotasi harga dan mengaktifkan paket data perjalanan internasional.",
    instruction=(
        "Bantu pelanggan memilih dan mengaktifkan paket perjalanan. Selalu sebutkan harga "
        "terlebih dahulu dan tunggu persetujuan eksplisit sebelum mengisi customer_confirmed=True."
    ),
    tools=[activate_travel_pass],
)

billing_contract_specialist = LlmAgent(
    name="billing_contract_specialist",
    model="gemini-2.5-flash",
    description="Menjawab pertanyaan saldo tagihan, perpanjangan kontrak, dan sengketa biaya.",
    instruction=(
        "Gunakan lookup_contract_and_balance untuk menjawab pertanyaan tagihan dan kontrak. "
        "Jika pelanggan mengajukan sengketa biaya atau meminta penghapusan denda kontrak, "
        "panggil escalate_to_human_agent dengan ringkasan lengkap."
    ),
    tools=[lookup_contract_and_balance, escalate_to_human_agent],
)

# --- Root Coordinator Agent ---
root_agent = LlmAgent(
    name="support_concierge_root",
    model="gemini-2.5-flash",
    description="Concierge utama layanan pelanggan yang mengarahkan ke diagnostik, paket perjalanan, dan tagihan.",
    instruction=(
        "Anda adalah concierge utama pelanggan. Delegasikan masalah koneksi internet "
        "ke diagnostics_specialist, permintaan paket perjalanan ke travel_pass_specialist, serta "
        "pertanyaan tagihan atau kontrak ke billing_contract_specialist."
    ),
    sub_agents=[
        diagnostics_specialist,
        travel_pass_specialist,
        billing_contract_specialist,
    ],
    tools=[escalate_to_human_agent],
)

---

6. Pola Menengah untuk Voicebot: Streaming Suara Real-Time & Barge-In (Runner.run_live)

Bagi engineer yang membangun voicebot, integrasi Streaming & Gemini Live API di ADK menggantikan arsitektur berantai tradisional Speech-to-Text (STT) $\rightarrow$ Webhook $\rightarrow$ Text-to-Speech (TTS) dengan bidirectional audio streaming berlatensi rendah.

Dengan meneruskan objek LiveRequestQueue dan RunConfig ke dalam runner.run_live(), hierarki multi-agent yang sama dapat langsung berinteraksi melalui suara secara real-time sekaligus menangani interupsi penelepon (barge-in) secara otomatis:

# app/voice_runner.py
from google.adk.agents.live_request_queue import LiveRequestQueue
from google.adk.agents.run_config import RunConfig, StreamingMode
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types
from app.multi_agent_concierge import root_agent


async def stream_voice_conversation(user_id: str, session_id: str):
    session_service = InMemorySessionService()
    await session_service.create_session(
        app_name="voice_concierge",
        user_id=user_id,
        session_id=session_id,
    )

    runner = Runner(
        app_name="voice_concierge",
        agent=root_agent,
        session_service=session_service,
    )

    # Konfigurasi audio dua arah dan sensitivitas Voice Activity Detection (VAD)
    run_config = RunConfig(
        streaming_mode=StreamingMode.BIDI,
        response_modalities=["AUDIO"],
        realtime_input_config=types.RealtimeInputConfig(
            automatic_activity_detection=types.AutomaticActivityDetection(
                disabled=False,
                start_of_speech_sensitivity=types.StartSensitivity.START_SENSITIVITY_LOW,
                end_of_speech_sensitivity=types.EndSensitivity.END_SENSITIVITY_LOW,
                silence_duration_ms=500,
            )
        ),
    )

    live_request_queue = LiveRequestQueue()

    async for event in runner.run_live(
        user_id=user_id,
        session_id=session_id,
        live_request_queue=live_request_queue,
        run_config=run_config,
    ):
        # Ketika penelepon memotong pembicaraan (barge-in), ADK menandai event.interrupted = True
        if getattr(event, "interrupted", False):
            print("Penelepon melakukan interupsi — mengosongkan buffer audio keluar secara instan.")

        # Ketika escalate_to_human_agent menyetel actions.escalate = True, teruskan ke antrean CCaaS
        if event.actions and event.actions.escalate:
            session = await session_service.get_session(
                app_name="voice_concierge", user_id=user_id, session_id=session_id
            )
            print("Mentransfer panggilan beserta payload handover:", session.state.get("handover_payload"))
            break

---

7. Use Case Nyata di Lapangan: Ide Implementasi Praktis

Baik saat Anda memodernisasi voicebot telekomunikasi, asisten layanan e-commerce, maupun helpdesk TI internal, perpaduan konsep code-first ADK dan agents-cli membuka tiga pola operasional berdampak tinggi:

1. Diagnostik Perangkat Bertahap Tanpa Eksekusi Prematur

• Masalah Sehari-hari: Pada bot yang hanya mengandalkan prompt, LLM dapat berhalusinasi mengenai status perangkat atau memicu restart modem yang mengganggu sebelum memeriksa apakah sedang terjadi gangguan jaringan di tingkat area.
• Cara Kerja di Praktik: Dengan menyimpan titik pemeriksaan diagnostik (outage_checked, telemetry_checked) di dalam ToolContext.state dan memvalidasinya di baris awal trigger_remote_reboot, kode Python—bukan probabilitas LLM—yang memastikan urutan pemeriksaan dipatuhi 100%.
• Dampak Bisnis & Pengguna: Pelanggan mendapatkan diagnosis akar masalah yang akurat dan cepat, sementara tim operasi jaringan terhindar dari lonjakan perintah reboot perangkat yang tidak perlu saat terjadi gangguan massal.

2. Percakapan Multi-Intent Lintas Domain dalam Satu Sesi

• Masalah Sehari-hari: Pelanggan di dunia nyata jarang menelepon hanya dengan satu maksud yang terisolasi kaku. Seorang penelepon bisa memulai dengan menanyakan mengapa Wi-Fi rumahnya lambat, lalu meminta aktivasi paket data perjalanan 7 hari, dan terakhir menanyakan kapan masa kontraknya berakhir.
• Cara Kerja di Praktik: Alih-alih mengunci pengguna di dalam satu sub-flow kaku, root LlmAgent mendelegasikan setiap giliran ke spesialis yang sesuai (diagnostics_specialist $\rightarrow$ travel_pass_specialist $\rightarrow$ billing_contract_specialist) sambil mempertahankan tool_context.state["account_id"] di sepanjang sesi.
• Dampak Bisnis & Pengguna: Pelanggan menyelesaikan berbagai kebutuhan dalam satu percakapan alami tanpa harus mengulang verifikasi identitas atau kembali ke menu utama.

3. Warm Handover ke Agen Manusia Tanpa Pengulangan Cerita

• Masalah Sehari-hari: Tidak ada pengalaman yang lebih membuat pelanggan frustrasi selain menghabiskan lima menit mengikuti langkah diagnostik dengan bot, lalu setelah ditransfer ke agen manusia justru ditanya kembali: "Boleh disebutkan nomor akun Anda dan apa kendala yang dialami?"
• Cara Kerja di Praktik: Pemanggilan escalate_to_human_agent merangkum seluruh parameter yang telah diverifikasi (account_id, diagnostics_completed, reboot_triggered, serta summary dua kalimat) ke dalam tool_context.state["handover_payload"] dan menyetel tool_context.actions.escalate = True.
• Dampak Bisnis & Pengguna: Agen contact center langsung melihat riwayat diagnostik lengkap di layar mereka (screen-pop), memangkas Average Handle Time (AHT) dan meningkatkan kepuasan pelanggan secara signifikan.

---

8. Referensi Resmi, Blog Google Cloud & Codelab Langkah demi Langkah

Siap membangun agen ADK pertama Anda? Simpan peta belajar terstruktur berisi dokumentasi resmi, artikel blog arsitektur, dan codelab praktis berikut ini:

A. Dokumentasi Resmi & Panduan agents-cli

1. Dokumentasi Resmi Agent Development Kit (adk.dev) — Referensi utama yang membahas LlmAgent, workflow agents (SequentialAgent, ParallelAgent, LoopAgent), ToolContext.state, callbacks, dan session services.
2. ADK Python Quickstart (adk.dev/get-started/python/) — Panduan menginstal google-adk, menyiapkan kunci API Gemini atau proyek Vertex AI, dan menjalankan agen pertama Anda dalam waktu kurang dari lima menit.
3. Agents CLI Quickstart (adk.dev/get-started/agents-cli/) & Dokumentasi Agents CLI (google.github.io/agents-cli/) — Panduan lengkap penggunaan google-agents-cli (scaffold create, run, playground, eval, scaffold enhance, dan deploy).
4. Coding with AI & ADK Docs MCP Server (adk.dev/tutorials/coding-with-ai/) — Cara memasang uvx google-agents-cli setup dan menghubungkan server MCP https://adk.dev/llms.txt ke Antigravity, Cursor, maupun Claude Code.
5. Vertex AI Agent Engine Overview (cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview) — Panduan deployment produksi untuk menjalankan agen ADK stateful dengan VertexAiSessionService terkelola, Memory Bank, dan telemetri Cloud Trace.

B. Blog Resmi Google Cloud & Panduan Platform

1. Build Multi-Agent Systems with Google Agent Development Kit (Google Cloud Blog) — Ulasan arsitektur mendalam mengenai alasan Google membangun ADK, cara kerja delegasi multi-agent hierarkis, serta integrasinya dengan ekosistem Model Context Protocol (MCP) dan Agent-to-Agent (A2A).
2. Gemini Enterprise Agent Platform — Build with ADK (docs.cloud.google.com) — Panduan bagaimana tim enterprise mengelola tata kelola, evaluasi, dan skala agen ADK di Cloud Run, GKE, dan managed runtime.

C. Tutorial Bertahap & Codelab Mudah untuk Diikuti

Ikuti empat laboratorium praktis ini secara berurutan untuk menguasai level pemula hingga menengah dalam satu sore:

1. Langkah 1 (Pemula — 15 menit): Build a Multi-Tool Agent (adk.dev/tutorials/multi-tool-agent/) — Buat LlmAgent Python pertama Anda, tambahkan fungsi kustom sebagai tool, dan inspeksi jejak eksekusi secara langsung di Developer UI.
2. Langkah 2 (Pemula ke Menengah — 30 menit): Build an Agent Team (adk.dev/tutorials/agent-team/) — Bangun koordinator multi-agent dengan sub-agent spesialis, memori sesi ToolContext.state, serta guardrails before_model_callback dan before_tool_callback.
3. Langkah 3 (Menengah — 25 menit): Build a Streaming Voice & Video Agent (adk.dev/live/get-started/) — Tambahkan kemampuan bidirectional audio streaming dan penanganan barge-in menggunakan Runner.run_live().
4. Langkah 4 (Google Codelabs Mandiri & Repositori Sampel):
   • Google Codelabs — Katalog AI & ADK (codelabs.developers.google.com/?cat=ai) — Cari "Agent Development Kit" atau "ADK" untuk mengikuti codelab interaktif di browser (termasuk Building AI Agents with ADK: The Foundation dan Build Multi-Agent Systems with ADK).
   • Repositori Sampel Resmi ADK (github.com/google/adk-samples) — Kumpulan agen referensi siap pakai untuk kasus penggunaan layanan pelanggan, software engineering, ritel, dan perjalanan yang dapat langsung Anda clone dan jalankan.