Integrasi OpenAPI dengan Alat Agen AI: Tanpa Wrapper Kode Manual

Membuat Tool Agen dari OpenAPI agar Selalu Sinkkron

Basis kode agen sering berisi puluhan definisi tool yang ditulis tangan—padahal setiap endpoint sudah memiliki kontrak yang dapat dibaca mesin di dokumen OpenAPI. Saat tim API menambah field wajib, spesifikasi dan dokumentasi berubah, tetapi tool agen tetap mengirim payload lama hingga error 400 atau 422 muncul di produksi.

Coba Apidog hari ini

Solusinya: jadikan spesifikasi OpenAPI sebagai satu-satunya sumber kebenaran, hasilkan definisi tool dari sana, lalu uji hasilnya. Jika Anda masih mempertimbangkan kebutuhan tool API untuk agen yang menulis kode, baca apakah Anda masih memerlukan alat API saat agen menulis kode.

Mengapa definisi tool manual bermasalah

Menulis lima tool secara manual mungkin terasa cepat. Pada dua puluh endpoint atau lebih, pendekatan ini mulai gagal:

• Definisi bergeser. Spesifikasi dikelola tim API, sedangkan file tool dikelola tim agen. Tanpa koneksi otomatis, keduanya menyimpang.
• Deskripsi menjadi terlalu tipis. Model memilih tool berdasarkan nama dan deskripsi. Deskripsi satu baris menurunkan akurasi pemilihan. Lihat desain skema alat untuk agen untuk pembahasannya.
• Kesalahan baru terlihat saat runtime. Jika tool mendeklarasikan string sementara API meminta integer, kegagalan baru muncul saat agen benar-benar memanggil endpoint.

Generator berbasis OpenAPI memperbaiki ketiganya: satu sumber kebenaran, deskripsi yang konsisten dengan dokumentasi, dan tipe yang sama dengan validasi server.

Memetakan operasi OpenAPI menjadi tool

Contoh operasi OpenAPI:

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]

Tool yang dihasilkan:

{
  "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"] }
    }
  }
}

Gunakan empat aturan berikut saat membangun generator:

1. Gunakan operationId sebagai nama tool. Jika belum ada, buat nama stabil dari HTTP method dan path, lalu simpan kembali ke spesifikasi.
2. Ratakan parameter path, query, dan body menjadi satu objek input. Simpan metadata lokasi parameter untuk eksekutor.
3. Gabungkan summary dan description menjadi deskripsi tool. Ringkasan saja biasanya tidak cukup untuk memandu model.
4. Gabungkan seluruh field wajib dari parameter dan request body ke satu array required.

Eksekutor HTTP-nya tetap 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)

Normalisasi yang harus dilakukan generator

Jangan langsung membuang seluruh spesifikasi ke daftar tool. Lakukan normalisasi berikut:

• Selesaikan $ref. Banyak API tool hanya mendukung subset JSON Schema dan tidak mengikuti referensi components. Inline schema, tetapi batasi kedalaman untuk struktur rekursif.
• Tangani keyword yang tidak didukung. oneOf, allOf, discriminator, dan nullable sering tidak bekerja baik pada tool schema. Gabungkan allOf; untuk oneOf, pilih varian dominan atau pecah menjadi beberapa tool.
• Kurangi nesting yang terlalu dalam. Payload seperti customer.address.postal_code sulit diisi model. Buat input tool lebih datar bila perlu, lalu susun ulang payload di eksekutor.
• Jangan masukkan response schema. Definisi tool menjelaskan input. Response lengkap hanya menghabiskan context window. Strategi penanganan response dibahas di menjaga respons API di dalam jendela konteks agen.
• Bawa metadata pengaman. Tandai operasi tulis agar eksekutor dapat mengarahkannya ke approval gate. Jika spesifikasi memakai x-agent-requires-approval, patuhi nilainya. Terapkan juga prinsip dalam perlindungan agen AI.

Jangan kirim 200 endpoint sekaligus ke model

Masalah terbesar biasanya bukan konversi, melainkan jumlah tool. Daftar yang terlalu besar menghabiskan context window dan menurunkan akurasi karena model harus memilih di antara operasi serupa.

Gunakan urutan strategi ini:

1. Filter berdasarkan tag. Agen refund hanya memerlukan tag seperti orders dan payments, bukan admin atau analytics.
2. Gunakan allowlist berdasarkan operationId. Selain mengurangi context, ini menjadi pembatas keamanan: agen tidak dapat memanggil endpoint yang tidak tersedia sebagai tool. Pendekatan ini dijelaskan dalam menghentikan agen merusak API Anda.
3. Ambil tool sesuai permintaan. Untuk API yang sangat besar, indeks operasi dan ambil beberapa tool paling relevan per giliran. Gunakan ini hanya jika filter dan allowlist belum cukup.

Anda juga dapat mengekspos tool melalui Model Context Protocol. Pelajari konsepnya di apa itu MCP, lalu lihat cara membangun server MCP dengan Apidog.

Perbaiki spesifikasi sebelum menghasilkan tool

Generator hanya sebaik spesifikasi asalnya. Audit OpenAPI dari perspektif agen:

• Setiap operasi memiliki operationId yang mudah dibaca, idealnya kata kerja + kata benda.
• Deskripsi menjelaskan tindakan, dampak, dan kapan tool tidak boleh digunakan.
• Setiap parameter menjelaskan unit dan formatnya. Misalnya, gunakan Amount in cents, minimum 50, bukan hanya amount.
• Deklarasikan enum di schema, bukan hanya dalam prosa.
• Pastikan field required benar-benar akurat.

Contoh deskripsi yang berguna:

Menghapus pengguna secara permanen dan semua sesi mereka. Tidak dapat dibatalkan. Gunakan deactivateUser untuk menonaktifkan akses sementara.

Di Apidog, spesifikasi, dokumentasi, mock server, dan pengujian berasal dari satu proyek. Perbaikan deskripsi akan meningkatkan seluruh permukaan tersebut. Untuk menjaga spesifikasi tetap konsisten antarperubahan, baca mengelola versi API di Apidog.

Bagikan konfigurasi tool

Tool hasil generate tetap merupakan konfigurasi. Simpan dan bagikan:

• filter tag;
• allowlist operationId;
• versi spesifikasi yang dipakai;
• aturan approval untuk operasi tulis.

Jangan biarkan konfigurasi hanya ada di checkout satu developer. Sebagai contoh, Sharkly menyimpan Agen sebagai konfigurasi kerja yang dapat dibagikan: instruksi, Runtime, Keahlian, repositori, dan pengaturan eksekusi. Runtime-nya tetap dapat berupa Claude Code, Codex, atau tooling lain; yang dibagikan adalah konfigurasi operasional di sekitarnya.

Uji tool hasil generate

Uji generator dan pemanggilan tool-nya.

1. Uji round-trip schema

Untuk setiap tool yang dihasilkan:

1. Buat contoh input valid berdasarkan schema tool.
2. Kirim ke endpoint atau mock server.
3. Investigasi setiap respons 400 atau 422.

Error tersebut berarti tool schema dan validasi server tidak sepakat—biasanya spesifikasi asal yang perlu diperbaiki.

2. Uji pemilihan tool

Buat suite kecil berisi prompt tugas dengan tool yang seharusnya dipilih. Jalankan secara berkala dan cek nama tool yang dipilih model.

Karena output model tidak deterministik, verifikasi nama tool, bukan argumen yang harus identik. Pendekatan ini mengikuti praktik di menguji agen non-deterministik.

3. Uji terhadap mock sebelum produksi

Jalankan agen terhadap mock server yang dihasilkan dari spesifikasi yang sama. Dengan begitu Anda mendapat respons realistis tanpa efek samping dan dapat menyuntikkan 500, timeout, atau error lain untuk menguji retry logic.

Ringkasan

Daftar tool agen harus menjadi proyeksi dari OpenAPI, bukan salinan paralel yang dipelihara manual:

• hasilkan tool dari spesifikasi;
• normalisasi schema untuk kemampuan model;
• filter tool secara ketat;
• bawa metadata approval;
• uji kecocokan schema, pemilihan tool, dan error handling melalui mock.

Mulailah dengan menghitung operasi OpenAPI yang belum memiliki deskripsi. Angka tersebut menunjukkan pekerjaan yang perlu dilakukan sebelum agen dapat menggunakan API dengan andal. Anda dapat mengunduh Apidog untuk mengelola spesifikasi, mock, dan pengujian dalam satu tempat.

Pertanyaan yang sering diajukan

Dapatkah saya membuat tool dari dokumen Swagger 2.0?

Ya, tetapi konversikan ke OpenAPI 3.x terlebih dahulu. Model request body Swagger 2.0 berbeda cukup jauh dan generator menanganinya secara tidak konsisten. Lihat Repositori Spesifikasi OpenAPI untuk perbedaannya.

Berapa banyak tool yang dapat ditangani model sekaligus?

Akurasi biasanya menurun jauh sebelum batas teknis context window. Batas praktisnya sering hanya beberapa lusin tool. Jika daftar lebih besar, filter berdasarkan tag atau gunakan allowlist.

Haruskah nama tool sama persis dengan operationId?

Ya, selama operationId mudah dibaca. Ini membuat tracing dari tool call kembali ke operasi OpenAPI jauh lebih mudah. Jika namanya buruk, perbaiki di spesifikasi, bukan di generator.

Bagaimana dengan API GraphQL?

Prinsipnya sama: introspeksi schema lalu hasilkan tool untuk query atau mutation. Karena GraphQL sering mengekspos permukaan lebih luas, filtering menjadi lebih penting.

Apakah saya masih perlu menulis tool secara manual?

Untuk beberapa kasus, ya: tool komposit yang menggabungkan beberapa panggilan dan tool yang tidak membungkus HTTP. Namun, wrapper satu-endpoint yang rutin seharusnya tidak lagi ditulis manual.

Bagaimana mencegah agen memanggil endpoint tulis saat pengujian?

Hasilkan set tool read-only dengan memfilter HTTP method, lalu arahkan operasi tulis ke mock server. Lihat mengapa agen harus menggunakan mock, bukan produksi.