Tool calling adalah yang mengubah model menjadi agen. Dengan model terbuka di API yang kompatibel dengan OpenAI, format permintaannya sama dengan yang Anda pakai di OpenAI. Yang berbeda adalah seberapa sering terjadi masalah dan apa yang dilakukan server untuk mencegahnya. Artikel ini membahas formatnya, cara menulis skema yang ditangani model terbuka dengan baik, panggilan paralel, lima kegagalan yang benar-benar akan Anda temui, dan loop Python yang tahan terhadap semuanya.
Bagaimana tool calling bekerja di API yang kompatibel dengan OpenAI?
- Anda mengirim
messagesbeserta daftartools. Setiap tool punya nama, deskripsi, dan JSON Schema untuk argumennya. - Model membalas dengan
finish_reason: "tool_calls"dan daftartool_calls. Setiap entri berisiid, nama fungsi, danargumentssebagai string JSON. - Kode Anda menjalankan setiap panggilan dan menambahkan satu pesan
role: "tool"per panggilan, dengantool_call_idyang cocok. - Anda memanggil API lagi. Model menjawab atau meminta tool lain.
Model tidak pernah menjalankan apa pun. Kode Anda yang memutuskan apa yang dieksekusi.
Bagaimana sebaiknya menulis skema tool?
Model terbuka lebih andal mengikuti skema yang sederhana. Aturan berikut berasal dari panduan OpenAI dan dari hal-hal yang biasanya rusak:
- Beri nama tool berdasarkan aksinya, misalnya
read_fileatausearch_code, dan tulis di deskripsi kapan masing-masing dipakai. - Buat daftarnya pendek. Panduan OpenAI menyebut kurang dari 20 fungsi di awal satu giliran sebagai saran yang tidak mengikat. Setiap skema juga dikirim di setiap panggilan; lihat anggaran token agen.
- Utamakan argumen datar. String, angka, boolean, dan enum. Hindari nesting dalam dan objek berbentuk bebas.
- Pakai enum untuk pilihan tetap, agar model tidak bisa mengarang nilai. Generator JSON schema mengubah contoh objek argumen menjadi skema datar yang bisa Anda tempel ke
parameters. - Tandai field wajib. Strict mode OpenAI mensyaratkan
additionalProperties: falsedan setiap field ada direquired, dengannullsebagai tipe untuk field opsional. Apakah penyedia memaksakanstrictatau tidak itu bervariasi, jadi tetap lakukan validasi.
Bagaimana dengan tool call paralel?
Model bisa mengembalikan beberapa entri di tool_calls dalam satu giliran, misalnya tiga pembacaan file. Jalankan panggilan yang saling independen secara bersamaan dan kembalikan satu hasil per tool_call_id, dalam urutan apa pun. Jika tool Anda punya efek samping yang saling bergantung, set parallel_tool_calls: false; panduan OpenAI menyebut itu membatasi model ke nol atau satu panggilan per giliran. Uji apakah penyedia Anda menghormatinya.
Kenapa tool call gagal?
| Kegagalan | Yang Anda lihat | Solusi |
|---|---|---|
| Argumen rusak | json.loads memunculkan exception |
Kembalikan error parse sebagai hasil tool; retry |
| Skema tidak cocok | Field hilang, tipe salah, enum karangan | Validasi; kembalikan error validasinya |
| Tool tidak dikenal | Nama yang tidak pernah Anda definisikan | Kembalikan “unknown tool, available: …” |
| Tidak memanggil saat diperlukan | Malah menjawab dengan teks | tool_choice: "required" atau fungsi bernama |
| Panggilan terpotong | finish_reason: "length" |
Naikkan max_tokens; penalaran ikut memakainya |
Dua yang pertama memang bisa diperkirakan, bukan hal langka. Dokumentasi tool calling vLLM menyebut bahwa dalam mode auto, kecuali sebuah tool menyetel strict: true (atau server memaksakan batas minimum strictness) dan parser model mendukung constraint, “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.” (Terjemahan BroadRouter: vLLM mengekstrak tool call dari teks mentah, sehingga argumen sesekali bisa rusak atau melanggar skema parameter fungsi.) Fungsi bernama memakai backend structured outputs milik vLLM. Penyedia Anda mungkin menyajikan model dengan cara berbeda, jadi anggap validasi sebagai keharusan.
Baris terakhir sering menjebak pengguna model penalaran. GLM 5.3 dan Qwen3.8 27B berpikir dulu sebelum menjawab, dan proses berpikir itu dihitung ke dalam max_tokens. Kenapa balasan kosong atau terpotong menjelaskan berapa banyak ruang yang perlu disisakan.
Loop tool yang memvalidasi dan retry
import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"
TOOLS = [{"type": "function", "function": {
"name": "get_order_status",
"description": "Look up one order by its ID. Use when the user asks where an order is.",
"parameters": {"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}
def run_call(call):
name = call.function.name
if name not in IMPL:
return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
try:
args = json.loads(call.function.arguments or "{}")
validate(args, SCHEMAS[name])
except (json.JSONDecodeError, ValidationError) as e:
return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
return str(IMPL[name](**args))
def agent(messages, max_steps=8):
for _ in range(max_steps):
r = client.chat.completions.create(model=MODEL, messages=messages,
tools=TOOLS, max_tokens=4000)
msg = r.choices[0].message
if r.choices[0].finish_reason == "length":
raise RuntimeError("Output limit reached; raise max_tokens")
messages.append(msg.model_dump(exclude_none=True))
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
messages.append({"role": "tool", "tool_call_id": call.id,
"content": run_call(call)})
raise RuntimeError("Step limit reached")
Tiga keputusan desain penting di sini:
- Error dikembalikan ke model sebagai hasil tool. Model melihat apa yang salah dan biasanya memperbaikinya di giliran berikutnya. Memunculkan exception membuang kesempatan itu.
- Loop-nya dibatasi.
max_stepsmenghentikan model yang terus memanggil tool tanpa kemajuan. - Retry di level transport dipisahkan.
max_retriesdi client menangani 429 dan 5xx. Argumen yang buruk ditangani di dalam loop. Jangan campur keduanya; lihat error dan retry.
Untuk tool yang punya efek samping, seperti mengirim email, tambahkan idempotency key agar langkah yang di-retry tidak bertindak dua kali. Agen yang berjalan lama membahas hal ini.
Model BroadNet mana yang mendukung tool calling?
| Model | Tools tercantum | Konteks | Catatan |
|---|---|---|---|
| GLM 5.3 | Ya | 1.048.576 | Juga output terstruktur |
| Qwen3.8 27B | Ya | 262.144 | Juga input gambar |
| DeepSeek V4.1 Flash | Tidak tercantum | 1.048.576 | Input gambar; uji tools sebelum mengandalkannya |
| Gemma 4 VL 26B | Tidak tercantum | 32.768 | Bukan untuk loop tool |
Untuk memilih di antara dua model yang mendukung tool, lihat GLM 5.3 vs Qwen3.8 27B. Jika jawaban akhir harus mengikuti bentuk tertentu tetapi tidak ada fungsi yang perlu dijalankan, output terstruktur lebih sederhana daripada tool.
Posisi BroadNet Inference
BroadNet Inference menyajikan GLM 5.3 dan Qwen3.8 27B dengan tool calling tercantum, lewat format chat-completions standar, sehingga loop di atas berjalan tanpa perubahan dengan OpenAI Python SDK. Harga per token ada di halaman harga. BroadNet tidak meng-host tool sisi server seperti web search atau eksekusi kode, dan dokumentasinya tidak mencantumkan tool calling untuk DeepSeek V4.1 Flash, model di paket unlimited. Untuk agen yang banyak memakai tools, gunakan GLM 5.3 atau Qwen3.8 27B dengan harga per token. Jika Anda tetap menginginkan paket harga tetap, pastikan dengan satu jam Meteor seharga $1 bahwa DeepSeek V4.1 Flash memanggil tools Anda dengan andal sebelum membeli paket bulanan.
