Function calling di Python dengan API yang kompatibel dengan OpenAI

Function calling (tool calling) memungkinkan model meminta kode Anda menjalankan sebuah fungsi. Anda mengirim daftar tools bersama permintaan, model menjawab dengan tool_calls alih-alih teks, Anda menjalankan fungsi itu sendiri, lalu mengirim hasilnya kembali dalam pesan dengan role: tool. Model kemudian menulis jawaban akhir. Panduan ini menunjukkan seluruh alur dalam Python terhadap endpoint yang kompatibel dengan OpenAI https://api.cheaptokens.dev/v1/chat/completions dengan MiniMax-M2.7 (id MiniMaxAI/MiniMax-M2.7, konteks 180K, hingga 8.192 token keluaran per jawaban).

Tool calling tercantum sebagai didukung untuk setiap model dalam katalog (CheapTokens dokumentasi, diperiksa pada 22 Oktober 2026). Anda memerlukan kunci API; jika Anda belum pernah membuat permintaan, mulailah dengan permintaan API pertama Anda.

Cara kerja function calling#

Model tidak pernah menjalankan apa pun. Model hanya menghasilkan permintaan terstruktur: "panggil get_weather dengan {\"city\": \"Paris\"}". Program Anda melakukan pekerjaan sebenarnya dan melaporkannya kembali. Itu membentuk alur dua permintaan:

1. Permintaan 1. Anda mengirim pesan pengguna beserta daftar tools. Model menjawab dengan teks atau mengembalikan satu atau lebih tool_calls.
2. Kode Anda. Anda mengurai setiap panggilan, menjalankan fungsi yang sesuai dan mengumpulkan hasilnya.
3. Permintaan 2. Anda mengirim seluruh percakapan lagi: pesan asli, pesan asisten dengan tool_calls, dan satu pesan role: tool per panggilan. Model menggunakan hasilnya untuk menulis jawaban akhir.

Setiap permintaan mengirim ulang seluruh riwayat, sehingga alur tool menggunakan lebih banyak token masukan daripada satu pertanyaan tunggal. Jika ini baru bagi Anda, baca apa itu token.

Siapkan klien#

Pasang SDK OpenAI (pip install openai) dan letakkan kunci Anda di variabel lingkungan, bukan di kode sumber:

export CHEAPTOKENS_API_KEY="your-key-here"

Base URL-nya adalah https://api.cheaptokens.dev/v1. Ambil id model dari dokumentasi CheapTokens: penyedia berbeda menamai model yang sama secara berbeda. Panduan ini menggunakan MiniMaxAI/MiniMax-M2.7.

Deklarasikan fungsi dan kirim permintaan pertama#

Sebuah fungsi dijelaskan dalam array tools. Setiap entri memiliki type: function dan objek function dengan name, description dan parameters yang ditulis sebagai JSON Schema. Deskripsi inilah yang dibaca model untuk memutuskan kapan memanggil fungsi, jadi tulis sebagai kalimat singkat dan konkret.

Berikut skrip lengkap. Fungsi cuaca adalah stub dengan data palsu, sehingga contoh ini tidak memerlukan layanan tambahan:

import json
import os

from openai import OpenAI

client = OpenAI(
    base_url='https://api.cheaptokens.dev/v1',
    api_key=os.environ['CHEAPTOKENS_API_KEY'],
)
MODEL = 'MiniMaxAI/MiniMax-M2.7'


def get_weather(city: str) -> dict:
    # Stub with fake data: replace with a real lookup
    fake = {'Paris': 14, 'Tokyo': 19}
    return {'city': city, 'temp_c': fake.get(city, 10)}


FUNCTIONS = {'get_weather': get_weather}

tools = [
    {
        'type': 'function',
        'function': {
            'name': 'get_weather',
            'description': 'Get the current temperature in Celsius for a city.',
            'parameters': {
                'type': 'object',
                'properties': {
                    'city': {'type': 'string', 'description': 'City name, for example Paris'},
                },
                'required': ['city'],
            },
        },
    }
]

messages = [{'role': 'user', 'content': 'What is the weather in Paris right now?'}]

# Step 1: the model decides whether to call a function
first = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
message = first.choices[0].message

if not message.tool_calls:
    print(message.content)
    raise SystemExit

# Step 2: run every requested call and send the results back
messages.append(message)
for call in message.tool_calls:
    args = json.loads(call.function.arguments)
    result = FUNCTIONS[call.function.name](**args)
    messages.append({
        'role': 'tool',
        'tool_call_id': call.id,
        'content': json.dumps(result),
    })

final = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
print(final.choices[0].message.content)

Tiga detail menentukan apakah alur ini berhasil:

• call.function.arguments adalah string JSON, bukan dictionary. Uraikan dengan json.loads.
• Setiap pesan role: tool harus membawa tool_call_id dari panggilan yang dijawabnya, yaitu call.id.
• content dari pesan tool adalah string. Gunakan json.dumps untuk hasil terstruktur.

Yang seharusnya Anda lihat#

Jika Anda mencetak field setelah permintaan pertama, tampilannya seperti ini (id panggilan berbeda di setiap eksekusi):

finish_reason: tool_calls
call.id: call_abc123
call.function.name: get_weather
call.function.arguments: {"city": "Paris"}

Skrip kemudian mencetak jawaban akhir, kalimat biasa seperti "Saat ini 14 °C di Paris." Kata-katanya berubah dari satu eksekusi ke eksekusi lain; angkanya berasal dari fungsi Anda.

Beberapa panggilan dan alur yang lebih panjang#

Model dapat mengembalikan lebih dari satu panggilan dalam satu respons, misalnya saat Anda bertanya tentang cuaca di dua kota. Itulah sebabnya contoh melakukan perulangan atas message.tool_calls dan menjawab setiap panggilan berdasarkan id-nya masing-masing. Panduan function calling OpenAI menjelaskan perilaku yang sama: dengan tool_choice bawaan bernilai auto, model dapat memanggil nol, satu, atau beberapa fungsi (dokumentasi OpenAI, diperiksa pada 22 Oktober 2026; halaman tersebut tidak mencantumkan tanggal pembaruan terakhir dan menjelaskan bentuk Responses API yang lebih baru, sedangkan panduan ini menggunakan bentuk Chat Completions dari endpoint /v1/chat/completions).

Agen mengulangi kedua langkah tersebut hingga model berhenti meminta tool. Bungkus permintaan dalam perulangan dan selalu tetapkan batas langkah:

for _ in range(5):  # safety limit against endless loops
    response = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
    message = response.choices[0].message
    if not message.tool_calls:
        print(message.content)
        break
    messages.append(message)
    for call in message.tool_calls:
        args = json.loads(call.function.arguments)
        result = FUNCTIONS[call.function.name](**args)
        messages.append({'role': 'tool', 'tool_call_id': call.id, 'content': json.dumps(result)})

Jika Anda ingin jawaban muncul token demi token, gabungkan dengan streaming di Python.

Mengapa MiniMax-M2.7 cocok untuk alur tool#

Alur tool mengirim banyak permintaan dengan riwayat yang terus bertambah. Untuk pola itu CheapTokens menawarkan MiniMax-M2.7: konteks 180K, hingga 8.192 token keluaran per jawaban, satu harga kapan pun sepanjang hari tanpa jam sibuk, dan satu saldo untuk semua model. Dihitung bersama antara masukan dan keluaran, harganya lebih murah daripada harga referensi OpenRouter (perbandingan harga CheapTokens, diperiksa 31 Oktober 2026).

Harga saat ini per 1 juta token: masukan $0.05, keluaran $0.15. Sebagai contoh beban kerja (bukan pengukuran), perjalanan pulang-pergi dua permintaan di atas dengan total sekitar 2.700 token masukan dan 350 token keluaran memakan biaya $0.00019. Daftar harga lengkap ada di halaman harga.

Untuk mencoba model lain, ubah hanya id-nya; daftar id ada di halaman model.

Jika tidak berhasil#

• message.tool_calls adalah None. Model menjawab dengan teks. Buat deskripsi fungsi description lebih spesifik, dan pastikan pertanyaannya memang membutuhkan fungsi tersebut.
• json.JSONDecodeError pada arguments. Model menghasilkan JSON yang tidak valid. Bungkus json.loads dalam try/except dan kirim teks error kembali sebagai hasil tool, agar model dapat mencoba ulang dengan argumen yang diperbaiki.
• Permintaan kedua gagal atau model mengabaikan hasilnya. Periksa bahwa setiap panggilan memiliki tepat satu pesan role: tool dengan tool_call_id yang cocok, dan bahwa pesan asisten dengan tool_calls ada dalam riwayat sebelum pesan-pesan tersebut.
• KeyError di FUNCTIONS[...]. Model menyebut fungsi yang tidak Anda daftarkan. Kembalikan string error singkat sebagai hasil tool alih-alih membuat program crash.
• Jawaban terpotong. Periksa finish_reason: nilai length berarti batas token keluaran tercapai. Lihat mengapa jawaban AI berhenti di tengah kalimat.
• Error 401 atau autentikasi. Periksa bahwa kunci ada di CHEAPTOKENS_API_KEY dan base URL diakhiri dengan /v1.

Langkah berikutnya#

Ganti stub dengan fungsi nyata: kueri basis data, panggilan pencarian, atau kalkulator. Tambahkan entri lain ke tools dan ke FUNCTIONS, dan jaga setiap hasil fungsi tetap singkat, karena hasil itu masuk kembali ke riwayat pada setiap permintaan berikutnya. Untuk mendapatkan kunci dan membuat panggilan pertama, buka dokumentasi CheapTokens.