Tool calling · Dokumentasi Laras Router

Tool calling (function calling) memungkinkan model meminta kode Anda menjalankan sebuah fungsi, lalu memakai hasilnya dalam jawaban. Formatnya sama persis dengan tools OpenAI: Anda mendeskripsikan fungsi dengan JSON Schema, model membalas dengan tool_calls, Anda menjalankannya lalu mengirim hasilnya kembali sebagai pesan tool.

Alurnya

Kirim percakapan beserta daftar tools.
Jika model ingin memakai tool, respons berisi finish_reason: "tool_calls" dan message.tool_calls.
Jalankan setiap panggilan di kode Anda.
Tambahkan pesan assistant (beserta tool_calls-nya) dan satu pesan tool untuk setiap panggilan, masing-masing dengan tool_call_id yang sesuai.
Kirim percakapan lagi. Ulangi sampai finish_reason bernilai "stop".

Setiap putaran adalah request terpisah dan ditagih terpisah.

Contoh lengkap

Contoh ini memberi model satu fungsi, get_order_status, dan menjalankan alur di atas sampai model menjawab dengan teks biasa.

import json
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.larasrouter.com/v1",
    api_key=os.environ["LARAS_API_KEY"],
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order_status",
            "description": "Cek status pengiriman pesanan berdasarkan ID-nya.",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {"type": "string", "description": "ID pesanan, misalnya INV-1042"}
                },
                "required": ["order_id"],
            },
        },
    }
]

def get_order_status(order_id: str) -> dict:
    # Ganti dengan pencarian data Anda yang sebenarnya.
    return {"order_id": order_id, "status": "shipped", "courier": "JNE", "eta_days": 2}

messages = [
    {"role": "system", "content": "Kamu adalah agen support yang ramah untuk sebuah toko online."},
    {"role": "user", "content": "Pesanan saya INV-1042 sudah sampai mana?"},
]

while True:
    response = client.chat.completions.create(
        model="deepseek-flash",
        messages=messages,
        tools=tools,
    )
    message = response.choices[0].message

    if not message.tool_calls:
        print(message.content)
        break

    # Simpan giliran assistant yang meminta tool, lalu jawab setiap panggilan.
    messages.append(
        {
            "role": "assistant",
            "content": message.content,
            "tool_calls": [call.model_dump() for call in message.tool_calls],
        }
    )
    for call in message.tool_calls:
        args = json.loads(call.function.arguments)
        result = get_order_status(**args)
        messages.append(
            {"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)}
        )

import OpenAI from "openai";
import type { ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources";

const client = new OpenAI({
  baseURL: "https://api.larasrouter.com/v1",
  apiKey: process.env.LARAS_API_KEY,
});

const tools: ChatCompletionTool[] = [
  {
    type: "function",
    function: {
      name: "get_order_status",
      description: "Cek status pengiriman pesanan berdasarkan ID-nya.",
      parameters: {
        type: "object",
        properties: {
          order_id: { type: "string", description: "ID pesanan, misalnya INV-1042" },
        },
        required: ["order_id"],
      },
    },
  },
];

function getOrderStatus(orderId: string) {
  // Ganti dengan pencarian data Anda yang sebenarnya.
  return { order_id: orderId, status: "shipped", courier: "JNE", eta_days: 2 };
}

const messages: ChatCompletionMessageParam[] = [
  { role: "system", content: "Kamu adalah agen support yang ramah untuk sebuah toko online." },
  { role: "user", content: "Pesanan saya INV-1042 sudah sampai mana?" },
];

while (true) {
  const response = await client.chat.completions.create({
    model: "deepseek-flash",
    messages,
    tools,
  });
  const message = response.choices[0].message;

  if (!message.tool_calls?.length) {
    console.log(message.content);
    break;
  }

  // Simpan giliran assistant yang meminta tool, lalu jawab setiap panggilan.
  messages.push({ role: "assistant", content: message.content, tool_calls: message.tool_calls });
  for (const call of message.tool_calls) {
    if (call.type !== "function") continue;
    const args = JSON.parse(call.function.arguments);
    messages.push({
      role: "tool",
      tool_call_id: call.id,
      content: JSON.stringify(getOrderStatus(args.order_id)),
    });
  }
}

Yang dikirim lewat jaringan

Respons pertama meminta tool:

Respons 1 — model memanggil tool

{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_0",
            "type": "function",
            "function": { "name": "get_order_status", "arguments": "{\"order_id\": \"INV-1042\"}" }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Request kedua mengirim ulang seluruh percakapan, termasuk hasil tool:

Request 2 — messages

[
  { "role": "system", "content": "Kamu adalah agen support yang ramah untuk sebuah toko online." },
  { "role": "user", "content": "Pesanan saya INV-1042 sudah sampai mana?" },
  {
    "role": "assistant",
    "content": "",
    "tool_calls": [
      {
        "id": "call_0",
        "type": "function",
        "function": { "name": "get_order_status", "arguments": "{\"order_id\": \"INV-1042\"}" }
      }
    ]
  },
  {
    "role": "tool",
    "tool_call_id": "call_0",
    "content": "{\"order_id\": \"INV-1042\", \"status\": \"shipped\", \"courier\": \"JNE\", \"eta_days\": 2}"
  }
]

Lalu model menjawab: "Pesanan INV-1042 Anda sudah dikirim lewat JNE dan diperkirakan tiba dalam sekitar 2 hari."

Mengatur pemakaian tool

`tool_choice`	Perilaku
`"auto"` (default jika ada tools)	Model memutuskan sendiri apakah perlu memanggil tool.
`"none"`	Model menjawab dengan teks dan tidak memanggil tool.
`"required"`	Model wajib memanggil setidaknya satu tool.
`{"type": "function", "function": {"name": "get_order_status"}}`	Model wajib memanggil fungsi tersebut.

Tips

Validasi argumen. function.arguments adalah string JSON yang ditulis model. Parse dengan hati-hati dan cocokkan dengan schema Anda sebelum menjalankan apa pun.
Beberapa panggilan sekaligus. Satu respons bisa berisi lebih dari satu entri di tool_calls. Jawab semuanya, masing-masing dengan tool_call_id-nya sendiri, sebelum request berikutnya.
Streaming. Dengan "stream": true, tool call datang sebagai potongan delta.tool_calls; gabungkan function.arguments berdasarkan index sampai finish_reason bernilai "tool_calls".
Biaya token. Definisi tool adalah bagian dari prompt dan dihitung sebagai token input di setiap request. Awalan yang panjang dan tetap — system prompt, tools — sering dilayani dari cache dengan harga yang lebih murah.