Cara Mengarahkan Tugas AI Agent dengan Gemini Decisions API

TL;DR

Untuk merutekan tugas AI agent menggunakan Gemini Decisions API, kirimkan judul dan deskripsi tugas ke gemini-decision-1 disertai tiga pertanyaan: choice untuk memilih Agent mana yang akan mengerjakannya, score untuk mengukur tingkat kesulitannya, dan noul untuk memastikan apakah manusia perlu mengambil keputusan terlebih dahulu. Tetapkan tugas secara otomatis saat tingkat keyakinan (confidence) melampaui ambang batas yang Anda tentukan. Tahan sisanya untuk ditinjau langsung oleh manusia.

Pendahuluan

Setiap tim yang menjalankan beberapa coding agent pasti berhadapan dengan rutinitas yang sama: seseorang harus membaca setiap tugas baru dan memutuskan siapa yang harus mengerjakannya. Agent backend atau frontend? Model yang hemat biaya atau model yang bertenaga besar? Sudah siap dikerjakan, atau masih menunggu keputusan?

Google meluncurkan alat khusus untuk mengatasi rutinitas tersebut pada 11 November 2026. Gemini Decisions API menjawab pertanyaan tertutup menggunakan probabilitas terkalibrasi alih-alih teks tergenerasi. Google memanfaatkannya di dalam Gemini Notebook untuk mengarahkan setiap kueri ke tingkatan model dan level berpikir (thinking level) yang tepat, dan melaporkan bahwa langkah ini mampu memangkas latensi kueri harian hingga 40%.

Artikel ini membahas cara membangun router serupa untuk board agent: satu panggilan API per tugas, tiga pertanyaan, satu ambang batas, dan serah terima yang mulus ke manusia saat router ragu. Jika Anda membutuhkan board untuk mengujinya, Sharkly dapat digunakan secara gratis untuk memulai. Untuk kebijakan perutean itu sendiri (tugas mana saja yang memerlukan model tingkat lanjut), silakan baca panduan merutekan tugas agent berdasarkan tingkat kesulitan terlebih dahulu. Artikel ini berfokus pada panggilan API yang menerapkan kebijakan tersebut.

Cara kerja Gemini Decisions API

Gemini Decisions API adalah sebuah endpoint yang mengevaluasi pertanyaan berstruktur tipe terhadap input bersama, lalu mengembalikan nilai probabilitas dan skor keyakinan untuk masing-masing pertanyaan. Endpoint ini tidak menghasilkan teks sama sekali, sehingga token output selalu nol. Kode Anda dapat langsung melakukan percabangan logika berdasarkan angka tersebut tanpa tahap parsing.

Ada tiga tipe pertanyaan yang mencakup kebutuhan perutean:

Satu permintaan dapat memuat hingga 1.000 pertanyaan terhadap input yang sama. Berdasarkan dokumentasi Decisions API, seluruh pertanyaan diproses dalam satu forward pass dan saling terisolasi (tidak dapat melihat satu sama lain), sehingga penambahan pertanyaan baru tidak akan mengubah hasil jawaban lainnya. Google menyatakan bahwa latensi end-to-end berada di kisaran 150 hingga 250 ms, relatif konstan dari rentang 1 hingga 100 pertanyaan.

Jika Anda pernah membaca artikel kami tentang Jev dan model keputusan di atas coding agent, arsitektur ini tentu sudah tidak asing lagi. Perbedaan utamanya bersifat praktis: model yang di-host langsung oleh Google, tiga pertanyaan yang terdefinisi jelas, dan integrasi langsung ke board manajemen tugas.

Panggilan perutean: tiga pertanyaan per tugas

Berikut adalah implementasi routernya. Dibutuhkan pustaka google-genai versi 3.2 atau lebih baru serta GEMINI_API_KEY dari Google AI Studio.

import json
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

AGENTS = {
    "backend": "Server code, APIs, database migrations, and backend tests.",
    "frontend": "UI components, styling, client state, and frontend tests.",
    "docs": "README files, docs pages, and changelogs. No code changes.",
    "other": "Work that fits none of the options above.",
}

DIFFICULTY = [
    "Trivial: one file, obvious change, no design decision.",
    "Routine: a few files, follows a pattern already in the repo.",
    "Involved: several modules or a new pattern, needs new tests.",
    "Hard: cross-cutting, touches auth or data migrations, or the spec is thin.",
]

def ask(task):
    state = json.dumps({
        "title": task["title"],
        "description": task["description"][:8000],
    })
    result = client.decisions.create(
        model="gemini-decision-1",
        input=state,
        questions={
            "agent": {
                "type": "choice",
                "instructions": "Which agent should take the task in `title` and `description`?",
                "criteria": AGENTS,
            },
            "difficulty": {
                "type": "score",
                "instructions": "How hard is this task for a coding agent working alone?",
                "criteria": DIFFICULTY,
            },
            "needs_human": {
                "type": "noul",
                "instructions": "Does a person need to make a decision before any agent starts?",
                "criteria": {
                    "true_description": "The spec is ambiguous, contradicts itself, or asks for a product, security, or pricing call.",
                    "false_description": "The spec is clear enough to implement as written.",
                },
            },
        },
    )
    return result.answers

Ada empat detail penting pada kode di atas yang berasal langsung dari dokumentasi resmi dan kerap terlewatkan.

Model tidak pernah melihat key kamus Anda. Model hanya membaca instructions dan criteria, jadi tuliskan pertanyaan selengkapnya di dalam instructions dan jelaskan setiap opsi secara mendalam.

Kunci opsi diurutkan berdasarkan abjad. API mengurutkan kunci opsi pilihan berdasarkan urutan bita UTF-8 sebelum memberikan skor. Karena itulah opsi penampung akhir dinamai other dan bukan none_of_the_above, yang mana nama tersebut akan terurut mendahului opsi-opsi sebenarnya.

Tingkatan skor harus bersifat linier. Nilai score yang dikembalikan adalah rata-rata terbobot probabilitas dari indeks tingkatan, yaitu antara 0 hingga 3 dalam contoh ini. Pastikan tingkatan yang bersebelahan memiliki batas kriteria yang kontras dan jelas.

Kirimkan informasi yang relevan saja. Dokumentasi menyatakan bahwa konteks yang tidak relevan dapat menurunkan akurasi. Judul dan deskripsi tugas biasanya jauh lebih efektif daripada menyertakan seluruh riwayat komentar.

Menentukan ambang batas keyakinan dari tugas Anda sendiri

Nilai jawaban memberi tahu apa langkah yang harus diambil, sedangkan nilai keyakinan (confidence) menentukan apakah langkah tersebut aman dijalankan secara otomatis tanpa intervensi. Untuk jawaban bertipe choice, keyakinan sama dengan probabilitas opsi teratas. Untuk noul, nilainya adalah max(noul, 1 - noul).

Berikut adalah logika lapisan keputusannya:

AUTO = 0.75      # assign without a person above this
HARD = 2.4       # difficulty score that earns the strong-model Agent

def decide(a):
    if a["needs_human"].noul >= 0.5:
        return ("human", "needs a decision first")
    if a["agent"].choice == "other" or a["agent"].confidence < AUTO:
        return ("human", f"router unsure ({a['agent'].confidence:.2f})")
    tier = "strong" if a["difficulty"].score >= HARD else "default"
    return (f"{a['agent'].choice}-{tier}", "auto")

Jangan menyalin angka 0.75 begitu saja. Saran resmi Google adalah menentukan ambang batas berdasarkan contoh tugas nyata yang telah berlabel dari alur kerja Anda sendiri. Ambil 50 hingga 100 tugas terakhir yang sudah selesai, catat Agent mana yang menuntaskannya, lalu jalankan melalui fungsi ask(). Pilih ambang batas terendah di mana hasil perutean otomatis tetap sejalan dengan keputusan tim Anda. Kesalahan rute otomatis berakibat pada kegagalan eksekusi dan penugasan ulang; sedangkan penahanan tugas ke manusia hanya memakan waktu beberapa menit. Timbang kedua risiko ini secara bijak, bukan sekadar memilih angka bulat acak.

Ada dua jebakan yang patut diwaspadai: Probabilitas noul tidak pernah melampaui 0.99, sehingga kondisi seperti > 0.99 tidak akan pernah terpenuhi. Selain itu, score bernilai 1.5 bisa berarti “terbagi antara level 1 dan 2” atau “tidak yakin di antara keempat level.” Saat akurasi mutlak diperlukan, periksa pula nilai probabilities-nya.

Menghubungkan router ke board Sharkly

Router ini ditulis dalam Python murni, sehingga fleksibel dijalankan di mana saja. Pada board Sharkly, pemicu paling ideal adalah momen ketika sebuah tugas beralih ke status siap dikerjakan (ready).

1. Buat satu Agent untuk setiap lajur dan tingkatan model. Contohnya backend-default, backend-strong, frontend-default. Berdasarkan dokumentasi Sharkly Agents, setiap Agent secara bawaan mengikuti model Runtime-nya, dan kolom Model memungkinkan Anda memilih model lain dari katalog Runtime tersebut. Di sinilah tingkat kesulitan tugas dipetakan langsung ke pemilihan model.

2. Eksekusi keputusan menggunakan CLI sharkly.

import subprocess

def apply(task_id, target, reason, a):
    note = (f"Router: agent={a['agent'].choice} ({a['agent'].confidence:.2f}), "
            f"difficulty={a['difficulty'].score:.1f}, "
            f"needs_human={a['needs_human'].noul:.2f}")
    if target == "human":
        subprocess.run(["sharkly", "task", "comment", task_id,
                        "--body", f"{note}. Held for a person: {reason}."], check=True)
        return
    subprocess.run(["sharkly", "task", "edit", task_id,
                    "--delegate-agent", target], check=True)
    subprocess.run(["sharkly", "task", "comment", task_id, "--body", note], check=True)

Menugaskan Agent akan langsung memulai eksekusinya begitu tugas berada dalam status siap. Menuliskan angka probabilitas ke dalam komentar sangat krusial: ini menjadi jejak audit berharga untuk mengevaluasi kinerja router di kemudian hari.

3. Picu melalui perubahan status tugas. Fitur Automation pada Sharkly menyimpan instruksi, penugasan Agent, dan pemicu. Berikan Router Agent instruksi singkat: “jalankan route.py pada tugas yang memicumu”, lalu tambahkan pemicu status tugas untuk status yang mewakili “Ready”. Riwayat eksekusi yang dimulai dari pemicu status tugas akan otomatis terhubung ke tugas bersangkutan, sehingga dokumentasi perutean tersimpan rapi bersama pekerjaannya. Perintah melalui CLI:

sharkly automation trigger create <automation-id> --kind task_event --to-status "Ready"

Estimasi biaya panggilan perutean

Gemini Decision 1 mematok tarif $0,10 per 1 juta token input dan $0 untuk output, sebagaimana tertera pada pengumuman resmi Google. Input bersama hanya dihitung satu kali per permintaan, terlepas dari berapa banyak pertanyaan yang diajukan.

Biaya menjalankan router ini bahkan lebih murah dibanding satu sesi eksekusi agent untuk satu tugas. Google AI Studio juga menyediakan kuota tingkat gratis (no-cost tier) untuk kebutuhan uji coba dan pembuatan prototipe.

Batasan penting sebelum mengandalkannya

API ini dirilis dalam versi v1beta di Gemini Developer API, sementara dukungan Gemini di Google Cloud tercatat berstatus “segera hadir”. Dokumentasi resmi menyebutkan bahwa endpoint ini belum mendukung context caching, Batch API, maupun inferensi tingkat Flex dan Priority, sehingga input berulang akan dihitung penuh setiap kali dipanggil. Batasan kuota (rate limit) per tingkatan dapat dilihat di laman rate limits Google; pastikan untuk memeriksanya sebelum mengalirkan seluruh lalu lintas tugas melalui satu kunci API.

Perlakukan deskripsi tugas sebagai input yang belum terpercaya. Dokumentasi memperingatkan bahwa teks yang disediakan pengguna dapat memengaruhi atau memanipulasi klasifikasi dirinya sendiri. Jika ada pihak di luar tim Anda yang dapat membuat tiket tugas, selalu alihkan tugas yang menyentuh ranah autentikasi, pembayaran, atau data produksi ke pemeriksaan manual manusia, apa pun rekomendasi router.

Klaim benchmark Google (tingkat kesalahan kalibrasi terendah di kelasnya, hampir 5x lebih hemat dibanding Gemini 3.5 Flash-Lite melalui Interactions API) adalah angka pengujian pihak Google. Data tugas nyata berlabel dari tim Anda sendirilah yang menjadi tolok ukur paling valid.

Kapan panggilan perutean bukan pilihan yang tepat

Gunakan panggilan Decisions API jika volume tugas masuk melampaui kapasitas triase manual manusia dan opsi tujuannya bersifat tetap: daftar Agent tertentu, tingkatan model tertentu, atau gerbang keputusan ya/tidak. Namun, gunakan aturan berbasis kode sederhana jika sudah ada label yang menentukannya secara langsung. Jika semua tugas berlabel docs selalu diserahkan ke Agent dokumentasi, percabangan logika if biasa jauh lebih cepat, hemat biaya, dan tidak akan pernah salah.

Beralihlah ke model generatif konvensional jika Anda memerlukan router yang mampu memberikan alasan tertulis dalam bahasa natural, menulis ulang spesifikasi tugas, atau memecah tugas menjadi beberapa sub-tugas. Decisions API mengembalikan angka probabilitas, bukan teks bebas. Untuk delegasi pekerjaan yang melibatkan banyak peran, arsitektur Crew dengan pemimpin tim yang memecah target kerja jauh lebih cocok; silakan pelajari perutean model untuk agent Crew.

Kesimpulan

Perutean tugas pada dasarnya adalah pengambilan keputusan berbasis pilihan tertutup (closed-set), dan Gemini Decisions API memang dirancang khusus untuk skenario tersebut: satu panggilan efisien, jawaban bertipe tegas, skor keyakinan yang dapat diatur ambang batasnya, serta biaya operasional yang hanya sepersekian sen. Tugas yang tersisa ada di tangan Anda: susun deskripsi opsi yang jelas, kalibrasi ambang batas dengan riwayat tugas tim Anda, dan serahkan kasus-kasus berkeyakinan rendah kepada manusia.

Mulailah dari satu alur kerja terlebih dahulu. Rutekan tugas-tugas backend baru selama seminggu, bandingkan pilihan router dengan keputusan riil tim Anda, lalu perluas penerapannya secara bertahap. Untuk menjalankan router ini langsung di board terpadu yang memadukan Agent, Automation, dan peninjauan manual oleh manusia, mulai gunakan Sharkly hari ini.

Tanya Jawab (FAQ)

Apa itu Gemini Decisions API?

Gemini Decisions API adalah endpoint API Gemini yang diluncurkan pada 11 November 2026 untuk menjawab pertanyaan bertipe ya/tidak, pilihan ganda, dan penilaian skor terhadap input teks, gambar, audio, video, atau dokumen PDF. Endpoint ini memanfaatkan model gemini-decision-1 untuk menghasilkan probabilitas terkalibrasi dan skor keyakinan alih-alih teks tergenerasi.

Berapa biaya penggunaan Gemini Decision 1?

Google menetapkan harga $0,10 per 1 juta token input dan $0 untuk token output, dengan input bersama hanya ditagih satu kali per permintaan. Google AI Studio juga menyediakan kuota tanpa biaya untuk eksplorasi dan pembuatan prototipe.

Berapa banyak pertanyaan yang dapat diajukan dalam satu permintaan?

Antara 1 hingga 1.000 pertanyaan, selama berada dalam batas jendela konteks 262.144 token untuk input beserta seluruh pertanyaan. Untuk pertanyaan bertipe pilihan (choice), sistem mendukung 2 hingga 255 opsi jawaban.

Berapa ambang batas keyakinan (confidence threshold) yang ideal untuk perutean?

Tidak ada satu angka baku yang berlaku universal. Google menyarankan untuk mengkalibrasi ambang batas menggunakan contoh data berlabel dari aktivitas kerja Anda sendiri. Uji ulang pada 50 hingga 100 tugas yang telah selesai, lalu pilih ambang batas di mana keputusan otomatis cocok dengan keputusan tim Anda.

Bisakah Decisions API menentukan model yang digunakan oleh agent?

Secara tidak langsung, ya. Anda dapat mengajukan pertanyaan bertipe score untuk mengukur kompleksitas tugas, kemudian memetakan skor tinggi ke Agent yang dikonfigurasikan dengan model berkinerja lebih tinggi. Di Sharkly, setiap Agent dapat diarahkan ke model tertentu dari katalog Runtime-nya.

Apakah Gemini Decisions API sudah tersedia di Vertex AI?

Belum saat ini. Google menyatakan bahwa integrasi Gemini di Google Cloud akan segera hadir. Saat ini endpoint tersebut beroperasi melalui Gemini Developer API dalam versi v1beta.