OpenAI Agents SDK: Membangun Sistem Multi-Agent dengan Handoff dan Guardrail
Halo temen-temen, kali ini kita bahas OpenAI Agents SDK, framework ringan untuk membangun aplikasi berbasis agent. Kalau kalian pernah mencoba LangChain atau CrewAI dan merasa abstraksinya terlalu tebal sampai susah di-debug, SDK ini menawarkan pendekatan yang jauh lebih sederhana dengan konsep yang sedikit tapi cukup.
Yang aku suka dari SDK ini adalah dia hanya punya empat primitif utama. Tidak ada belasan kelas abstrak yang harus kalian hafal. Kalian menulis fungsi Python biasa, membungkusnya jadi agent, dan sistemnya berjalan. Karena sedikit abstraksinya, saat ada yang salah kalian bisa langsung melihat penyebabnya, bukan menelusuri lima lapis wrapper.
Di tutorial ini kita bahas empat primitif itu, instalasi, agent pertama, tool, output terstruktur, handoff antar-agent, guardrail untuk keamanan, tracing untuk debugging, sampai membangun sistem customer service multi-agent yang lengkap.
Introduction
Empat Primitif
Agents adalah model bahasa yang diberi instruksi dan sekumpulan tool. Ini unit dasarnya.
Handoffs memungkinkan sebuah agent menyerahkan percakapan ke agent lain yang lebih spesialis. Ini cara SDK ini melakukan orkestrasi multi-agent, dan menurutku pendekatannya lebih elegan daripada framework lain karena handoff itu sendiri diperlakukan sebagai tool.
Guardrails adalah pemeriksaan yang berjalan paralel dengan agent, biasanya untuk memvalidasi input atau output. Kalau pemeriksaan gagal, eksekusi dihentikan lebih awal sebelum kalian membakar biaya atau menghasilkan sesuatu yang tidak diinginkan.
Sessions menangani riwayat percakapan secara otomatis, sehingga kalian tidak perlu mengelola daftar pesan secara manual antar giliran.
Di atas semuanya ada tracing yang aktif secara default, yang menurutku fitur paling underrated di SDK ini. Setiap jalannya agent tercatat lengkap, jadi debugging jadi jauh lebih manusiawi.
Kapan Memakai Ini
SDK ini cocok kalau kalian ingin membangun agent produksi dengan abstraksi minimal, kalau kalian butuh alur di mana beberapa spesialis menangani jenis permintaan berbeda, atau kalau kalian menghargai kemampuan debugging lebih daripada kekayaan fitur.
Perlu dicatat, meskipun namanya OpenAI, SDK ini mendukung banyak provider model lewat antarmuka yang kompatibel, jadi kalian tidak terkunci selamanya.
Instalasi
python -m venv venv
source venv/bin/activate # Linux / Mac
venv\Scripts\activate # Windows
pip install openai-agents
Set kunci API kalian:
export OPENAIAPIKEY="sk-..."
Agent Pertama
from agents import Agent, Runner
agent = Agent(
name="Asisten Riset",
instructions=(
"Kamu asisten riset yang teliti. Jawab dengan ringkas dan berbasis fakta. "
"Kalau kamu tidak yakin, katakan tidak yakin, jangan mengarang."
),
model="gpt-4o-mini",
)
hasil = Runner.runsync(agent, "Jelaskan perbedaan antara SSD SATA dan NVMe dalam tiga poin.")
print(hasil.finaloutput)
Untuk lingkungan async, yang biasanya kalian pakai di produksi:
import asyncio
from agents import Agent, Runner
async def main():
agent = Agent(name="Asisten", instructions="Kamu asisten yang membantu.")
hasil = await Runner.run(agent, "Halo, apa kabar?")
print(hasil.finaloutput)
asyncio.run(main())
Instruksi adalah system prompt agent kalian. Tulis dengan spesifik, termasuk apa yang boleh dan tidak boleh dilakukan. Instruksi yang kabur menghasilkan agent yang perilakunya tidak konsisten.
Menambahkan Tool
Tool adalah cara agent kalian berinteraksi dengan dunia nyata.
from agents import Agent, Runner, functiontool
import httpx
@functiontool
def cekstok(kodeproduk: str) -> dict:
"""Cek ketersediaan stok sebuah produk di gudang.
Args:
kodeproduk: kode SKU produk, contoh 'SKU-1234'
"""
# Di dunia nyata ini query ke database
gudang = {
"SKU-1234": {"nama": "Keyboard Mekanik", "stok": 42, "lokasi": "Jakarta"},
"SKU-5678": {"nama": "Mouse Wireless", "stok": 0, "lokasi": "Surabaya"},
}
return gudang.get(kodeproduk, {"error": "produk tidak ditemukan"})
@functiontool
def hitungongkir(kotaasal: str, kotatujuan: str, beratkg: float) -> dict:
"""Hitung estimasi ongkos kirim antar kota.
Args:
kotaasal: nama kota pengirim
kotatujuan: nama kota penerima
beratkg: berat paket dalam kilogram
"""
tarifdasar = 12000
biaya = tarifdasar * max(1, round(beratkg))
return {"biaya": biaya, "estimasihari": 3}
agent = Agent(
name="Asisten Penjualan",
instructions=(
"Kamu asisten penjualan. Gunakan tool untuk mengecek stok dan menghitung ongkir. "
"Jangan pernah mengarang angka stok atau harga."
),
tools=[cekstok, hitungongkir],
)
hasil = Runner.runsync(
agent,
"Saya mau beli SKU-1234 dikirim ke Bandung, beratnya 2 kg. Ada stok? Berapa ongkirnya?",
)
print(hasil.finaloutput)
Sama seperti di FastMCP, docstring dan type hints adalah antarmuka yang dibaca model. Tulis dengan jelas, sebutkan format yang diharapkan, dan pakai tipe yang spesifik.
Perhatikan juga instruksi "jangan pernah mengarang angka". Ini penting. Tanpa instruksi eksplisit, model kadang menjawab dari pengetahuan umumnya alih-alih memanggil tool.
Output Terstruktur
Untuk integrasi dengan sistem lain, kalian butuh output yang bisa diparsing, bukan teks bebas.
from pydantic import BaseModel
from typing import Literal
from agents import Agent, Runner
class AnalisisTiket(BaseModel):
kategori: Literal["billing", "teknis", "akun", "lainnya"]
urgensi: Literal["rendah", "sedang", "tinggi", "kritis"]
ringkasan: str
perlueskalasi: bool
alasan: str
agent = Agent(
name="Penganalisis Tiket",
instructions="Analisis tiket support dan klasifikasikan dengan tepat.",
outputtype=AnalisisTiket,
)
hasil = Runner.runsync(
agent,
"Server produksi down sejak 20 menit lalu, semua transaksi gagal, "
"klien sudah menelepon tiga kali.",
)
analisis = hasil.finaloutput
print(analisis.kategori) # teknis
print(analisis.urgensi) # kritis
print(analisis.perlueskalasi) # True
print(type(analisis)) # AnalisisTiket
Hasilnya adalah objek Pydantic yang sudah tervalidasi, bukan string yang harus kalian parsing sendiri. Ini membuat integrasi ke sistem tiket atau database jadi jauh lebih aman.
Handoff: Orkestrasi Multi-Agent
Ini fitur yang membuat SDK ini menarik. Alih-alih satu agent raksasa dengan tiga puluh tool, kalian membuat beberapa spesialis dan satu agent penyalur.
from agents import Agent, Runner, functiontool
@function
tool
def cektagihan(idpelanggan: str) -> dict:
"""Ambil status tagihan pelanggan."""
return {"id": idpelanggan, "tagihan": 450000, "status": "belum dibayar",
"jatuhtempo": "2026-09-20"}
@functiontool
def restartlayanan(idlayanan: str) -> dict:
"""Restart layanan pelanggan yang bermasalah."""
return {"id": idlayanan, "status": "restart berhasil", "waktu": "12 detik"}
agentbilling = Agent(
name="Spesialis Billing",
handoffdescription="Menangani pertanyaan tagihan, pembayaran, dan invoice.",
instructions=(
"Kamu spesialis billing. Bantu pelanggan soal tagihan dan pembayaran. "
"Selalu cek data tagihan sebelum menjawab nominal."
),
tools=[cektagihan],
)
agentteknis = Agent(
name="Spesialis Teknis",
handoffdescription="Menangani masalah teknis, gangguan layanan, dan error.",
instructions=(
"Kamu spesialis teknis. Bantu pelanggan menyelesaikan gangguan layanan. "
"Tanyakan detail gejala sebelum melakukan tindakan."
),
tools=[restartlayanan],
)
agentpenyalur = Agent(
name="Customer Service",
instructions=(
"Kamu petugas customer service lini pertama. "
"Sapa pelanggan dengan ramah, pahami masalahnya, lalu serahkan ke spesialis "
"yang tepat. Jangan mencoba menyelesaikan masalah teknis atau billing sendiri."
),
handoffs=[agentbilling, agentteknis],
)
hasil = Runner.runsync(
agentpenyalur,
"Halo, internet saya mati sejak pagi padahal saya sudah bayar tagihan bulan ini.",
)
print(hasil.finaloutput)
print("agent terakhir:", hasil.lastagent.name)
handoffdescription adalah teks yang dibaca agent penyalur untuk memutuskan ke mana menyerahkan. Tulis dengan jelas dan bedakan antar spesialis, karena kalau deskripsinya tumpang tindih, penyaluran jadi acak.
Yang penting dipahami, handoff itu benar-benar pemindahan kendali. Agent tujuan mengambil alih percakapan sepenuhnya, dengan instruksi dan tool-nya sendiri. Ini berbeda dengan memanggil agent lain sebagai tool, yang akan kita bahas berikutnya.
Agent sebagai Tool
Kadang kalian tidak ingin memindahkan kendali, tapi cuma ingin meminta bantuan lalu melanjutkan sendiri.
penerjemah = Agent(
name="Penerjemah",
instructions="Terjemahkan teks yang diberikan ke bahasa Inggris dengan akurat.",
)
peringkas = Agent(
name="Peringkas",
instructions="Ringkas teks menjadi maksimal tiga kalimat.",
)
orkestrator = Agent(
name="Orkestrator",
instructions=(
"Kamu mengelola alur pemrosesan dokumen. "
"Terjemahkan dulu, lalu ringkas hasilnya, lalu sajikan keduanya."
),
tools=[
penerjemah.astool(
toolname="terjemahkan",
tooldescription="Terjemahkan teks ke bahasa Inggris",
),
peringkas.astool(
toolname="ringkas",
tooldescription="Ringkas teks jadi tiga kalimat",
),
],
)
hasil = Runner.runsync(orkestrator, "Proses dokumen ini: [isi dokumen panjang]")
print(hasil.finaloutput)
Perbedaannya penting. Pakai handoff kalau agent lain harus mengambil alih percakapan dengan pengguna. Pakai astool kalau kalian cuma butuh hasilnya untuk diproses lebih lanjut oleh agent utama.
Guardrail: Menjaga Agent Tetap di Jalur
Guardrail adalah pemeriksaan yang berjalan sebelum atau sesudah agent utama.
from pydantic import BaseModel
from agents import (
Agent, Runner, GuardrailFunctionOutput,
inputguardrail, RunContextWrapper,
InputGuardrailTripwireTriggered,
)
class HasilPemeriksaan(BaseModel):
relevan: bool
alasan: str
agentpemeriksa = Agent(
name="Pemeriksa Relevansi",
instructions=(
"Tentukan apakah pesan pengguna berkaitan dengan layanan internet, "
"tagihan, atau dukungan teknis perusahaan kami."
),
outputtype=HasilPemeriksaan,
model="gpt-4o-mini",
)
@inputguardrail
async def guardrailrelevansi(ctx: RunContextWrapper, agent: Agent, inputdata):
hasil = await Runner.run(agentpemeriksa, inputdata, context=ctx.context)
periksa = hasil.finaloutput
return GuardrailFunctionOutput(
outputinfo=periksa,
tripwiretriggered=not periksa.relevan,
)
agentutama = Agent(
name="Customer Service",
instructions="Bantu pelanggan dengan pertanyaan seputar layanan kami.",
inputguardrails=[guardrailrelevansi],
)
try:
hasil = Runner.runsync(agentutama, "Tolong buatkan saya resep rendang.")
print(hasil.finaloutput)
except InputGuardrailTripwireTriggered as e:
print("Permintaan di luar cakupan layanan.")
Perhatikan bahwa aku memakai model murah untuk guardrail. Ini penting, karena guardrail berjalan di setiap permintaan. Memakai model mahal untuk penyaringan akan membuat biaya kalian membengkak tanpa manfaat sepadan.
Guardrail output juga tersedia dengan dekorator @outputguardrail, berguna untuk memastikan agent tidak membocorkan informasi sensitif atau memberi janji yang tidak boleh diberikan.
Session: Riwayat Percakapan Otomatis
from agents import Agent, Runner, SQLiteSession
agent = Agent(name="Asisten", instructions="Kamu asisten yang membantu.")
sesi = SQLiteSession("percakapanuser123", "riwayat.db")
hasil = Runner.runsync(agent, "Nama saya Ruby, saya kerja di bidang AI.", session=sesi)
print(hasil.finaloutput)
hasil = Runner.runsync(agent, "Kamu ingat nama saya siapa?", session=sesi)
print(hasil.finaloutput) # Model ingat karena riwayat dikelola sesi
Tanpa session, kalian harus mengelola daftar pesan sendiri dan meneruskannya setiap giliran. Dengan session, riwayat disimpan otomatis di SQLite dan bisa dilanjutkan bahkan setelah proses kalian restart.
Tracing: Debugging yang Manusiawi
Tracing aktif secara default dan mencatat setiap langkah eksekusi.
from agents import Agent, Runner, trace
async def prosespermintaan(pesan: str, idpelanggan: str):
with trace("Alur Customer Service", groupid=idpelanggan):
hasil = await Runner.run(agentpenyalur, pesan)
return hasil.finaloutput
Dengan groupid, semua giliran dari satu pelanggan dikelompokkan bersama, sehingga kalian bisa menelusuri satu percakapan utuh di dashboard.
Kalian juga bisa memeriksa hasil eksekusi secara program:
hasil = Runner.runsync(agentpenyalur, "Internet saya mati.")
for item in hasil.newitems:
print(type(item).name)
print("jumlah giliran:", len(hasil.rawresponses))
print("agent terakhir:", hasil.lastagent.name)
Untuk data sensitif, kalian bisa mematikan tracing:
export OPENAIAGENTSDISABLETRACING=1
Membatasi Giliran
Agent yang berputar-putar memanggil tool tanpa henti adalah cara tercepat membakar anggaran. Selalu pasang batas.
from agents import Agent, Runner, RunConfig, MaxTurnsExceeded
try:
hasil = Runner.runsync(
agent,
"Cari semua informasi yang mungkin tentang produk kami.",
maxturns=10,
)
print(hasil.finaloutput)
except MaxTurnsExceeded:
print("Agent melebihi batas giliran, kemungkinan terjebak loop.")
Tips dan Best Practice
Tulis instruksi yang spesifik, termasuk larangan eksplisit. "Jangan pernah menjanjikan refund tanpa persetujuan supervisor" jauh lebih efektif daripada berharap model paham sendiri.
Pisahkan agent berdasarkan domain, jangan membuat satu agent dengan tiga puluh tool. Agent dengan lima tool yang jelas jauh lebih andal daripada agent dengan tiga puluh tool yang membingungkan.
Pakai model murah untuk guardrail dan tugas klasifikasi sederhana, model mahal hanya untuk penalaran utama. Ini optimasi biaya terbesar yang bisa kalian lakukan.
Selalu pasang maxturns. Tidak ada pengecualian.
Pakai output terstruktur setiap kali hasilnya akan masuk ke sistem lain. Parsing teks bebas adalah sumber bug yang tidak pernah habis.
Simpan trace dan hasil evaluasi. Waktu kalian mengubah instruksi, kalian butuh cara membandingkan apakah perubahan itu membuat sistem lebih baik atau lebih buruk.
Untuk tool yang punya efek samping serius seperti mengirim email atau memproses pembayaran, tambahkan langkah konfirmasi manusia. Agent yang salah mengirim seratus email adalah cerita yang tidak ingin kalian alami.
Kesimpulan
OpenAI Agents SDK adalah pilihan yang bagus kalau kalian menghargai kesederhanaan dan kemampuan debugging. Ringkasannya:
Hanya ada empat primitif yang perlu dikuasai: Agents, Handoffs, Guardrails, dan Sessions.
Tool ditulis sebagai fungsi Python biasa dengan dekorator, dan docstring plus type hints adalah antarmuka yang dibaca model.
Output terstruktur dengan Pydantic membuat integrasi ke sistem lain jadi aman dan bisa divalidasi.
Handoff memindahkan kendali percakapan ke spesialis, sedangkan as_tool hanya meminta bantuan tanpa memindahkan kendali. Pilih sesuai kebutuhan.
Guardrail dengan model murah adalah cara efisien menjaga agent tetap di jalur dan menghemat biaya.
Tracing bawaan membuat debugging sistem multi-agent jauh lebih masuk akal daripada menebak dari log.
Coba bangun satu alur nyata di tempat kerja kalian, misalnya penyaluran tiket support ke tiga spesialis. Mulai dari dua agent dan dua tool, lalu tambahkan guardrail. Dalam satu sore kalian sudah punya prototipe yang bisa didemokan, dan dari situ biasanya keputusan untuk melanjutkan jadi jauh lebih mudah. Selamat mencoba.