Temu Duga Umum: Bagaimanakah Anda Akan Mereka Bentuk API HTTP yang Boleh Digunakan oleh Ejen AI Secara Boleh Harap?

Gesaan dan skop

Tukarkan API pengurusan projek yang direka bentuk untuk pembangun manusia kepada API yang boleh dipanggil oleh ejen AI secara boleh harap. Terangkan penerangan operasi, input, output, penomboran halaman, ralat, pengesahan penulisan, had kadar dan keselamatan. Gesaan ini merujuk kepada Draf Internet (Internet-Draft) IETF Jun 2026 "Agent-Friendly HTTP API Profile". Dokumen ini bersifat Maklumat (Informational) dan masih dalam proses pembangunan; ia tidak mentakrifkan protokol, identiti atau mekanisme pengesahan kebenaran (authorization) yang baharu.

Perkara yang diuji oleh penemu duga

• Memperlakukan penerangan yang boleh dibaca mesin sebagai kontrak dan bukannya dokumentasi selepas siap.
• Mengurangkan pilihan yang salah dengan nama yang stabil, skema yang ketat, respons yang terhad dan penomboran halaman kursor.
• Menjadikan ralat, percubaan semula, keidempotenan, pratonton dan buat asal (undo) sebagai isyarat yang boleh diambil tindakan.
• Memisahkan kebolehgunaan API daripada identiti ejen, pengesahan kebenaran dan keselamatan suntikan gesaan (prompt injection).

Soalan untuk dijelaskan sebelum menjawab

1. Adakah ejen akan menemui API melalui OpenAPI, lapisan alat MCP atau katalog tersuai?
2. Operasi manakah yang baca sahaja dan manakah yang membuat pemberitahuan, mengenakan caj atau mengubah keadaan (state)?
3. Adakah respons memerlukan pemilihan medan, penomboran halaman kursor dan saiz halaman maksimum?
4. Bolehkah klien menyediakan kunci keidempotenan dan mendapatkan semula hasil asal selepas tamat masa (timeout)?
5. Medan dikembalikan manakah yang mengandungi kandungan pengguna yang tidak dipercayai yang mesti diasingkan daripada medan kawalan?

Rangka kerja jawapan 30 saat

Anggap penerangan API dan tingkah laku HTTP sebagai satu kontrak input. Pastikan nama operasi stabil dan mendedahkan niat, tolak sifat input yang tidak diketahui, kembalikan respons kecil dengan pemilihan medan dan nomborkan halaman koleksi menggunakan kursor. Ralat membawa kod yang stabil, kebolehan mencuba semula dan tindakan seterusnya; penulisan menyokong kunci keidempotenan, pratonton, pengesahan dan buat asal. Pelayan menguatkuasakan had, pengesahan kebenaran dan audit; ia tidak boleh mewakilkan keputusan keselamatan kepada ejen. Dokumen IETF ialah senarai semak draf, bukan protokol pengesahan identiti (authentication).

Perbincangan mendalam langkah demi langkah

1. Asingkan lapisan API dan alat

OpenAPI dan penerangan boleh dibaca mesin yang serupa tergolong dalam lapisan API; MCP dan protokol panggilan alat lain tergolong dalam lapisan alat. Bina kontrak API yang stabil dan boleh disahkan terlebih dahulu supaya pelbagai lapisan alat boleh menggunakannya semula. Jangan jadikan gesaan atau nama alat satu ejen sebagai satu-satunya sempadan keselamatan.

2. Reka bentuk operasi yang boleh dibezakan

ID operasi mestilah stabil, pendek dan mendedahkan niat. Pada permukaan alat yang besar, nama yang mendahulukan entiti seperti task_create dan task_update boleh jadi lebih mudah dibezakan berbanding awalan sepunya create_. Penerangan harus menyatakan masa untuk menggunakan dan masa untuk tidak menggunakan operasi, kesan sampingannya, dan operasi carian yang mana untuk mendapatkan pengecam yang hilang.

3. Kekang input dan output

Skema input harus mentakrifkan medan yang diperlukan, enum tertutup, had panjang dan tatasusunan, serta menolak sifat yang tidak diketahui. Respons hendaklah kecil secara lalai dan menyokong pemilihan medan atau tahap keperincian. Jangan bergantung pada klien untuk meminta data yang lebih sedikit; pelayan tetap mengawal kos dan penggunaan konteks.

{
  "name": "task_create",
  "description": "Create a task; notifies the assignee.",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["project_id", "title", "idempotency_key"],
    "properties": {
      "project_id": {"type": "string"},
      "title": {"type": "string", "maxLength": 200},
      "priority": {"type": "string", "enum": ["low", "medium", "high"]},
      "idempotency_key": {"type": "string", "maxLength": 128}
    }
  }
}

4. Jadikan operasi baca dan penomboran halaman boleh dipulihkan

Kembalikan kursor legap (opaque cursor) dan bukannya meminta ejen mengira ofset. Ikat kursor pada pertanyaan, tamatkan tempohnya, dan kembalikan next_cursor dengan tindakan seterusnya yang sedia untuk digunakan. Susunan yang stabil, permintaan bersyarat dan pemilihan medan mengurangkan pemindahan pendua dan penggunaan konteks.

5. Jadikan ralat boleh diambil tindakan oleh mesin

Kembalikan kod yang stabil, butiran berstruktur dan bendera retryable; sertakan pautan operasi seterusnya apabila berguna. Respons 429 harus menyediakan kelewatan percubaan semula, ralat pengesahan harus mengenal pasti medan, dan tugasan yang berjalan lama harus menyediakan URL status. Bahasa semula jadi membantu manusia, tetapi ia tidak boleh menjadi satu-satunya semantik kawalan.

{
  "type": "https://api.example/problems/rate-limit",
  "title": "Too many requests",
  "status": 429,
  "code": "RATE_LIMITED",
  "retryable": true,
  "retry_after_seconds": 30
}

6. Lindungi penulisan

Penulisan menerima kunci keidempotenan dengan tetingkap dan skop yang didokumentasikan. Percubaan semula selepas tamat masa mengembalikan hasil asal dan bukannya mencipta pendua. Penulisan berisiko tinggi menyediakan percubaan larian (dry-run), pengesahan atau buat asal serta menyatakan pemberitahuan, caj dan kesan sampingan yang lain. Pelayan masih melakukan pemeriksaan pengesahan kebenaran, kuota dan audit.

7. Tetapkan sempadan keselamatan dan kebolehcerapan (observability)

Tandakan teks pengguna atau pihak ketiga sebagai data dan pastikan ia berasingan daripada medan kawalan yang dipercayai untuk mengurangkan suntikan gesaan tidak langsung. Hadkan saiz respons, saiz halaman, pengundian (polling) dan ruang nama alat; wajibkan keistimewaan paling sedikit (least privilege) dan pengesahan manusia untuk operasi berisiko tinggi. Rekodkan ID korelasi, pelaku, perwakilan, hasil dan percubaan semula tanpa mengelog kandungan sensitif.

8. Sahkan dan lelar (iterate)

Gunakan set tugas tetap untuk mengukur ketepatan pemilihan operasi, ralat parameter, penulisan pendua, ralat yang boleh dipulihkan, purata saiz respons, penggunaan konteks, kejayaan selepas 429 dan liputan pengesahan. Versikan penerangan, skema, ralat dan respons. Jadikan cadangan draf sebagai senarai semak dalaman dan bukannya menjanjikan keserasian piawaian.

Contoh jawapan berkualiti tinggi

Saya akan memperlakukan penerangan API sebagai kontrak utama dan mereka bentuk tingkah laku HTTP di sekelilingnya. ID operasi adalah stabil dan menyatakan entiti serta niat; penerangan menyatakan syarat penggunaan, kes yang dilarang dan kesan sampingan. Skema input menolak medan yang tidak diketahui dan mengekang enum, panjang, tatasusunan dan halaman. Koleksi menggunakan kursor legap dan susunan yang stabil, manakala respons adalah kecil dan medannya boleh dipilih.

Ralat membawa kod yang stabil, kebolehan mencuba semula, retry_after dan tindakan seterusnya. Penulisan memerlukan kunci keidempotenan dan mengembalikan hasil asal selepas tamat masa; penulisan berisiko tinggi menyokong pratonton, pengesahan atau buat asal. Pelayan menguatkuasakan pengesahan kebenaran, had kadar, saiz dan audit, dan bukannya mempercayai ejen untuk mematuhi arahan prosa. Kandungan pengguna diasingkan daripada medan kawalan, dan penyedia alat menggunakan ruang nama berasingan dengan ID korelasi.

Akhir sekali, nilaikan set tugas untuk pilihan yang salah, ralat parameter, penulisan pendua, saiz respons, kejayaan percubaan semula dan liputan pengesahan. Dokumen IETF ialah draf Maklumat Jun 2026 tanpa protokol pengesahan identiti atau pengesahan kebenaran, jadi saya akan menggunakannya sebagai senarai semak reka bentuk dengan pemversian dalaman dan keupayaan pengunduran (rollback).

Kesilapan biasa

• Memanggil profil tersebut sebagai protokol identiti atau pengesahan kebenaran yang baharu.
• Mengoptimumkan gesaan sambil membiarkan OpenAPI, skema, ralat dan kesan sampingan kurang ditentukan.
• Meminta ejen mengehadkan saiz respons atau mengira ofset penomboran halaman.
• Meniadakan keidempotenan, pratonton, pengesahan atau buat asal daripada penulisan yang boleh dicuba semula.
• Memasukkan teks pengguna yang dikembalikan ke dalam medan arahan yang dipercayai dan mengabaikan suntikan gesaan tidak langsung.

Soalan susulan dan jawapan

Mengapa tidak menulis dokumentasi yang lebih terperinci sahaja?

Ejen memilih daripada penerangan dan respons yang boleh dibaca mesin pada setiap langkah. Medan yang stabil, enum, bendera ralat dan kursor lebih mudah untuk dilaksanakan berbanding nasihat yang bertaburan dalam prosa; dokumentasi tetap berguna untuk manusia dan penghijrahan.

Lapisan manakah yang memiliki keselamatan, API atau MCP?

API mesti menguatkuasakan pengesahan identiti, pengesahan kebenaran, had kadar dan audit. Lapisan alat boleh mengehadkan pendedahan, ruang nama dan pengesahan, tetapi ia tidak boleh menggantikan kawalan akses bahagian pelayan.

Bagaimanakah anda memutuskan penulisan yang manakah memerlukan pengesahan?

Kelaskan mengikut ketidakterbalikan (irreversibility), amaun, pendedahan data, pemberitahuan luaran dan skop keistimewaan. Operasi berisiko tinggi mendedahkan percubaan larian atau token pengesahan; kemas kini idempoten berisiko rendah boleh dijalankan secara automatik, tetapi pelayan sentiasa mengesahkannya.

Bagaimana jika penerangan dicemari oleh kandungan pihak ketiga?

Letakkan teks pihak ketiga dalam medan data yang jelas dan halang ia daripada mengubah takrifan atau kebenaran alat. Asingkan ruang nama penyedia, sematkan cap jari, audit versi dan semak semula pengesahan kebenaran pada pelayan.