OpenAI Agents SDK: Membangun Sistem Multi-Agent dengan Handoff dan Guardrail

# 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...

By Ruby Abdullah · · tutorial
openai-agents-sdkmulti-agentllm-agentsguardrailspython

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

@functiontool

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.

Artikel Terkait

Tutorial Google A2A Protocol: Membangun Sistem Multi-Agent yang Saling Berkomunikasi

Tutorial Google A2A Protocol: Membangun Sistem Multi-Agent yang Saling Berkomunikasi Dalam era AI yang semakin canggih, ...

Tutorial CAMEL-AI: Framework Multi-Agent Communication untuk Membangun Sistem AI Kolaboratif

Tutorial Lengkap CAMEL-AI: Framework Multi-Agent Communication untuk Membangun Sistem AI Kolaboratif Penulis: Ruby Abdul...

Tutorial Lengkap Google Agent Development Kit (ADK): Membangun AI Agent dengan Python

Tutorial Lengkap Google Agent Development Kit (ADK): Membangun AI Agent dengan Python Google Agent Development Kit (ADK)...

AutoGen: Framework Multi-Agent Conversation dari Microsoft

AutoGen: Framework Multi-Agent Conversation dari Microsoft AutoGen adalah framework open-source dari Microsoft Research ...