Integrasi OpenAPI dengan Alat Agen AI: Tanpa Wrapper Kode Manual

Sebagian besar basis kode agen berisi berkas yang tidak seorang pun suka memeliharanya. Berkas tersebut berisi empat puluh definisi alat, masing-masing adalah skema JSON yang ditulis tangan yang menjelaskan titik akhir yang sudah memiliki skema di tempat lain. Tim API mengirimkan bidang wajib baru, spesifikasi diperbarui, dokumentasi diperbarui, dan agen terus mengirimkan muatan lama sampai seseorang menyadari adanya kode 400.

Anda sudah memiliki deskripsi yang dapat dibaca mesin untuk setiap titik akhir. Itu adalah dokumen OpenAPI. Tugasnya adalah mengubahnya menjadi definisi alat yang dapat dipanggil oleh model, dan menjaga keduanya tetap sinkron secara otomatis, bukan secara manual.

Panduan ini membahas bagaimana operasi OpenAPI dipetakan ke skema alat, apa yang harus diperbaiki oleh generator, cara memangkas spesifikasi 200 titik akhir menjadi sesuatu yang dapat dipahami model, dan cara menguji perilaku alat yang dihasilkan. Jika Anda berada di tahap awal, postingan kami tentang apakah Anda masih memerlukan alat API saat agen menulis kode memberikan konteks yang lebih luas.

Apidog penting di sini karena spesifikasi harus benar sebelum apa pun yang dihasilkan darinya dapat berfungsi. Sebuah definisi alat mewarisi setiap celah dalam dokumen asalnya.

Biaya definisi alat yang ditulis tangan

Menulis alat secara manual terasa baik-baik saja pada lima titik akhir. Namun akan menjadi masalah di sekitar dua puluh titik akhir, karena tiga alasan.

Definisi bergeser. Spesifikasi dihasilkan dari kode atau dikelola oleh tim API. Berkas alat dikelola oleh siapa pun yang membangun agen. Tidak ada yang menghubungkan keduanya, sehingga mereka menyimpang secara diam-diam, dan gejala pertamanya adalah agen yang “tiba-tiba” berhenti berfungsi.

Deskripsi menjadi tipis. Ketika seseorang menulis empat puluh skema secara manual, dua puluh skema terakhir hanya mendapatkan deskripsi satu baris. Model memilih alat dengan membaca deskripsi tersebut, sehingga teks yang tipis secara langsung menurunkan pemilihan alat. Postingan kami tentang desain skema alat untuk agen membahas lebih dalam mengapa pemilihan kata begitu penting.

Kesalahan tidak terlihat sampai waktu berjalan (runtime). Skema yang ditulis tangan yang menyatakan bahwa sebuah bidang adalah string ketika API menginginkan integer akan menghasilkan 422 pertama kali agen mencobanya, dalam produksi, pada tugas nyata.

Membangkitkan dari spesifikasi memperbaiki ketiganya sekaligus. Ada satu sumber kebenaran, deskripsi berasal dari teks yang sama yang digunakan dokumen Anda, dan jenis berasal dari skema yang sama yang divalidasi oleh server.

Bagaimana operasi OpenAPI menjadi alat

Pemetaan ini lebih langsung dari yang terlihat. Ambil satu operasi:

paths:
  /orders/{orderId}/refund:
    post:
      operationId: refundOrder
      summary: Refund an order
      description: >
        Issues a full or partial refund against a completed order.
        Refunds are irreversible. Partial refunds require an amount
        no greater than the remaining refundable balance.
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
          description: The order to refund.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                amount:
                  type: integer
                  description: Amount in cents. Omit for a full refund.
                reason:
                  type: string
                  enum: [duplicate, fraudulent, requested_by_customer]

Definisi alat yang dihasilkan darinya:

{
  "name": "refundOrder",
  "description": "Issues a full or partial refund against a completed order. Refunds are irreversible. Partial refunds require an amount no greater than the remaining refundable balance.",
  "input_schema": {
    "type": "object",
    "required": ["orderId", "reason"],
    "properties": {
      "orderId": { "type": "string", "description": "The order to refund." },
      "amount": { "type": "integer", "description": "Amount in cents. Omit for a full refund." },
      "reason": { "type": "string", "enum": ["duplicate", "fraudulent", "requested_by_customer"] }
    }
  }
}

Empat aturan melakukan sebagian besar pekerjaan:

operationId menjadi nama alat. Jika suatu operasi tidak memiliki operationId, buatlah yang stabil dari metode ditambah path, lalu tambahkan ke spesifikasi.
Parameter path, query, dan body diratakan menjadi satu objek properti. Model tidak peduli di mana nilai tersebut melewati jaringan. Eksekutor Anda peduli, jadi simpan tabel samping yang mencatat parameter mana pergi ke mana.
summary ditambah description menjadi deskripsi alat. Keduanya, digabungkan. Ringkasan saja biasanya terlalu singkat untuk memandu pemilihan.
Array wajib digabungkan. Parameter path wajib dan bidang body wajib keduanya masuk ke daftar required yang sama.

Eksekutor adalah bagian lainnya, dan ukurannya kecil:

def execute(tool_name, args, spec_index, http):
    op = spec_index[tool_name]          # method, path template, param locations
    path = op.path
    query, body = {}, {}

    for name, value in args.items():
        location = op.locations[name]   # "path" | "query" | "header" | "body"
        if location == "path":
            path = path.replace("{" + name + "}", str(value))
        elif location == "query":
            query[name] = value
        elif location == "body":
            body[name] = value

    return http.request(op.method, path, params=query, json=body or None)

Itulah keseluruhan jembatannya. Semua yang lain adalah pembersihan dalam prosesnya.

Apa yang harus diperbaiki oleh generator

Pembuangan spesifikasi secara naif ke dalam skema alat menghasilkan alat yang tidak ditangani dengan baik oleh model. Lima penyesuaian penting.

Selesaikan pointer $ref. Sebagian besar API pemanggil alat menerima subset JSON Schema dan tidak akan mengikuti referensi ke bagian components. Sisipkan secara inline. Perhatikan skema rekursif, yang penyisipan secara inline akan mengembang selamanya; potong rekursi pada kedalaman tetap dan jelaskan struktur yang lebih dalam dalam prosa.
Jatuhkan kata kunci yang tidak didukung. oneOf, allOf, discriminator, dan nullable umum dalam spesifikasi dan kurang didukung oleh skema alat. Gabungkan allOf dengan menggabungkan properti. Untuk oneOf, pilih varian dominan atau pisahkan operasi menjadi dua alat, satu per bentuk. Opsi kedua itu biasanya menghasilkan pemilihan alat yang lebih baik.
Ratakan penumpukan mendalam. Tubuh yang bertingkat tiga sulit diisi dengan benar oleh model. Jika payload create-order Anda menyarangkan customer.address.postal_code, pertimbangkan permukaan alat yang lebih datar dan rakit ulang bentuk bersarang di eksekutor.
Pangkas skema respons. Definisi alat menggambarkan input. Skema respons lengkap tidak termasuk dalam definisi, dan memasukkannya hanya membuang konteks. Seperti apa responsnya penting ketika hasilnya kembali, dan itu adalah masalah terpisah yang dibahas dalam postingan kami tentang menjaga respons API di dalam jendela konteks agen.
Bawa tanda pengaman. Operasi tulis harus ditandai agar eksekutor Anda dapat mengarahkannya melalui gerbang persetujuan. Jika spesifikasi Anda menggunakan ekstensi seperti x-agent-requires-approval, bacalah dan patuhi. Pasangkan ini dengan pola dalam panduan perlindungan agen AI kami.

Jangan berikan semua 200 titik akhir ke model

Masalah praktis terbesar bukanlah konversi. Ini adalah volume. API yang matang memiliki ratusan operasi, dan menempelkan semuanya ke dalam daftar alat menghasilkan dua kegagalan sekaligus: konteks terisi dengan skema sebelum tugas dimulai, dan akurasi pemilihan menurun karena model memilih di antara opsi yang hampir identik.

Tiga cara untuk menguranginya, kira-kira berdasarkan seberapa baik kinerjanya.

Saring berdasarkan tag. Operasi OpenAPI membawa tag, dan tag biasanya memetakan ke area produk. Agen yang menangani pengembalian dana membutuhkan tag orders dan payments, bukan admin atau analytics. Ini adalah filter satu baris dan biasanya menghilangkan sebagian besar permukaan.
Kurasi daftar izin (allowlist). Catat operasi yang diizinkan untuk dipanggil oleh agen ini, berdasarkan operationId, dan hanya hasilkan operasi tersebut. Ini juga berfungsi sebagai kontrol keamanan, karena agen yang tidak memiliki alat untuk titik akhir tidak dapat memanggilnya secara tidak sengaja. Postingan kami tentang menghentikan agen merusak API Anda berpendapat untuk jenis permukaan sempit seperti ini.
Ambil alat sesuai permintaan. Untuk API yang sangat besar, indeks operasi dan pilih beberapa per giliran berdasarkan tugas. Ini menambahkan langkah pengambilan dan mode kegagalannya sendiri, jadi gunakan hanya setelah pemfilteran dan kurasi tidak lagi cukup.

Ada juga jalur protokol. Model Context Protocol menstandardisasi cara server mengekspos alat ke klien, dan server MCP yang didukung oleh dokumen OpenAPI Anda memberi Anda satu titik integrasi alih-alih satu per framework. Penjelasan kami tentang apa itu MCP mencakup modelnya, dan membangun server MCP dengan Apidog mencakup pembangunannya.

Spesifikasi harus benar terlebih dahulu

Generasi memindahkan masalah kualitas ke hulu. Deskripsi yang tidak jelas dalam dokumen OpenAPI Anda menjadi deskripsi alat yang tidak jelas, dan model memilih titik akhir yang salah. Bidang opsional yang sebenarnya wajib oleh server menjadi alat yang dipanggil agen secara salah pada percobaan pertama.

Jadi, audit spesifikasi melalui sudut pandang agen sebelum Anda menghasilkan apa pun:

Setiap operasi memiliki operationId, dan itu terbaca seperti kata kerja ditambah kata benda.
Setiap operasi memiliki deskripsi yang menyatakan apa yang dilakukannya, apa yang diubahnya, dan kapan tidak menggunakannya. 'Menghapus pengguna' tidak cukup. 'Menghapus pengguna secara permanen dan semua sesi mereka. Tidak dapat dibatalkan. Gunakan deactivateUser untuk menonaktifkan akses sementara.' itu yang benar.
Setiap parameter memiliki deskripsi dengan unit dan format. amount ambigu. 'Jumlah dalam sen, minimum 50' tidak ambigu.
Enum dideklarasikan daripada dijelaskan dalam prosa, sehingga model mendapatkan set tertutup alih-alih menebak.
Wajib itu akurat. Spesifikasi cenderung menandai semuanya sebagai opsional, yang mendorong kegagalan validasi ke waktu berjalan.

Ini adalah kebersihan spesifikasi biasa, dan memberikan keuntungan ganda, karena teks yang sama menggerakkan dokumen publik Anda. Di Apidog, spesifikasi, dokumen, mock server, dan pengujian berasal dari satu proyek, sehingga mengencangkan deskripsi meningkatkan semuanya sekaligus. Panduan kami tentang mengelola versi API di Apidog mencakup separuh lainnya untuk menjaga alat yang dihasilkan tetap jujur dari waktu ke waktu.

Bagikan set alat, jangan salin

Satu set alat yang dihasilkan adalah konfigurasi, dan konfigurasi yang berada di satu checkout pengembang akan bergeser dengan cara yang sama seperti skema yang ditulis tangan. Daftar filter, daftar izin, dan versi spesifikasi yang disematkan harus menjadi artefak bersama, yang diverifikasi di samping spesifikasi asalnya.

Beberapa platform menjadikan ini unit default. Di Sharkly, Agen adalah konfigurasi kerja yang disimpan alih-alih perintah sekali pakai: instruksi, Runtime, Keahlian, repositori, dan pengaturan jalannya ikut dengannya dan dapat dibagikan di seluruh Ruang, sehingga pengaturan alat yang berfungsi menjadi sesuatu yang digunakan kembali oleh tim alih-alih sesuatu yang dibangun kembali oleh setiap orang. Runtime di bawahnya masih Claude Code, Codex, atau apa pun yang sudah Anda jalankan. Yang berubah adalah konfigurasi di sekitarnya berhenti menjadi lokal.

Menguji alat yang dihasilkan

Alat yang dihasilkan gagal dengan cara yang tidak terjadi pada alat yang ditulis tangan, jadi ujilah generasi dan juga panggilannya.

Mulai dengan pemeriksaan round-trip skema. Untuk setiap alat yang dihasilkan, buat contoh yang valid dari skema dan kirimkan. Apa pun yang mengembalikan 400 atau 422 berarti skema alat dan server tidak setuju, dan spesifikasi adalah hal yang harus diperbaiki.

Kemudian uji pemilihan. Tulis serangkaian kecil prompt tugas dengan alat yang diketahui benar, jalankan, dan catat alat mana yang dipilih model. Ini adalah suite regresi murah yang menangkap saat seseorang mengganti nama operasi atau memperpendek deskripsi. Karena outputnya tidak deterministik, pastikan nama alat daripada argumen yang tepat, sejalan dengan panduan kami untuk menguji agen non-deterministik.

Terakhir, jalankan agen terhadap mock sebelum apa pun yang bersifat langsung. Mock server yang dihasilkan dari spesifikasi yang sama memberi Anda respons yang realistis tanpa efek samping, dan memungkinkan Anda menyuntikkan 500 dan batas waktu yang seharusnya ditangani oleh logika percobaan ulang Anda.

Di mana ini menempatkan Anda

Spesifikasi adalah kontrak, dan daftar alat harus menjadi proyeksi darinya, bukan salinan paralel yang dipelihara secara manual. Hasilkan alat-alatnya, saring dengan ketat, jaga deskripsinya tetap jujur, dan uji baik bentuk maupun pemilihannya.

Mulailah dengan mengekspor dokumen OpenAPI Anda dan menghitung operasi yang tidak memiliki deskripsi. Angka itu adalah seberapa banyak pekerjaan yang ada di antara Anda dan alat agen yang dapat Anda percaya. Unduh Apidog jika Anda ingin spesifikasi, mock, dan pengujian dalam satu tempat saat Anda memperbaikinya.

Pertanyaan yang sering diajukan

Dapatkah saya membuat alat dari dokumen Swagger 2.0? Ya, tetapi konversikan ke OpenAPI 3.x terlebih dahulu. Model body 2.0 cukup berbeda sehingga generator menanganinya secara tidak konsisten, dan 3.x adalah target alat saat ini. Repositori Spesifikasi OpenAPI mendokumentasikan perbedaannya.

Berapa banyak alat yang dapat ditangani model sekaligus? Akurasi mulai menurun jauh sebelum batas teknis, dan batas praktisnya biasanya beberapa lusin. Anggap daftar apa pun di luar itu sebagai sinyal untuk memfilter berdasarkan tag atau mengkurasi daftar izin (allowlist) daripada sebagai batasan untuk diuji.

Haruskah nama alat cocok persis dengan operationId? Ya, ketika operationId mudah dibaca. Ini memberi Anda pencarian langsung dari panggilan alat kembali ke operasi spesifikasi, yang membuat pelacakan dan debugging jauh lebih mudah. Ganti nama dalam spesifikasi jika namanya buruk, bukan di generator.

Bagaimana dengan API GraphQL? Ide yang sama berlaku dengan sumber yang berbeda: introspeksi skema dan hasilkan alat per query atau mutasi. Masalah volume lebih buruk karena skema GraphQL mengekspos lebih banyak permukaan, jadi pemfilteran menjadi lebih penting.

Apakah saya masih perlu menulis alat secara manual? Beberapa. Alat komposit yang menggabungkan beberapa panggilan menjadi satu tindakan, dan alat yang membungkus sesuatu selain HTTP, masih ditulis secara manual. Intinya adalah pembungkus satu titik akhir yang rutin berhenti menjadi pekerjaan manual.

Bagaimana cara menghentikan agen dari memanggil titik akhir tulis selama pengujian? Hasilkan set alat hanya-baca untuk uji coba dengan memfilter berdasarkan metode HTTP, dan arahkan agen ke mock untuk apa pun yang menulis. Postingan kami tentang mengapa agen harus menggunakan mock, bukan produksi mencakup pengaturan tersebut.