Seri Qoder CN:Agent Tools

Apa yang Dilakukan Tools

Saat mengeksekusi suatu task, Agent menentukan kemampuan mana yang dapat dipanggil berdasarkan konfigurasi tools. Semua tools dikonfigurasi melalui single object { "type": "agent_toolset_20260401", "enabled_tools": [...] }, dengan secara selektif mengaktifkan tools atomik dalam array enabled_tools.

Jika enabled_tools berupa daftar izin (allowlist) yang tidak kosong, tools di luar daftar tersebut tidak terlihat oleh model dan tidak akan dipanggil. Jika enabled_tools dihilangkan atau berupa array kosong, semua tools bawaan diekspos ke model. Namun, jika seluruh bidang tools dihilangkan atau diatur ke [], model sama sekali tidak menerima skema tool apa pun (lihat FAQ di bawah).

Tools yang Tersedia

Nama Tool (nilai enabled_tools)	Tujuan	Kasus penggunaan khas
Bash	Eksekusi perintah shell	Menginstal dependensi, menjalankan skrip, memanggil API dengan curl
Read	Membaca file	Melihat file yang dimount, membaca kode
Write	Penulisan file (membuat/menimpa)	Menghasilkan laporan, menghasilkan output
Edit	Edit file sebagian	Mengubah konfigurasi, mengedit kode
Glob	Daftar file berdasarkan pola Glob	Menemukan file kode
Grep	Pencarian konten file	Menemukan string
WebFetch	HTTP GET satu halaman	Mengambil dokumentasi/halaman
WebSearch	Web search	Mencari informasi
DeliverArtifacts	Alat yang dicadangkan sistem. Terdapat dalam set "all on" (saat enabled_tools tidak disertakan atau kosong).	Tidak direkomendasikan untuk mendeklarasikan secara eksplisit di enabled_tools.

Catatan:

• Nama tool ditulis dengan huruf kapital (Bash, bukan bash); nama tersebut juga muncul dalam bentuk kapital di aliran acara.
• Menghilangkan enabled_tools atau memberikan array kosong [] akan mengaktifkan semua tool bawaan (termasuk DeliverArtifacts yang tercantum di atas). Jika Anda ingin Agent tidak memiliki tool sama sekali, hilangkan seluruh bidang tools atau atur nilainya menjadi [].
• Setiap nama tool dalam enabled_tools divalidasi — menuliskan nama yang tidak dikenal (misalnya "Foo") akan mengembalikan respons 400: "unknown tool name 'Foo'"
• Skema lama berbasis objek per-tool (seperti {"type": "bash_20250124"}) tidak lagi didukung.

Format Saat Ini: Objek Tunggal

Konfigurasi tool berupa objek tunggal yang mengatur tool tertentu melalui array enabled_tools:

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}

Diatur saat membuat Agent:

curl -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-agent",
    "model": "ultimate",
    "instructions": "You are a development assistant",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }'

Contoh Konfigurasi

Minimal (hanya CLI)

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash"]
    }
  ]
}

Stack Pengembangan Lengkap

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}

Buat Versi Baru (PUT Penggantian Penuh)

Gunakan PUT untuk membuat versi baru Agent dengan konfigurasi tool yang diperbarui:

curl -X PUT https://api.qoder.com.cn/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit"]
      }
    ]
  }'

PUT adalah penggantian penuh (bukan Patch) — bidang yang tidak disertakan akan dihapus. Anda harus menyertakan bidang version untuk Kontrol konkurensi optimistis:

• Jika versi yang diberikan cocok dengan versi saat ini: respons 200, dan versi bertambah menjadi 1.
• Jika versi yang diberikan kedaluwarsa: respons 409 { error: { type: "conflict_error", message: "Version conflict. Expected version N, got M." }}

Sesi yang sudah ada tidak terpengaruh; sesi baru menggunakan konfigurasi yang diperbarui.

Periksa Konfigurasi Tool Saat Ini

curl https://api.qoder.com.cn/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_PAT" | jq '.tools'

Contoh output:

[
  {
    "type": "agent_toolset_20260401",
    "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
  }
]

FAQ

T: Bagaimana jika saya tidak mengonfigurasi tools? J: Agent tidak memiliki alat yang tersedia dan hanya dapat melakukan percakapan teks biasa. Untuk memberikan Agent kemampuan alat, teruskan setidaknya [{"type":"agent_toolset_20260401"}] (yang mengaktifkan semua alat bawaan).

T: Dapatkah saya mengganti tool di level Sesi? J: Saat ini belum bisa. Konfigurasi tool terikat pada Agent, dan semua Sesi untuk Agent tersebut berbagi kumpulan tool yang sama.

T: Apakah urutan tools berpengaruh? J: Tidak. Agent menentukan tool mana yang akan dipanggil berdasarkan konteks tugas.

T: Apakah sufiks versi akan berubah seiring berjalannya waktu? J: Ya. Seiring dirilisnya versi tool baru, sufiks baru bertanggal akan diperkenalkan. Pantau changelog dan adopsi sufiks terbaru.