agentHints: Mengajarkan CLI untuk Berkomunikasi dengan Agen

Ini adalah seri 10 bagian yang menceritakan bagaimana Apidog mengembangkan Apidog CLI, sebuah alat baris perintah untuk pengujian API dan manajemen siklus hidup API. Baca secara berurutan atau langsung ke postingan mana pun yang menarik minat Anda:

Output CLI tradisional ditujukan untuk manusia. Agen membutuhkan hasil terstruktur, alasan kegagalan, dan saran langkah selanjutnya. agentHints mengubah pengalaman produk menjadi panduan yang dapat dibaca mesin.

Kesenjangan Output CLI

Output CLI tradisional dirancang untuk manusia.

Ini berfungsi untuk manusia. Manusia dapat:

• Menginterpretasikan pesan yang samar
• Memutuskan apa yang harus dilakukan selanjutnya
• Mengingat konteks dari perintah sebelumnya
• Menerapkan pengetahuan domain untuk melanjutkan

Tetapi Agen bekerja secara berbeda.

Apa yang Sebenarnya Dibutuhkan Agen

Agen tidak hanya membaca hasil. Mereka perlu menghubungkan hasil dengan rantai tugas berikutnya.

Manusia melihat "Sumber daya berhasil dibuat" dan tahu: "Saya mungkin harus memeriksa apa yang dibuat, lalu mungkin menjalankan beberapa pengujian."

Agen melihat "Sumber daya berhasil dibuat" dan... tidak tahu apa yang harus dilakukan selanjutnya.

agentHints: Solusinya

Apidog CLI menambahkan agentHints ke outputnya.

Berikut adalah tampilan respons tipikal:

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Health Check Test Case"
  },
  "agentHints": {
    "summary": "Kasus uji berhasil dibuat.",
    "nextSteps": [
      "Baca kembali kasus uji yang dibuat untuk mengkonfirmasi struktur.",
      "Tambahkan pernyataan jika kasus uji memerlukan validasi respons.",
      "Tambahkan kasus uji ke skenario uji untuk pengujian integrasi.",
      "Jalankan pengujian terkait setelah menambahkan ke skenario."
    ]
  }
}

Tiga komponen:

Masalah Inersia Eksekusi

Berikut masalah nyata yang kami amati:

Setelah berhasil membuat sumber daya, model seringkali langsung melanjutkan untuk menghasilkan penulisan berikutnya.

Contoh:

Agen: Membuat kasus uji
CLI: Mengembalikan keberhasilan
Agen: Segera membuat skenario uji (tanpa membaca kembali)
Agen: Segera menjalankan pengujian
Hasil: Skenario memiliki struktur yang salah, pengujian gagal

Dalam proses bisnis yang kompleks, eksekusi berkelanjutan mekanis tidaklah tepat.

Pendekatan yang paling benar seringkali adalah:

1. Buat sumber daya
2. Baca kembali terlebih dahulu
3. Konfirmasi struktur
4. Lalu lanjutkan

Mengapa Membaca Kembali Penting

Melewatkan pembacaan kembali menyebabkan masalah nyata:

Jika struktur yang sebenarnya tidak dibaca kembali, Agen dengan mudah terus menulis berdasarkan tebakannya sendiri—bukan pada data aktual.

agentHints sebagai Navigator

agentHints mengubah pengalaman produk menjadi saran langkah selanjutnya yang dapat dibaca mesin.

Ini muncul tepat di tempat Agen perlu membuat keputusan.

Contoh setelah membuat kasus uji:

{
  "agentHints": {
    "nextSteps": [
      "Baca kembali kasus uji yang dibuat dengan flag --with-case-detail.",
      "Validasi pembaruan apa pun dengan cli-schema sebelum menulis.",
      "Jalankan pengujian setelah menyelesaikan skenario uji."
    ]
  }
}

Agen:

1. Membaca output
2. Mem-parsing agentHints
3. Mengikuti nextSteps[0]: membaca kembali kasus uji
4. Mengkonfirmasi struktur aktual
5. Lalu melanjutkan dengan informasi yang akurat

Transformasi Peran CLI

Ini mengubah arti CLI dalam alur kerja Agen.

CLI menjadi navigator status ringan.

Pohon Alur Kerja Bawaan

Apidog CLI memiliki ribuan alur kerja berbentuk pohon bawaan.

Ini bukan hanya saran yang di-hardcode. Mereka adalah:

Contoh setelah pembaruan skenario uji yang berhasil:

{
  "agentHints": {
    "summary": "Skenario uji berhasil diperbarui.",
    "nextSteps": [
      "Jalankan skenario uji untuk memverifikasi perubahan.",
      "Periksa laporan uji untuk setiap kegagalan.",
      "Jika terjadi kegagalan, baca kembali langkah-langkah skenario untuk debugging."
    ]
  }
}

Contoh setelah kegagalan validasi:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'comparator' has invalid value",
    "details": [...]
  },
  "agentHints": {
    "summary": "Validasi gagal. Perbaiki kesalahan dan validasi ulang.",
    "nextSteps": [
      "Tinjau detail kesalahan pada output.",
      "Sesuaikan file JSON berdasarkan saran kesalahan.",
      "Jalankan ulang validasi cli-schema sebelum menulis."
    ]
  }
}

Bahkan kegagalan pun menjadi dapat dinavigasi.

Lingkaran yang Lebih Aman dengan agentHints

Mari kita lacak alur kerja lengkap dengan agentHints:

Langkah 1: Agen membuat kasus uji
        ↓
Output CLI: success + agentHints
        ↓
agentHints.nextSteps[0]: "Baca kembali kasus uji yang dibuat"
        ↓
Langkah 2: Agen membaca kembali (dengan struktur aktual)
        ↓
Output CLI: struktur kasus uji + agentHints
        ↓
agentHints.nextSteps[0]: "Tambahkan pernyataan jika diperlukan"
        ↓
Langkah 3: Agen menambahkan pernyataan (berdasarkan struktur aktual)
        ↓
Output CLI: success + agentHints
        ↓
agentHints.nextSteps[0]: "Jalankan pengujian"
        ↓
Langkah 4: Agen menjalankan pengujian
        ↓
Output CLI: laporan uji

Setiap langkah dipandu. Tidak ada lompatan buta. Tidak ada asumsi.

Perbandingan: Dengan dan Tanpa agentHints

Apa Selanjutnya

Sekarang setelah CLI dapat memandu Agen melalui langkah-langkah selanjutnya, pertanyaan yang tersisa adalah:

Bagaimana Agen tahu alur kerja mana yang harus diikuti sejak awal?

Pada Bagian 5, SKILL: Mengirimkan Pengalaman Operasional sebagai Kode, kita akan menjelajahi bagaimana SKILL mengemas pengetahuan alur kerja—kapan menggunakan perintah, urutan apa yang harus diikuti, dan bidang apa yang tidak boleh ditebak.

Poin-poin Penting

• Output CLI tradisional berorientasi pada manusia; Agen membutuhkan panduan terstruktur
• agentHints menyediakan ringkasan + saran langkah selanjutnya dalam output JSON
• Inersia eksekusi menyebabkan Agen melewatkan pembacaan kembali; agentHints mencegah hal ini
• CLI bertransformasi dari pelaksana menjadi navigator
• Pohon alur kerja bawaan membuat setiap langkah dapat dinavigasi
• Bahkan kegagalan pun menjadi dapat ditindaklanjuti dengan agentHints

Unduh Apidog untuk mendesain, membuat mock, menguji, dan mendokumentasikan API dalam satu ruang kerja. Pelajari lebih lanjut tentang Apidog CLI untuk pengujian API baris perintah, otomatisasi CI, dan alur kerja Agen AI.