# Tutorial Google ADK 2.0: Graph Workflow dan Multi-Agent

> Tutorial Google ADK 2.0 langsung praktik: membangun graph approval pengadaan dengan route dan persetujuan manusia, session yang tahan restart, memilih graph, dynamic atau collaborative workflow, testing, dan migrasi dari 1.x.

URL: https://www.matthewswong.com/id/blog/google-adk-2-graph-workflows-tutorial/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-10-01
- Updated: 2026-10-01
- Category: AI

> **Key takeaway:** Google ADK 2.0 menjadikan agent, tool, dan function sebagai node dalam sebuah workflow graph. Pakai graph Workflow ketika aturan routing sudah jelas, misalnya batas nominal approval, dan sisakan LLM untuk satu langkah yang memang butuh penilaian. Selalu petakan DEFAULT_ROUTE, karena route yang tidak cocok menghentikan run diam-diam tanpa error.

Versi pertama asisten pengadaan kami membiarkan model memutuskan siapa yang menyetujui pembelian. Model membaca permintaan, menebak rentang nominal, lalu transfer ke agent manajer atau direktur. Hasilnya benar hampir setiap kali, dan justru itu standar yang salah untuk aturan yang oleh tim finance sudah ditulis sebagai dua angka: di bawah 5 juta rupiah otomatis, di bawah 50 juta perlu manajer, di atas itu perlu direktur.

Tutorial Google ADK 2.0 ini membangun ulang alur tersebut di atas graph engine yang baru, di mana LLM hanya mengekstrak permintaan dan Python biasa yang mengurus routing. Semua snippet saya jalankan di google-adk 2.10.0 dengan Python 3.11, dengan intake agent diganti function stub supaya jalur deterministiknya bisa berjalan tanpa model. Bagian yang perilakunya mengejutkan saya tulis apa adanya; sisanya merujuk ke dokumentasi resmi ADK 2.0.

## Apa yang berubah di ADK 2.0: agent menjadi node

ADK 2.0 mengganti eksekusi agent yang hierarkis dengan graph engine. Agent, tool, dan function biasa semuanya adalah node, dan BaseAgent sekarang meng-extend BaseNode. Python mencapai GA pada 19 Mei 2026, Go pada 30 Juni 2026, dan TypeScript pada 21 Agustus 2026, dan sejak itu Python merilis versi minor kira-kira tiap dua minggu hingga 2.10.0 di akhir September. Rilis ini memberi tiga cara menyusun node.

| Jenis workflow | Cara menulisnya | Siapa yang menentukan langkah berikutnya | Cocok untuk |
| --- | --- | --- | --- |
| Graph workflow | Workflow dengan daftar edges dan route map | Kode Anda, lewat nilai route pada Event | Aturan yang bisa ditulis: batas nominal, status, pipeline tetap |
| Dynamic workflow | Async function dengan decorator node yang memanggil ctx.run_node | Kode Anda, dengan loop dan kondisi | Rantai dengan panjang bervariasi dan retry yang bikin graph berantakan |
| Collaborative workflow | Agent koordinator dengan sub_agents dalam mode chat, task, atau single_turn | Model koordinator, lewat delegation tool yang dibuat otomatis | Pekerjaan terbuka yang rencananya belum diketahui di awal |

Pertanyaan untuk memilih barisnya sederhana: apakah analis junior bisa menjalankan aturannya dari kebijakan tertulis? Kalau bisa, tempatnya di graph atau dynamic workflow, dan bukan model yang memilih cabangnya. Batas nominal approval lolos tes ini, jadi masuk ke kode. Mengubah pesan yang samar menjadi vendor, nominal, dan cost center tidak lolos, jadi langkah itu tetap di model.

## Tutorial Google ADK 2.0: graph approval pengadaan

Seluruh kebijakan muat dalam satu Workflow. Daftar edges dibaca dari atas ke bawah: START masuk ke intake agent, output terstrukturnya masuk ke router nominal, dan setiap nilai route dipetakan ke satu cabang. Semua cabang approval bertemu di router kedua yang memisahkan disetujui dan ditolak.

Tiga detail menopang desain ini. Intake agent memakai output_schema, sehingga router menerima PurchaseRequest yang sudah tervalidasi, bukan prosa. ADK meng-coerce setiap node_input ke type annotation parameternya, itu sebabnya sebuah node boleh mengembalikan dict biasa dan node berikutnya tetap menerima model. Lalu route_by_amount menulis permintaan ke ctx.state, sehingga create_po bisa membaca vendor dua langkah kemudian tanpa harus mengopernya lewat setiap return value.

> Uji graph-nya tanpa model terlebih dulu. Saya mengganti intake_agent dengan function lima baris yang mem-parse JSON menjadi PurchaseRequest, lalu menjalankan ketiga rentang lewat Runner: 1,2 juta disetujui otomatis, 12 juta berhenti di node manajer, 80 juta berhenti di node direktur. Node tetaplah node, jadi stub-nya masuk ke daftar edges yang sama.

## Menunggu manusia dengan RequestInput

Manajer tidak menjawab dalam hitungan milidetik, jadi node approval tidak boleh blocking. Yield RequestInput mengakhiri run saat itu dan mengirim event berisi function call bernama adk_request_input, membawa pesan, payload Anda, dan interrupt id yang juga tercantum di long_running_tool_ids. Untuk melanjutkan, kirim function response dengan id tersebut ke session yang sama.

- Balasan diteruskan ke node penerus, bukan ke node yang berhenti, jadi manager_approval tidak pernah berjalan dua kali. Itulah perilaku default function node, yang rerun_on_resume-nya false.
- response_schema ditegakkan saat balasan masuk. Balasan dengan approved bernilai maybe membuat run_async melempar WorkflowDataError berisi error Pydantic, jadi bungkus pemanggilan resume dan kirim error-nya kembali ke UI approval Anda.
- Nilai default tidak bertahan dalam perjalanan pulang-pergi. Model Decision pertama saya punya note bertipe str dengan default string kosong; nilai yang di-resume membawa note sebagai None, dan decision_router yang ber-annotation gagal dengan event ValidationError. Mendeklarasikan note sebagai optional dengan default None memperbaikinya.

## Route yang tidak dipetakan menghentikan run diam-diam

Inilah kegagalan yang paling saya harap ada orang yang memperingatkan sebelumnya. Ketika router mengembalikan nilai route yang bukan key di map-nya, ADK tidak melempar exception dan tidak mengirim event error. Event output router muncul, lalu run langsung berakhir. Dalam pengujian saya mengembalikan nilai yang tidak dipetakan dan hanya mendapat satu event.

> Classifier LLM yang menjawab Manager alih-alih MANAGER, atau tier approval keempat yang ditambahkan ke router tetapi lupa ditambahkan ke map, akan membuang permintaan tanpa suara. Petakan DEFAULT_ROUTE, di-import dari google.adk.workflow, di setiap route dictionary dan arahkan ke tempat yang dipantau manusia. Dengan default terpasang, nilai yang sama menjalankan node fallback sesuai harapan.

## Session yang bertahan setelah restart

Jeda hanya berguna kalau jedanya lebih awet daripada prosesnya. InMemorySessionService kehilangan semuanya saat restart, jadi production butuh DatabaseSessionService. Saya membuat session, menjalankannya sampai interrupt manajer, lalu membuat service dan Runner baru di file SQLite yang sama dan mengirim approval. Workflow melanjutkan di record_decision dengan data permintaan masih ada di state.

Sampai ke sana saya terjebak satu error yang menyesatkan. Extra db meng-install SQLAlchemy, yang ter-resolve ke 2.1.1, dan layer asyncio di rilis itu butuh greenlet, yang tidak ikut ter-install. ADK hanya melaporkan gagal membuat database engine; penyebab sebenarnya adalah ImportError di bawahnya. Meng-install greenlet menyelesaikannya. Baris event juga menunjukkan kenapa custom session store rusak di 2.0: node_info dan output sekarang ada di setiap event yang disimpan, dan validator yang menolak property tak dikenal akan menolaknya.

## Saat graph kurang cocok: dynamic dan collaborative workflow

Matriks approval sungguhan jarang hanya tiga kotak tetap. Di atas 500 juta rupiah rantai kami menambah CFO, dan menggambar graph untuk setiap panjang rantai cepat jadi berantakan. Dynamic workflow menuliskannya sebagai loop, dengan setiap approval didelegasikan ke child node lewat ctx.run_node.

Trace di komentar itu berasal dari run sungguhan, dan itulah yang perlu dipahami: setiap kali resume, body orchestrator mulai lagi dari atas, dan child yang sudah selesai mengembalikan jawaban tersimpan alih-alih berhenti lagi. Checkpoint-nya ada di child. Apa pun yang punya side effect, seperti email, penulisan ke ERP, atau counter, harus menjadi node tersendiri, kalau tidak ia akan terpicu sekali per resume. Ketika pekerjaannya sendiri terbuka, seperti mencari vendor dan mengumpulkan penawaran, koordinator dengan subagent lebih cocok.

- chat adalah mode default: subagent berbicara dengan user dan harus mengembalikan kontrol secara eksplisit.
- task boleh mengajukan pertanyaan klarifikasi dan kembali otomatis saat selesai. Mode ini tidak boleh punya subagent sendiri dan dinonaktifkan di dalam graph workflow pada Python 2.0.
- single_turn tidak mengizinkan interaksi dengan user, langsung kembali, dan merupakan satu-satunya mode yang bisa berjalan paralel.

Koordinator mendapat satu tool yang dibuat otomatis per subagent, dinamai sesuai subagent-nya, dan agent dengan mode task dan single_turn berjalan di cabang session yang terisolasi, sehingga sibling paralel tidak bisa melihat pekerjaan satu sama lain. Jangan pasang mode pada root agent. Model yang memilih subagent mana yang dipanggil, dan justru karena itu approval tetap di graph sementara sourcing ada di sini.

## Menguji graph dan mengevaluasi agent

Bagi pengujian di garis yang sama dengan desainnya. Node deterministik adalah function Python biasa, jadi uji dengan pytest tanpa API key. Satu-satunya node yang memakai model adalah tempat adk eval berguna: tool_trajectory_avg_score membandingkan tool call dengan daftar yang diharapkan, dan response_match_score membandingkan jawaban akhir.

Kriteria trajectory secara default memakai threshold 1.0 dengan exact match, artinya tidak boleh ada call yang berlebih atau hilang. IN_ORDER menerima call tambahan di antara call yang diharapkan, dan ANY_ORDER mengabaikan urutan, jadi pilih mode paling longgar yang masih menangkap regresi yang Anda pedulikan. response_match_score default-nya 0.8. Untuk intake agent, yang penting adalah agent tidak pernah melewatkan pencarian vendor, jadi IN_ORDER adalah setelan yang jujur.

## Migrasi dari ADK 1.x tanpa merusak session

Sebagian besar agent 1.x tetap jalan, tetapi empat perubahan ini yang sering menggigit dalam praktik.

1. Perbarui custom session store dan validator JSON yang ketat untuk field Event baru: node_info, output, route, dan isolation scope di semua bahasa, ditambah RequestedInput di Go.
2. Di Python, override _run_async_impl dilewati. Pindahkan logikanya ke callback before dan after agent, yield event alih-alih menambahkan langsung ke context.session.events, dan berhenti menangkap BaseException supaya retry bisa bekerja.
3. Di Go, ganti module path menjadi google.golang.org/adk/v2 dan berikan context sebagai argumen pertama session.NewEvent.
4. Di TypeScript, SequentialAgent, ParallelAgent, dan LoopAgent sudah deprecated dan digantikan graph workflow, dan InvocationContext.agent sekarang bisa undefined.

> ADK open source dengan lisensi Apache 2.0, tersedia sebagai google-adk di PyPI dan @google/adk di npm, plus port untuk Go, Java, dan Kotlin. Untuk session store berbasis database yang sudah ada, adk migrate session menyalin database sumber ke URL tujuan dengan versi schema terbaru.

Aturan yang saya bawa dari pembangunan ulang ini: biarkan model membaca, biarkan kode memutuskan. Di ADK 2.0 bentuknya adalah Workflow yang satu-satunya node LLM-nya mengubah teks menjadi schema, dengan setiap batas nominal berada di route map yang punya DEFAULT_ROUTE. Simpan session di database sebelum jeda manusia pertama, dan taruh side effect di child node supaya resume tidak mengulanginya.

## Sumber

- Ringkasan ADK 2.0, tanggal rilis, dan catatan migrasi (adk.dev)
- Graph-based agent workflow (adk.dev)
- Human input di workflow: RequestInput (adk.dev)
- Collaborative workflow dan mode subagent (adk.dev)
- Kriteria evaluasi: tipe match tool trajectory (adk.dev)

## Source links

- https://adk.dev/2.0/
- https://adk.dev/graphs/
- https://adk.dev/graphs/human-input/
- https://adk.dev/workflows/collaboration/
- https://adk.dev/evaluate/criteria/

## FAQ

### Apa yang baru di Google ADK 2.0?

ADK 2.0 mengganti eksekusi agent yang hierarkis dengan graph engine, di mana agent, tool, dan function semuanya adalah node, dan BaseAgent sekarang meng-extend BaseNode. Rilis ini menambahkan graph-based, dynamic, dan collaborative workflow. Python mencapai GA pada 19 Mei 2026, Go pada 30 Juni 2026, dan TypeScript pada 21 Agustus 2026.

### Kapan sebaiknya memakai graph workflow daripada membiarkan LLM melakukan routing?

Pakai graph workflow setiap kali aturan routing bisa ditulis, misalnya batas nominal approval, status dokumen, atau pipeline tetap. Sisakan model untuk langkah yang butuh penilaian, seperti mengubah permintaan berbentuk teks bebas menjadi field terstruktur. Route yang deterministik bisa diuji dengan pytest biasa dan tidak berubah-ubah antar run.

### Bagaimana cara menjeda workflow ADK 2.0 untuk approval manusia?

Yield RequestInput dari function node dengan message, payload opsional, dan response_schema opsional. Run berakhir dengan function call adk_request_input yang membawa interrupt id. Lanjutkan dengan mengirim function response ber-id sama ke session yang sama, dan balasannya menjadi input node berikutnya.

### Apa yang terjadi jika router ADK mengembalikan route yang tidak dipetakan?

Di google-adk 2.10.0 run langsung berakhir setelah event output router, tanpa exception dan tanpa event error. Tambahkan DEFAULT_ROUTE dari google.adk.workflow ke setiap route map dan arahkan ke node fallback yang dipantau manusia. Cara ini menangkap perbedaan huruf besar-kecil dari classifier LLM maupun tier baru yang ditambahkan.

### Apa saja yang rusak saat migrasi dari ADK 1.x ke 2.0?

Custom session store dan validator yang ketat harus menerima field Event baru seperti node_info dan output. Di Python, override _run_async_impl dilewati dan diganti callback, sedangkan di Go import path pindah ke google.golang.org/adk/v2 dan NewEvent menerima context sebagai argumen pertama. TypeScript men-deprecate SequentialAgent, ParallelAgent, dan LoopAgent.

---

- HTML version: https://www.matthewswong.com/id/blog/google-adk-2-graph-workflows-tutorial/
- English: https://www.matthewswong.com/en/blog/google-adk-2-graph-workflows-tutorial/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
