Cara Menggunakan OpenAI Function Calling

Pada akhir panduan ini, Anda akan dapat mendefinisikan alat, mengirimkannya ke OpenAI, membaca panggilan alat yang dikembalikan model, dan menjalankan fungsi Anda sendiri dengan argumen terstruktur yang disediakannya. Anda juga akan mengaktifkan mode ketat (strict mode) dan panggilan paralel (parallel calls), lalu melakukan asersi dan mock sisi alat dengan Apidog agar Anda memercayai keluarannya sebelum mencapai produksi. Biarkan dokumentasi panggilan fungsi OpenAI tetap terbuka di tab lain sebagai sumber kebenaran, dan lihat pengantar kami tentang membangun agen dengan OpenAI Agents SDK untuk gambaran tingkat yang lebih tinggi.

Apa yang Anda perlukan sebelum memulai

Panggilan fungsi (sering disebut panggilan alat) adalah cara model terhubung ke kode dan sistem eksternal Anda. Anda menjelaskan fungsi yang diekspos aplikasi Anda, model membaca permintaan pengguna, dan ketika suatu fungsi cocok, ia mengembalikan nama fungsi ditambah objek JSON dari argumen. Model tidak pernah menjalankan apa pun sendiri. Ia menyerahkan permintaan terstruktur kepada Anda, dan kode Anda yang melakukan pekerjaan.

Pemisahan itulah yang perlu diingat saat Anda membangun. Model memilih maksud dan mengisi parameter. Anda tetap memegang kendali atas eksekusi. Pesan “dapatkan cuaca di Paris” berubah menjadi panggilan get_weather({"location": "Paris, France"}) yang rapi alih-alih paragraf yang harus Anda uraikan secara manual.

Untuk mengikuti, Anda memerlukan kunci API OpenAI dan fungsi di kode Anda sendiri yang ingin Anda picu oleh model. Satu hal lagi yang perlu diputuskan di awal: endpoint mana yang Anda gunakan. Fitur yang sama berfungsi di dua tempat. API Chat Completions yang lebih lama mendukungnya, dan begitu pula API Responses yang lebih baru, yang menyatukan apa yang sebelumnya terpisah di Chat Completions dan Assistants API. Bentuknya sedikit berbeda, dan langkah-langkah di bawah ini mencakup keduanya.

Langkah 1: Definisikan alat Anda

Alat adalah definisi fungsi yang dapat dibaca model. Anda memberikannya nama, deskripsi, dan Skema JSON untuk argumen. Deskripsi di sini benar-benar berfungsi. Deskripsi ini memberi tahu model kapan harus menggunakan fungsi tersebut, jadi tulis seperti instruksi, bukan label.

Berikut adalah definisi alat dalam bentuk Chat Completions, di mana fungsi berada di bawah wrapper function:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city. Use when the user asks about temperature or conditions.",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City and country, e.g. Bogotá, Colombia"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"]
        }
      },
      "required": ["location"],
      "additionalProperties": false
    }
  }
}

Responses API meratakan ini. Bidang name, description, parameters, dan strict berada di tingkat teratas objek alat, tanpa kunci function yang bertumpuk. Informasi yang sama, lapisan yang lebih sedikit.

Jika Anda sudah memelihara spesifikasi OpenAPI untuk layanan yang mendasarinya, bentuk parameter hampir langsung diturunkan. Panduan kami tentang membuat koleksi uji dari spesifikasi OpenAPI menunjukkan bagaimana pekerjaan skema tersebut memberikan keuntungan ganda.

Langkah 2: Buat permintaan pertama Anda

Kirim alat Anda ke model bersama dengan pesan pengguna. Permintaan Chat Completions lengkap yang melakukan ini terlihat seperti berikut:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "What is the weather in Paris right now?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a city.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string"}
            },
            "required": ["location"],
            "additionalProperties": false
          }
        }
      }
    ]
  }'

Array tools membawa setiap fungsi yang ingin Anda ekspos untuk giliran ini. Model membaca pesan pengguna, memutuskan apakah ada alat yang cocok, dan merespons. Ketika ia memilih satu, Anda mendapatkan panggilan alat kembali alih-alih prosa, yaitu yang akan Anda baca di langkah berikutnya.

Langkah 3: Baca panggilan alat yang dikembalikan model

Ketika model memutuskan untuk memanggil suatu fungsi, ia tidak mengembalikan teks. Ia mengembalikan panggilan alat yang Anda baca dari respons.

Di Chat Completions, pesan asisten membawa array tool_calls. Setiap entri memiliki id, type berupa function, dan objek function dengan name dan string arguments:

{
  "id": "call_12345xyz",
  "type": "function",
  "function": {
    "name": "get_weather",
    "arguments": "{\"location\":\"Paris, France\"}"
  }
}

Di Responses API, panggilan muncul di array output dengan bentuk yang lebih datar: type berupa function_call, call_id, name, dan arguments:

{
  "type": "function_call",
  "call_id": "call_12345xyz",
  "name": "get_weather",
  "arguments": "{\"location\":\"Paris, France\"}"
}

Satu detail yang sering membuat orang bingung: arguments adalah string yang dienkode JSON, bukan objek yang sudah di-parsing. Anda menguraikannya sendiri, menjalankan fungsi Anda, lalu mengirimkan hasilnya kembali agar model dapat menyelesaikan balasannya.

Langkah 4: Kembalikan hasilnya ke model

Setelah Anda menjalankan fungsi Anda, serahkan hasilnya kembali agar model dapat menghasilkan jawaban akhir. Di Chat Completions, Anda menambahkan pesan peran tool yang dikaitkan dengan id panggilan. Di Responses API, Anda mengirim item function_call_output yang dikaitkan dengan call_id. Bagaimanapun, alurnya sama: model bertanya, Anda menjalankan, Anda mengembalikan hasilnya, model merespons.

Langkah 5: Tambahkan panggilan paralel dan mode ketat

Dua pengaturan mengubah seberapa andal dan seberapa cepat ini terjadi, dan Anda menambahkannya setelah alur dasar berfungsi.

Panggilan alat paralel. Secara default, model dapat mengembalikan lebih dari satu panggilan alat dalam satu giliran. Jika pengguna menanyakan cuaca di tiga kota, Anda mungkin mendapatkan tiga panggilan sekaligus dan dapat menjalankannya secara bersamaan. Jika Anda lebih suka memaksakan paling banyak satu panggilan per giliran, atur parallel_tool_calls ke false.

Mode ketat. Atur strict: true pada definisi fungsi dan argumen model dijamin sesuai dengan Skema JSON Anda alih-alih hanya upaya terbaik. OpenAI merekomendasikan untuk selalu mengaktifkannya. Mode ketat memiliki aturan: setiap objek memerlukan additionalProperties: false, dan setiap bidang dalam properties harus muncul di required. Untuk membuat bidang opsional, Anda tidak menghapusnya dari required; Anda menambahkan null ke daftar jenis yang diizinkan.

Aturan bidang opsional seringkali mengejutkan orang. Katakanlah unit bersifat opsional di get_weather. Dalam mode ketat, Anda tetap mencantumkannya di required, lalu menandainya sebagai nullable di skema, seperti "unit": {"type": ["string", "null"], "enum": ["celsius", "fahrenheit"]}. Model sekarang dapat meneruskan unit nyata atau null eksplisit, tetapi tidak pernah dapat menghilangkan kunci tersebut. Prediktabilitas itulah intinya: kode parsing Anda tahu persis kunci mana yang harus diharapkan setiap saat.

Mode ketat mengurangi JSON yang salah format, tetapi tidak memeriksa apakah nilai-nilai tersebut masuk akal secara bisnis. Lokasi bisa valid secara skema dan tetap menjadi kota yang tidak Anda layani. Di situlah pengujian berperan.

Cara mengujinya di Apidog

Model memberi Anda panggilan alat. Sebelum Anda menghubungkannya ke fungsi langsung, Anda menginginkan dua jaminan: argumen cocok dengan bentuk yang Anda harapkan, dan API hilir yang akan diakses fungsi Anda berperilaku seperti yang Anda asumsikan. Apidog mencakup kedua sisi tersebut, dan ada baiknya untuk lebih tepat mengenai hal tersebut.

Apidog memvalidasi dan memalsukan sisi API. Ia tidak mengeksekusi fungsi aplikasi Anda. Yang ia lakukan dengan baik adalah kontrak di sekitarnya.

Asersikan struktur argumen. Ambil string arguments dari panggilan alat yang sebenarnya, perlakukan sebagai badan permintaan, dan jalankan asersi di Apidog. Periksa apakah location ada dan merupakan string, bahwa bidang enum hanya berisi nilai yang diizinkan, bahwa bidang yang wajib ada. Mengambil bidang tertentu dari payload mudah dilakukan dengan ekspresi JSONPath, dan untuk pemeriksaan struktural yang lebih dalam ada validasi terhadap Skema JSON, yang mencerminkan skema yang sama yang Anda berikan kepada OpenAI dalam mode ketat. Jika keluaran model melewati skema yang sama dengan yang diharapkan fungsi Anda, Anda telah menutup lingkaran.

Mock API hilir yang akan dipanggil fungsi. Fungsi get_weather Anda mungkin memanggil penyedia cuaca. Selama pengembangan, penyedia tersebut mungkin dibatasi laju, berbayar, atau belum dibangun. Buat API mock di Apidog yang mengembalikan payload cuaca yang realistis, arahkan fungsi Anda ke mock, dan latih seluruh jalur panggilan tanpa menghabiskan permintaan pada layanan nyata. Anda mengontrol respons, termasuk kasus kesalahan yang jarang dihasilkan API langsung sesuai permintaan, sehingga Anda dapat mengonfirmasi bahwa kode Anda menangani batas waktu atau kode 429 sebelum pengguna menemukannya.

Secara keseluruhan, alurnya adalah: menangkap panggilan alat dari OpenAI, mengasersi argumennya terhadap skema Anda di Apidog, lalu menjalankan fungsi Anda terhadap mock Apidog dari API nyata. Anda memverifikasi kontrak di kedua sisi tanpa menghabiskan panggilan langsung atau menebak-nebak kasus ekstrem.

Pertanyaan yang Sering Diajukan

Apakah panggilan fungsi berfungsi di Chat Completions dan Responses API? Ya. Kedua endpoint mendukungnya. Responses API menyatukan kemampuan yang sebelumnya terpisah antara Chat Completions dan Assistants API. Perbedaan utamanya adalah bentuk: Chat Completions menumpuk fungsi di bawah kunci function dan mengembalikan tool_calls, sedangkan Responses API menggunakan definisi alat datar dan mengembalikan item function_call di array output.

Mengapa model mengembalikan argumen sebagai string, bukan objek? Bidang arguments adalah teks yang dienkode JSON. Anda menguraikannya di kode Anda sebelum menggunakannya. Ini konsisten di kedua API, jadi selalu jalankan melalui parser JSON Anda dan validasi hasilnya daripada mempercayainya secara membabi buta. Menjalankan argumen tersebut melalui validasi Skema JSON akan menangkap payload yang salah format sebelum mencapai fungsi Anda.

Apakah mode ketat menjamin fungsi akan berhasil? Tidak. Mode ketat menjamin argumen sesuai dengan Skema JSON Anda, sehingga strukturnya dapat diandalkan. Ia tidak memeriksa apakah nilai-nilai tersebut benar untuk logika bisnis Anda, dan ia tidak menjalankan fungsi Anda. Anda tetap memvalidasi nilai dan menangani kegagalan panggilan hilir sendiri.

Bisakah Apidog menjalankan fungsi saya yang sebenarnya? Tidak, dan ia tidak mencoba. Apidog memvalidasi argumen yang dihasilkan model dan memalsukan API yang bergantung pada fungsi Anda. Aplikasi Anda masih mengeksekusi fungsi-fungsinya sendiri. Apidog mencakup kontrak di kedua sisi sehingga Anda mempercayai input dan dependensi sebelum tayang.

Ringkasan

Anda sekarang memiliki alur lengkap: definisikan alat Anda dengan jelas, kirimkan dengan permintaan, baca keluaran tool_calls atau function_call, kembalikan hasilnya, lalu aktifkan mode ketat dan putuskan apakah panggilan paralel membantu atau merugikan. Akhiri dengan pengujian dengan memastikan argumen sesuai dengan skema Anda dan memalsukan API hilir agar Anda yakin sebelum produksi.

Ingin mencoba sisi pengujian? Unduh Apidog untuk mengasersi argumen panggilan alat terhadap skema Anda dan memalsukan API yang bergantung pada fungsi Anda, semuanya di satu tempat.