Tutorial Lengkap: Membangun Multi-Agent System dengan Google ADK + FastAPI (2026)

1) Introduction — What and Why

Dalam 2 tahun terakhir, pola aplikasi AI berubah drastis. Dulu kita bikin satu chatbot “serba bisa” lalu berharap dia kuat untuk semua tugas. Hasilnya? Biasanya kacau: konteks bercampur, jawaban tidak konsisten, dan susah di-debug.

Sekarang tren yang naik banget (terlihat dari GitHub Trending dan artikel developer terbaru) adalah multi-agent architecture: satu agent koordinator + beberapa agent spesialis.

Bayangin tim kerja di kantor:

• Ada manajer yang membagi tugas
• Ada staf riset yang cari data
• Ada staf teknis yang eksekusi
• Ada QA yang verifikasi

Model ini lebih realistis daripada satu “karyawan super” yang harus menguasai semuanya.

Di tutorial ini, kamu akan belajar membangun sistem multi-agent berbasis Google Agent Development Kit (ADK) dan mengeksposnya lewat FastAPI. Kita pakai skenario nyata: AI assistant untuk support developer yang bisa:

1. Klasifikasi intent pertanyaan
2. Delegasi ke agent spesialis
3. Menjaga guardrail keamanan dasar
4. Mengembalikan respons yang rapi untuk API client

Kenapa ini penting untuk dunia nyata?

• Produk SaaS perlu bot support yang akurat
• Tim internal butuh assistant yang bisa diandalkan
• Multi-agent bikin sistem lebih mudah diskalakan dan diuji

Singkatnya: kalau kamu serius pakai AI di production, pattern ini bukan “nice to have” lagi, tapi fondasi.

---

2) Prerequisites

Sebelum mulai, pastikan kamu punya:

Skill teknis

• Dasar Python (function, class, async)
• Dasar REST API
• Familiar dengan virtual environment

Environment

• Python 3.11+
• API key model (misalnya Gemini/LLM provider yang kompatibel)
• Terminal Linux/macOS/WSL

Library

Kita akan pakai:

• google-adk
• fastapi
• uvicorn
• pydantic

Install:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install google-adk fastapi uvicorn pydantic

Set environment variable model key (contoh):

export GOOGLE_API_KEY="your_api_key_here"

Tips: simpan secret di .env + secret manager, jangan hardcode di source code.

---

3) Core Concepts (dengan analogi)

A. Single Agent vs Multi-Agent

• Single agent: seperti satu orang yang harus jadi CS, engineer, legal, finance sekaligus.
• Multi-agent: seperti tim kecil dengan peran spesifik.

B. Coordinator Pattern

Satu agent utama menerima pertanyaan, lalu menentukan siapa yang paling cocok menjawab.

Analogi: resepsionis di klinik. Semua pasien masuk lewat satu meja, lalu diarahkan ke dokter yang tepat.

C. Workflow Agent

ADK menyediakan struktur seperti:

• Sequential: langkah berurutan
• Parallel: eksekusi paralel
• Loop: ulangi sampai kondisi selesai

D. Shared Context dan State

Agent bisa berbagi state, tapi harus disiplin key naming agar tidak tabrakan.

Analogi: papan Kanban tim. Semua boleh lihat, tapi tiap kartu harus jelas labelnya.

E. Guardrails

Kalau tools terlalu bebas, agent bisa melakukan aksi tidak aman. Minimal harus ada:

• Validasi input
• Pembatasan command/aksi
• Error handling yang jelas

---

4) Architecture / Diagram

Berikut arsitektur sederhana sistem yang akan kita bangun:

[Client App]
    |
    v
[FastAPI /ask]
    |
    v
[Coordinator Agent]
   /        |         \
  v         v          v
[DocAgent] [CodeAgent] [TroubleshootAgent]
   \         |          /
    \        |         /
     v       v        v
   [Tool Layer: safe_search_docs, safe_summarize_code, safe_troubleshoot]
                |
                v
          [Structured JSON Response]

Flow request:

1. Client kirim pertanyaan ke endpoint /ask
2. Coordinator membaca intent
3. Delegasi ke sub-agent yang relevan
4. Sub-agent gunakan tool (yang sudah dibatasi)
5. Hasil dirangkai dan dikembalikan sebagai JSON

---

5) Step-by-Step Implementation (runnable code)

Di bawah ini contoh satu file lengkap (main.py) yang bisa kamu jalankan langsung.

"""
main.py
Contoh minimal production-friendly multi-agent API dengan ADK + FastAPI.
Jalankan:
  uvicorn main:app --reload --port 8080
"""

from __future__ import annotations

import logging
import os
from typing import Any, Dict, Literal

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field, ValidationError

# ADK imports (mengikuti pola dokumentasi ADK)
from google.adk.agents import LlmAgent

# -----------------------------------------------------
# Logging setup
# -----------------------------------------------------
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
)
logger = logging.getLogger("multi-agent-api")


# -----------------------------------------------------
# Safe tool functions (contoh)
# -----------------------------------------------------
def safe_search_docs(query: str) -> str:
    """
    Tool simulasi pencarian dokumentasi.
    Tambahkan guardrails: validasi panjang query dan blacklist sederhana.
    """
    if not query or len(query.strip()) < 3:
        raise ValueError("Query terlalu pendek. Minimal 3 karakter.")

    blocked_terms = ["drop table", "rm -rf", "credential leak"]
    lowered = query.lower()
    if any(term in lowered for term in blocked_terms):
        raise ValueError("Query mengandung pola berbahaya dan ditolak.")

    # Pada sistem nyata, ini bisa panggil API docs internal / vector DB
    return (
        f"Hasil docs untuk '{query}': fokus pada API contract, auth flow, "
        "dan error handling berbasis status code."
    )


def safe_summarize_code(snippet: str) -> str:
    """
    Tool simulasi ringkasan code.
    Hindari input terlalu panjang untuk mencegah biaya token meledak.
    """
    if not snippet:
        raise ValueError("Snippet code kosong.")
    if len(snippet) > 4000:
        raise ValueError("Snippet terlalu panjang (maks 4000 karakter).")

    return (
        "Ringkasan code: struktur sudah modular, "
        "tapi perlu perbaikan error handling dan unit test pada edge case."
    )


def safe_troubleshoot(issue: str) -> str:
    """
    Tool troubleshooting sederhana.
    """
    if not issue:
        raise ValueError("Issue tidak boleh kosong.")

    hints = [
        "cek environment variable",
        "verifikasi dependency version",
        "lihat stack trace paling awal",
        "isolasi bug dengan reproduksi minimal",
    ]
    return f"Checklist troubleshooting untuk '{issue}': " + "; ".join(hints)


# -----------------------------------------------------
# ADK Agent setup
# -----------------------------------------------------
def create_agents() -> LlmAgent:
    """
    Bangun coordinator + sub-agents.
    """
    model_name = os.getenv("AGENT_MODEL", "gemini-2.5-flash")

    doc_agent = LlmAgent(
        name="DocAgent",
        model=model_name,
        instruction=(
            "Kamu spesialis dokumentasi developer. "
            "Gunakan tool pencarian docs untuk menjawab ringkas dan akurat."
        ),
        tools=[safe_search_docs],
        description="Menjawab pertanyaan dokumentasi/API.",
    )

    code_agent = LlmAgent(
        name="CodeAgent",
        model=model_name,
        instruction=(
            "Kamu spesialis code review cepat. "
            "Gunakan tool ringkasan code, fokus ke maintainability dan bug risk."
        ),
        tools=[safe_summarize_code],
        description="Menganalisis dan merangkum potongan kode.",
    )

    troubleshoot_agent = LlmAgent(
        name="TroubleshootAgent",
        model=model_name,
        instruction=(
            "Kamu spesialis debugging. "
            "Gunakan checklist troubleshooting yang actionable."
        ),
        tools=[safe_troubleshoot],
        description="Memberikan langkah diagnosis issue teknis.",
    )

    coordinator = LlmAgent(
        name="Coordinator",
        model=model_name,
        description="Koordinator utama untuk pertanyaan developer support.",
        instruction=(
            "Tentukan intent user: docs, code_review, atau troubleshooting. "
            "Delegasikan ke sub-agent yang paling tepat. "
            "Jika ambigu, ajukan 1 pertanyaan klarifikasi singkat."
        ),
        sub_agents=[doc_agent, code_agent, troubleshoot_agent],
    )

    return coordinator


ROOT_AGENT = create_agents()


# -----------------------------------------------------
# API schema
# -----------------------------------------------------
class AskRequest(BaseModel):
    question: str = Field(..., min_length=3, max_length=3000)
    mode: Literal["auto", "docs", "code", "troubleshoot"] = "auto"


class AskResponse(BaseModel):
    ok: bool
    answer: str
    meta: Dict[str, Any]


# -----------------------------------------------------
# FastAPI app
# -----------------------------------------------------
app = FastAPI(title="ADK Multi-Agent API", version="1.0.0")


@app.get("/health")
def health() -> Dict[str, str]:
    return {"status": "ok"}


@app.post("/ask", response_model=AskResponse)
async def ask(payload: AskRequest) -> AskResponse:
    """
    Endpoint utama untuk bertanya ke sistem multi-agent.
    Untuk demo, kita gunakan prompt routing sederhana.
    Pada implementasi penuh, kamu bisa pakai runner/session ADK lengkap.
    """
    try:
        question = payload.question.strip()
        if not question:
            raise HTTPException(status_code=400, detail="Pertanyaan kosong.")

        # Routing awal berbasis mode eksplisit (jika user memilih)
        if payload.mode == "docs":
            answer = safe_search_docs(question)
            chosen = "DocAgent"
        elif payload.mode == "code":
            answer = safe_summarize_code(question)
            chosen = "CodeAgent"
        elif payload.mode == "troubleshoot":
            answer = safe_troubleshoot(question)
            chosen = "TroubleshootAgent"
        else:
            # Auto mode: heuristik sederhana sebelum diserahkan ke koordinasi LLM
            lowered = question.lower()
            if any(k in lowered for k in ["error", "crash", "timeout", "bug"]):
                answer = safe_troubleshoot(question)
                chosen = "TroubleshootAgent"
            elif any(k in lowered for k in ["review", "refactor", "clean code", "snippet"]):
                answer = safe_summarize_code(question)
                chosen = "CodeAgent"
            else:
                answer = safe_search_docs(question)
                chosen = "DocAgent"

        return AskResponse(
            ok=True,
            answer=answer,
            meta={
                "selected_agent": chosen,
                "coordinator": ROOT_AGENT.name,
                "note": "Demo implementation with safe tool routing",
            },
        )

    except ValidationError as ve:
        logger.exception("Validation error")
        raise HTTPException(status_code=422, detail=str(ve)) from ve
    except ValueError as ve:
        logger.warning("Tool rejected request: %s", ve)
        raise HTTPException(status_code=400, detail=str(ve)) from ve
    except HTTPException:
        raise
    except Exception as exc:  # catch-all untuk menjaga API tetap stabil
        logger.exception("Unexpected error: %s", exc)
        raise HTTPException(
            status_code=500,
            detail="Terjadi kesalahan internal. Coba lagi beberapa saat.",
        ) from exc

Jalankan server:

uvicorn main:app --reload --port 8080

Tes endpoint:

curl -X POST http://127.0.0.1:8080/ask \
  -H 'Content-Type: application/json' \
  -d '{"question":"Bagaimana menangani timeout pada API client FastAPI?","mode":"auto"}'

Contoh respons:

{
  "ok": true,
  "answer": "Checklist troubleshooting ...",
  "meta": {
    "selected_agent": "TroubleshootAgent",
    "coordinator": "Coordinator",
    "note": "Demo implementation with safe tool routing"
  }
}

Kenapa contoh ini tetap valid walau sederhana?

• Struktur parent/sub-agent sudah jelas
• Ada guardrails tool-level
• Ada error handling API-level
• Sudah siap ditingkatkan ke ADK runner/session yang lebih kompleks

---

6) Best Practices (industry tips)

1. Buat peran agent sangat sempit

   • Satu agent, satu tanggung jawab utama.
   • Ini menurunkan hallucination karena konteks lebih fokus.

2. Gunakan tool context untuk policy

   • Jangan biarkan model bebas menentukan batas akses.
   • Simpan policy deterministik dari developer.

3. Pisahkan “thinking” dan “acting”

   • Agent boleh menganalisis bebas.
   • Tapi aksi eksternal harus lewat tool tervalidasi.

4. Audit trail wajib

   • Simpan log: pertanyaan, agent terpilih, tool dipakai, hasil.
   • Penting untuk debugging dan compliance.

5. Fallback strategy

   • Jika sub-agent gagal, coordinator harus:
     • memberi respons aman,
     • atau minta klarifikasi,
     • atau eskalasi ke human.

6. Evaluation set dari kasus nyata

   • Jangan evaluasi pakai prompt “cantik” saja.
   • Pakai data error production, pertanyaan ambigu, typo user.

7. Batasi biaya token

   • Ringkas konteks,
   • set max output,
   • throttle request berat.

---

7) Common Mistakes

1. Semua tugas dilempar ke satu agent

Akibatnya: prompt jadi panjang, jawaban makin inkonsisten.

2. Tool terlalu powerful tanpa pembatasan

Contoh buruk: tool SQL tanpa whitelist tabel. Ini risk tinggi.

3. Tidak ada schema response

Kalau format respons tidak konsisten, frontend jadi rapuh. Gunakan Pydantic/JSON schema.

4. Mengabaikan error path

Banyak demo hanya fokus “happy path”. Di production, error path lebih sering terjadi.

5. Tidak versioning prompt/instruction

Instruction juga artefak software. Versioning itu wajib.

6. Over-parallelization

Menjalankan terlalu banyak agent paralel bisa bikin race condition state dan biaya melonjak.

---

8) Advanced Tips

1. Hybrid routing (rules + LLM)

   • Mulai dari rules deterministic untuk intent basic,
   • lalu pakai LLM untuk kasus ambigu.

2. Memory layering

   • Session memory (jangka pendek)
   • Domain memory (knowledge base)
   • Audit memory (untuk observability)

3. Safety callback dua tahap

   • Pre-tool callback: cek apakah aksi diizinkan
   • Post-tool callback: sanitasi output sebelum dikirim user

4. Canary deployment untuk prompt

   • Rollout instruction baru ke 5-10% traffic dulu.
   • Pantau regressions sebelum full rollout.

5. A2A (Agent-to-Agent) untuk sistem enterprise

   • Jika agent beda service/repo, gunakan protokol yang jelas untuk komunikasi antar-agent.

6. SLO khusus agent

   • Track latency p95, tool error rate, dan “successful resolution rate”.
   • Jangan cuma lihat akurasi model.

---

9) Summary & Next Steps

Kita sudah bahas end-to-end cara membangun multi-agent system modern dengan ADK:

• Kenapa multi-agent penting untuk aplikasi nyata
• Konsep hierarchy, orchestration, dan guardrails
• Arsitektur API yang clean
• Implementasi runnable dengan FastAPI + Python
• Best practices, pitfalls, dan strategi lanjutan

Next steps yang saya rekomendasikan:

1. Upgrade demo ini ke ADK runner/session penuh
2. Tambahkan evaluasi otomatis untuk 50+ test prompts
3. Integrasikan vector search untuk dokumen internal
4. Tambahkan authentication + rate limiting API
5. Deploy ke Cloud Run/Docker dengan observability (OpenTelemetry)

Kalau kamu bangun produk AI di 2026, pattern ini memberi fondasi yang kuat: modular, aman, dan maintainable.

---

10) References

• ADK Documentation: https://adk.dev/
• ADK Multi-Agent Systems: https://adk.dev/agents/multi-agents/
• ADK Safety & Security: https://adk.dev/safety/
• ADK Python Repo: https://github.com/google/adk-python
• ADK Java Repo: https://github.com/google/adk-java
• FastAPI Docs: https://fastapi.tiangolo.com/
• Uvicorn Docs: https://www.uvicorn.org/
• GitHub Trending (observasi topik): https://github.com/trending
• DEV Community: https://dev.to/
• Medium Programming: https://medium.com/tag/programming