Cara Menggunakan OpenAI Assistants API di Python

Pendahuluan

Bayangkan kamu punya asisten pribadi yang bisa mengingat percakapan sebelumnya, menjalankan kode Python, membaca dokumen PDF, dan menjawab pertanyaan berdasarkan data yang kamu berikan — semuanya tanpa kamu harus menulis logika memori dari nol. Itulah yang ditawarkan oleh OpenAI Assistants API.

Berbeda dengan ChatGPT biasa yang kamu akses lewat browser, Assistants API dirancang untuk developer yang ingin membangun aplikasi AI yang lebih canggih dan stateful — artinya, asisten ini bisa mengingat konteks percakapan secara otomatis.

Jika kamu pernah mencoba membangun chatbot sederhana dengan Python dan merasa pusing mengurus memori percakapan secara manual, artikel ini adalah solusinya. Kita akan belajar langkah demi langkah cara menggunakan Assistants API dari OpenAI dengan Python — mulai dari konsep dasar hingga contoh kode yang bisa langsung kamu jalankan.

Sebelum mulai, pastikan kamu sudah familiar dengan dasar-dasar Python. Jika belum, kamu bisa melihat artikel tentang Membangun Web Scraper dengan Python: Tutorial Step-by-Step sebagai referensi untuk mempersiapkan lingkungan Python-mu.

Konsep Dasar

Sebelum langsung ke kode, kita perlu memahami empat komponen utama dalam Assistants API. Anggap saja seperti membangun sebuah pusat layanan pelanggan otomatis — ada beberapa bagian yang perlu bekerja sama.

1. Assistant

Assistant adalah “kepribadian” atau identitas dari AI yang kamu buat. Di sinilah kamu mendefinisikan:

• Model yang digunakan (misalnya gpt-4o)
• Instruksi atau sistem prompt
• Tools apa saja yang bisa digunakan (code interpreter, file search, dll.)

Analoginya: ini seperti kontrak kerja karyawan baru — kamu menjelaskan siapa dia, apa tugasnya, dan apa yang boleh dia lakukan.

2. Thread

Thread adalah satu sesi percakapan. Setiap kali pengguna memulai obrolan baru, kamu membuat Thread baru. OpenAI secara otomatis menyimpan semua pesan dalam Thread ini, sehingga kamu tidak perlu menyimpan riwayat percakapan sendiri.

Analoginya: ini seperti satu tiket percakapan di aplikasi customer service seperti Tokopedia — semua pesan antara pelanggan dan agen tersimpan dalam satu tiket yang sama.

3. Message

Message adalah pesan individual yang masuk dalam sebuah Thread — bisa dari pengguna (role: user) atau dari asisten (role: assistant).

4. Run

Run adalah proses eksekusi — saat kamu meminta Assistant untuk memproses pesan terbaru dalam Thread dan menghasilkan respons. Run ini bersifat asynchronous, artinya kamu perlu menunggu hingga statusnya completed sebelum bisa membaca responsnya.

Hubungan keempat komponen ini bisa digambarkan seperti ini:

Assistant (identitas & instruksi)
    │
    └── Thread (sesi percakapan)
            │
            ├── Message (pesan user)
            ├── Message (respons asisten)
            └── Run (proses eksekusi)

Contoh Kode

Persiapan: Instalasi Library

Pertama, pastikan kamu sudah menginstal library OpenAI terbaru:

pip install openai

Kemudian, simpan API key kamu sebagai environment variable agar tidak hardcode di dalam kode:

export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

Langkah 1: Membuat Assistant

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

# Membuat Assistant baru
assistant = client.beta.assistants.create(
    name="Asisten Python KamusNgoding",
    instructions="""
    Kamu adalah asisten pemrograman Python yang ramah dan sabar.
    Jelaskan konsep dengan bahasa yang mudah dipahami.
    Jika ada pertanyaan tentang kode, berikan contoh yang konkret.
    """,
    model="gpt-4o",
)

print(f"Assistant berhasil dibuat! ID: {assistant.id}")
# Simpan assistant.id ini, kamu butuh nanti

Catatan penting: Simpan assistant.id yang dihasilkan. Kamu tidak perlu membuat Assistant baru setiap kali aplikasi dijalankan — cukup gunakan ID yang sama.

Langkah 2: Membuat Thread dan Mengirim Pesan

# Membuat Thread baru (satu sesi percakapan)
thread = client.beta.threads.create()
print(f"Thread dibuat! ID: {thread.id}")

# Menambahkan pesan dari user ke dalam Thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Halo! Bisa jelaskan apa itu list comprehension di Python?",
)

print(f"Pesan berhasil dikirim! ID: {message.id}")

Langkah 3: Menjalankan Run dan Menunggu Respons

Ini adalah bagian yang paling penting — kita harus menjalankan Run dan menunggu hingga selesai:

import time

def tunggu_run_selesai(client, thread_id, run_id, interval=1):
    """
    Polling status Run hingga selesai.
    Mengembalikan objek Run yang sudah selesai.
    """
    while True:
        run = client.beta.threads.runs.retrieve(
            thread_id=thread_id,
            run_id=run_id,
        )
        
        print(f"Status Run: {run.status}")
        
        if run.status in ["completed", "failed", "cancelled", "expired"]:
            return run
        
        # Tunggu sebentar sebelum cek lagi
        time.sleep(interval)

# Menjalankan Run
run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id,
)

print(f"Run dimulai! ID: {run.id}")

# Tunggu hingga Run selesai
run_selesai = tunggu_run_selesai(client, thread.id, run.id)

if run_selesai.status == "completed":
    print("Run berhasil diselesaikan!")
else:
    print(f"Run gagal dengan status: {run_selesai.status}")

Langkah 4: Membaca Respons dari Assistant

# Mengambil semua pesan dalam Thread
messages = client.beta.threads.messages.list(
    thread_id=thread.id,
    order="asc",  # Urutkan dari pesan pertama
)

# Tampilkan semua pesan
for msg in messages.data:
    role = "User" if msg.role == "user" else "Asisten"
    # Ambil konten teks dari pesan
    for content_block in msg.content:
        if content_block.type == "text":
            print(f"\n[{role}]: {content_block.text.value}")

Langkah 5: Melanjutkan Percakapan (Thread yang Sama)

Salah satu keunggulan Assistants API adalah kamu bisa melanjutkan percakapan dalam Thread yang sama — asisten akan mengingat konteks sebelumnya:

# Kirim pesan lanjutan — asisten masih ingat konteks sebelumnya!
pesan_lanjutan = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Bisa berikan contoh kode list comprehension untuk memfilter angka genap?",
)

# Jalankan Run lagi pada Thread yang sama
run2 = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id,
)

# Tunggu selesai
run2_selesai = tunggu_run_selesai(client, thread.id, run2.id)

# Ambil hanya pesan terbaru dari asisten
messages2 = client.beta.threads.messages.list(
    thread_id=thread.id,
    order="desc",  # Mulai dari yang terbaru
    limit=1,       # Ambil satu pesan saja
)

for msg in messages2.data:
    if msg.role == "assistant":
        for content_block in msg.content:
            if content_block.type == "text":
                print(f"\n[Asisten]: {content_block.text.value}")

Kode Lengkap: Chatbot Sederhana

Berikut adalah contoh lengkap yang menggabungkan semua langkah di atas menjadi chatbot interaktif:

import os
import time
from openai import OpenAI

client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

def buat_atau_ambil_assistant(nama, instruksi, model="gpt-4o"):
    """Membuat assistant baru."""
    assistant = client.beta.assistants.create(
        name=nama,
        instructions=instruksi,
        model=model,
    )
    return assistant

def kirim_pesan_dan_tunggu(thread_id, assistant_id, pesan_user):
    """Kirim pesan dan tunggu respons dari assistant."""
    # Tambah pesan user ke thread
    client.beta.threads.messages.create(
        thread_id=thread_id,
        role="user",
        content=pesan_user,
    )
    
    # Jalankan run
    run = client.beta.threads.runs.create(
        thread_id=thread_id,
        assistant_id=assistant_id,
    )
    
    # Tunggu selesai
    while True:
        run = client.beta.threads.runs.retrieve(
            thread_id=thread_id,
            run_id=run.id,
        )
        if run.status == "completed":
            break
        elif run.status in ["failed", "cancelled", "expired"]:
            raise Exception(f"Run gagal: {run.status}")
        time.sleep(1)
    
    # Ambil respons terbaru
    messages = client.beta.threads.messages.list(
        thread_id=thread_id,
        order="desc",
        limit=1,
    )
    
    for msg in messages.data:
        if msg.role == "assistant":
            for block in msg.content:
                if block.type == "text":
                    return block.text.value
    
    return "Tidak ada respons."

def main():
    print("=== Chatbot KamusNgoding ===")
    print("Ketik 'keluar' untuk mengakhiri percakapan.\n")
    
    # Buat assistant
    assistant = buat_atau_ambil_assistant(
        nama="Asisten Python",
        instruksi="Kamu adalah asisten pemrograman Python yang ramah. Jawab dalam Bahasa Indonesia.",
    )
    
    # Buat thread baru untuk sesi ini
    thread = client.beta.threads.create()
    
    while True:
        user_input = input("Kamu: ").strip()
        
        if user_input.lower() == "keluar":
            print("Sampai jumpa! Selamat belajar Python!")
            break
        
        if not user_input:
            continue
        
        try:
            respons = kirim_pesan_dan_tunggu(thread.id, assistant.id, user_input)
            print(f"\nAsisten: {respons}\n")
        except Exception as e:
            print(f"Error: {e}")

if __name__ == "__main__":
    main()

Contoh output saat dijalankan:

=== Chatbot KamusNgoding ===
Ketik 'keluar' untuk mengakhiri percakapan.

Kamu: Apa itu decorator di Python?

Asisten: Decorator di Python adalah fungsi yang membungkus fungsi lain untuk
menambahkan fungsionalitas tambahan tanpa mengubah kode aslinya...

Kamu: Bisa kasih contoh sederhananya?

Asisten: Tentu! Karena kamu tadi tanya tentang decorator, ini contoh sederhananya...

Perhatikan bahwa pada pertanyaan kedua, asisten masih mengingat konteks tentang decorator — itulah kekuatan Thread yang menyimpan riwayat percakapan secara otomatis.

Konsep state management percakapan seperti ini juga mirip dengan cara kerja state dalam komponen React. Jika kamu tertarik membangun antarmuka chatbot-nya, kamu bisa baca tentang React Context vs Redux: Perbedaan dan Kapan Menggunakannya untuk mengelola state percakapan di sisi frontend.

Troubleshooting: Error yang Sering Muncul

AuthenticationError: Incorrect API key provided

Penyebab: API key tidak terbaca oleh program, biasanya karena environment variable belum di-set dengan benar atau ada typo di key.

Solusi:

import os

# Cek apakah API key sudah ter-set
api_key = os.environ.get("OPENAI_API_KEY")
if not api_key:
    raise ValueError("OPENAI_API_KEY belum di-set! Jalankan: export OPENAI_API_KEY='sk-...'")

print(f"API Key ditemukan: {api_key[:10]}...")  # Tampilkan sebagian untuk verifikasi

client = OpenAI(api_key=api_key)

Run Status failed atau Respons Tidak Muncul

Penyebab: Run gagal dieksekusi, bisa karena token limit terlampaui, model tidak tersedia, atau instruksi yang terlalu panjang.

Solusi:

# Cek detail error dari Run yang gagal
run = client.beta.threads.runs.retrieve(
    thread_id=thread_id,
    run_id=run_id,
)

if run.status == "failed":
    print(f"Run gagal!")
    print(f"Error code: {run.last_error.code}")
    print(f"Error message: {run.last_error.message}")
    
    # Solusi umum:
    # - "context_length_exceeded" → kurangi panjang percakapan atau buat Thread baru
    # - "model_not_found" → ganti model ke "gpt-4o-mini" atau "gpt-3.5-turbo"
    # - "rate_limit_exceeded" → tambah delay sebelum retry

Thread Messages Tidak Muncul / Urutan Terbalik

Penyebab: Parameter order tidak disetel dengan benar, atau pengambilan pesan dilakukan sebelum Run selesai.

Solusi:

# Pastikan Run sudah completed sebelum ambil pesan
# Gunakan order="asc" untuk urutan kronologis
messages = client.beta.threads.messages.list(
    thread_id=thread.id,
    order="asc",   # "asc" = tertua dulu, "desc" = terbaru dulu
    after=None,    # Kosongkan untuk ambil semua pesan
)

# Atau gunakan order="desc" + limit=1 untuk ambil pesan terbaru saja
latest = client.beta.threads.messages.list(
    thread_id=thread.id,
    order="desc",
    limit=1,
)

RateLimitError: Too Many Requests

Penyebab: Terlalu banyak request dalam waktu singkat, terutama saat polling status Run terlalu cepat.

Solusi:

import time
import random

def tunggu_run_dengan_backoff(client, thread_id, run_id):
    """Polling dengan exponential backoff untuk menghindari rate limit."""
    interval = 1  # Mulai dari 1 detik
    max_interval = 30  # Maksimal 30 detik
    
    while True:
        try:
            run = client.beta.threads.runs.retrieve(
                thread_id=thread_id,
                run_id=run_id,
            )
            
            if run.status in ["completed", "failed", "cancelled", "expired"]:
                return run
            
            # Tambah sedikit jitter agar tidak semua request bersamaan
            jitter = random.uniform(0, 0.5)
            time.sleep(interval + jitter)
            interval = min(interval * 2, max_interval)  # Exponential backoff
            
        except Exception as e:
            print(f"Error saat polling: {e}")
            time.sleep(5)  # Tunggu 5 detik jika ada error

Pertanyaan yang Sering Diajukan (FAQ)

Apa perbedaan Assistants API dengan Chat Completions API biasa?

Chat Completions API adalah API “satu tembakan” — kamu kirim pesan, dapat respons, selesai. Kamu harus mengurus sendiri riwayat percakapan dengan menyimpan array pesan. Sementara Assistants API menyediakan Thread yang menyimpan riwayat secara otomatis di server OpenAI, sehingga cocok untuk aplikasi chatbot yang butuh memori percakapan jangka panjang.

Apakah Thread tersimpan selamanya di OpenAI?

Tidak. Secara default, Thread dan pesan di dalamnya akan dihapus setelah 60 hari tidak aktif. Jika aplikasimu butuh penyimpanan percakapan permanen, kamu perlu mengekspor dan menyimpan data Thread ke database sendiri — misalnya menggunakan SQLite seperti yang digunakan dalam pipeline KamusNgoding.

Bagaimana cara menggunakan satu Assistant untuk banyak pengguna?

Cukup buat satu Assistant, lalu buat Thread yang berbeda untuk setiap pengguna atau sesi. Assistant ID bisa dipakai bersama, tetapi Thread harus unik per pengguna. Simpan mapping antara user_id dan thread_id di database aplikasimu.

Apakah Assistants API bisa membaca file atau dokumen?

Ya! Assistants API mendukung tool file_search yang memungkinkan asisten membaca dan mencari informasi dari file yang kamu upload (PDF, DOCX, TXT, dll.). Kamu perlu mengaktifkan tool ini saat membuat Assistant dan mengupload file ke OpenAI Files API terlebih dahulu.

Berapa biaya menggunakan Assistants API?

Biaya dihitung berdasarkan token yang digunakan — sama seperti Chat Completions API, ditambah biaya penyimpanan Thread jika menggunakan file storage. Untuk aplikasi dengan volume rendah, gpt-4o-mini adalah pilihan yang jauh lebih hemat dibanding gpt-4o dengan kualitas yang masih sangat baik untuk tugas-tugas umum.

Kesimpulan

Kita sudah belajar cara menggunakan OpenAI Assistants API dari awal hingga membangun chatbot sederhana yang fungsional. Empat konsep kunci yang perlu kamu ingat: Assistant (identitas AI), Thread (sesi percakapan), Message (pesan individual), dan Run (proses eksekusi). Dengan Assistants API, kamu tidak perlu lagi repot mengurus memori percakapan secara manual — semuanya sudah ditangani oleh OpenAI di sisi server.

Langkah selanjutnya, kamu bisa mengeksplorasi fitur lebih lanjut seperti Code Interpreter (menjalankan kode Python langsung oleh AI), File Search (membuat asisten yang bisa membaca dokumen PDF), atau bahkan menggabungkan Assistants API dengan pipeline otomatisasi seperti yang dijelaskan dalam Cara Membuat Pipeline CI/CD Sederhana dengan GitHub Actions untuk deployment otomatis.

Selamat belajar dan terus bereksperimen! Membangun AI agent bukanlah hal yang rumit jika kamu memulai selangkah demi selangkah. Jika ada pertanyaan atau hambatan, jangan ragu untuk mengeksplorasi artikel-artikel lainnya di KamusNgoding — komunitas developer Indonesia terus berkembang dan belajar bersama!