Seri Qoder CN:Definisikan Agent

Konsep utama

Anda dapat menganggap Agent sebagai "deskripsi pekerjaan":

Agent itu sendiri tidak menjalankan tugas; Agent hanyalah sebuah konfigurasi. Eksekusi tugas ditangani oleh Session yang terikat pada Agent tersebut.

Referensi parameter

Model

Field model menentukan model yang digunakan oleh Agent.

Tools

Field tools adalah array objek tool. Saat ini, hanya toolset agent_toolset_20260401 yang didukung. Anda dapat mengaktifkan tool atomik dalam toolset ini dengan mencantumkannya dalam array enabled_tools:

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

Nilai yang tersedia untuk enabled_tools (nilai bersifat case-sensitive dan harus dalam PascalCase):

Untuk konfigurasi tool lebih lanjut, lihat Agent Tool Configuration.

Manage agents

Untuk rangkaian lengkap API CRUD, lihat API Reference / Agents. Contoh berikut mencakup alur kerja umum.

Create

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "auto",
    "instructions": "You are a code review expert. Review the code line by line and output issues and improvement suggestions in Markdown.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "metadata": {
      "team": "backend",
      "purpose": "code-review"
    }
  }' | jq .

Permintaan yang berhasil mengembalikan 201 Created. version dimulai dari 1.

Query

# Get a single Agent
curl -s https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

# List Agents with pagination
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=20" \
  -H "Authorization: Bearer $QODER_PAT"

Update

Saat memperbarui Agent, Anda harus menyertakan version saat ini. Untuk informasi selengkapnya, lihat manajemen versi di bawah.

curl -s -X PUT https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "auto",
    "instructions": "You are a senior code review expert, focusing on security vulnerabilities and performance issues.",
    "version": 1
  }' | jq .

Permintaan yang berhasil mengembalikan 200 OK, dan version secara otomatis bertambah 1.

Delete

curl -s -X DELETE https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

Menghapus Agent tidak menghentikan Session aktif yang terikat padanya. Session membuat Snapshot konfigurasi Agent saat dibuat.

Manajemen versi

API Agent menggunakan optimistic concurrency control (OCC):

• version dimulai dari 1 saat pembuatan.

• Setelah setiap pembaruan berhasil, version secara otomatis bertambah 1.

• Permintaan pembaruan harus menyertakan version saat ini. Dua skenario kegagalan:

  • Field version tidak ada — mengembalikan 400 invalid_request_error ("Field 'version' is required.")

  • version disediakan tetapi tidak sesuai dengan versi di sisi server — mengembalikan 409 conflict_error

Mekanisme ini mencegah modifikasi konkuren saling menimpa.

Menangani konflik 409

Jika permintaan Anda gagal karena versi sudah kedaluwarsa, Anda akan menerima error berikut:

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 2, got 1."
  }
}

Untuk menyelesaikan konflik:

1. GET Agent terbaru untuk mendapatkan version saat ini

2. Terapkan kembali perubahan yang Anda inginkan pada data objek terbaru.

3. Gunakan version baru untuk melakukan PUT lainnya.

Praktik terbaik

1. Konvensi penamaan — Gunakan format tim-tujuan, seperti backend-code-review atau frontend-test-gen.

2. Penyempurnaan prompt — Tentukan peran, format output, dan batasan dalam field system.

3. Terapkan prinsip hak istimewa minimal: Untuk meminimalkan risiko, berikan hanya tools yang esensial untuk tugas tersebut.

4. Gunakan metadata secara efektif: Gunakan pasangan kunci-nilai untuk mengkategorikan Agent, yang menyederhanakan penyaringan dan audit.

5. Penguncian versi di produksi — Saat membuat Session, gunakan format {"id": ..., "version": ...} untuk mengunci versi Agent. Ini mencegah versi baru memengaruhi layanan online Anda.

FAQ

Q: Apakah memperbarui Agent memengaruhi Session yang sedang berjalan?Tidak. Session terikat pada versi tertentu dari Agent saat dibuat.Q: Dapatkah array tools kosong?
Ya. Agent tanpa tools hanya dapat melakukan percakapan berbasis teks dan tidak dapat menjalankan aksi.Q: Apakah ada batas panjang untuk field name?Kami menyarankan agar panjangnya di bawah 64 karakter dan menggunakan huruf kecil, angka, serta tanda hubung.Q: Bagaimana cara melakukan rollback ke versi Agent yang lebih lama?
Rollback otomatis tidak didukung. Kami menyarankan menyimpan konfigurasi Agent sebelum memperbaruinya. Untuk mengembalikan, Anda dapat secara manual melakukan PUT konfigurasi lama, pastikan menggunakan nomor version terbaru.