Seri Qoder CN:Mulai sesi

Siklus hidup sesi

1. Create → idle

   Sesi baru memasuki status idle, menunggu input.

2. idle → processing

   Setelah Anda mengirim event user.message, status berubah menjadi processing.

3. processing → idle

   Ketika putaran saat ini selesai, Sesi kembali ke status idle, siap untuk putaran berikutnya.

4. processing → canceling → idle

   Ketika Anda membatalkan Sesi yang sedang berjalan, statusnya berubah menjadi canceling sebelum kembali ke idle. Sesi tetap tersedia untuk digunakan.

5. archived (terminal state)

   Status archived merupakan status terminal; sesi yang diarsipkan tidak dapat dipulihkan.

Sesi merupakan mesin keadaan dengan status inti berikut:

Bidang

Buat sesi

Saat membuat Sesi, Anda harus menentukan agent dan environment_id.

Gunakan ID Agent (string)

Metode ini mengikat Sesi ke versi terbaru Agent.

# Buat Sesi menggunakan ID Agent
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
    "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428"
  }' | jq .

Gunakan objek Agent (tentukan versi)

Metode ini mengikat Sesi ke versi tertentu Agent untuk memastikan perilaku yang konsisten.

# Buat Sesi dengan menentukan versi Agent
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
      "version": 2
    },
    "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428"
  }' | jq .

Permintaan yang berhasil mengembalikan respons 201 Created.

{
  "id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "agent": {
    "created_at": "2026-05-18T10:00:00Z",
    "default_environment": "",
    "description": "",
    "id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
    "instructions": "You are a code review expert.",
    "mcp_servers": [],
    "model": "ultimate",
    "name": "code-reviewer",
    "system": "You are a code review expert.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "type": "agent",
    "updated_at": "2026-05-18T10:00:00Z",
    "version": 2
  },
  "agent_id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
  "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "status": "idle",
  "title": "",
  "turn_status": "idle",
  "memory_store_ids": [],
  "resources": [],
  "vault_ids": [],
  "type": "session",
  "created_at": "2026-05-18T12:00:00Z",
  "updated_at": "2026-05-18T12:00:00Z"
}

Untuk lingkungan produksi, kami merekomendasikan menggunakan metode kedua (menentukan versi) untuk mencegah perubahan perilaku tak terduga akibat pembaruan Agent.

Format bidang agent

Transisi status

Format badan permintaan event

Badan permintaan untuk POST /sessions/{id}/events harus berupa objek yang berisi array events. Setiap event dalam array mencakup bidang content, yang merupakan array blok konten.

idle → processing

Saat Anda mengirim event user.message ke Sesi, statusnya berubah dari idle menjadi processing.

# Kirim pesan untuk memicu pemrosesan
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "user.message",
      "content": [{"type": "text", "text": "Analyze the code complexity of all Python files in the current directory."}]
    }]
  }' | jq .

processing → idle

Setelah Agent selesai memproses, Sesi secara otomatis kembali ke status idle. Anda akan menerima event session.status_idle melalui aliran event.

Batalkan sesi

Anda dapat menghentikan Sesi yang sedang berjalan.

# Batalkan Sesi
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/cancel" \
  -H "Authorization: Bearer $QODER_PAT"

Ambil sesi

# Ambil satu Sesi
curl -s "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522" \
  -H "Authorization: Bearer $QODER_PAT"

# Daftar semua Sesi (dengan pagination)
curl -s "https://api.qoder.com.cn/api/v1/cloud/sessions?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

Berikut contoh respons terpaginasi:

{
  "data": [
    {
      "id": "sess_019e5ce0bf9074b69c3481e93771a522",
      "type": "session",
      "agent_id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
      "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
      "status": "idle",
      "turn_status": "idle",
      "title": "",
      "memory_store_ids": [],
      "vault_ids": [],
      "resources": [],
      "created_at": "2026-05-18T12:00:00Z",
      "updated_at": "2026-05-18T12:30:00Z"
    }
  ],
  "first_id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "last_id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "has_more": false
}

Penggunaan token

Penggunaan token untuk setiap putaran tidak dikembalikan melalui REST API. Untuk melihat penggunaannya, dengarkan event SSE session.status_idle di akhir setiap putaran. Bidang usage-nya berisi jumlah token untuk putaran tersebut.

Berikut contoh muatan dari event SSE:

{
  "type": "session.status_idle",
  "usage": {
    "input_tokens": 3840,
    "output_tokens": 2156,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

Pengikatan versi Sesi dan Agent

Saat Sesi dibuat, konfigurasi Agent diambil sebagai snapshot.

• Gunakan format string "agent": "agent_xxx" untuk mengikat ke versi terbaru Agent pada saat pembuatan.

• Gunakan format objek "agent": {"id": "agent_xxx", "version": N} untuk mengikat ke versi tertentu.

• Setelah Sesi dibuat, memodifikasi Agent tidak memengaruhi Sesi tersebut.

• Untuk menggunakan versi baru Agent, Anda harus membuat Sesi baru.

Percakapan multi-putaran

Sesi mendukung percakapan multi-putaran. Setelah mengirim pesan, tunggu event session.status_idle, lalu Anda dapat mengirim pesan berikutnya.

#!/bin/bash
# Contoh percakapan multi-putaran
BASE_URL="https://api.qoder.com.cn/api/v1/cloud"
SESSION_ID="sess_019e5ce0bf9074b69c3481e93771a522"
HEADERS=(
  -H "Authorization: Bearer $QODER_PAT"
)

# Putaran 1: Buat permintaan awal
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "user.message", "content": [{"type": "text", "text": "Create a Python Flask project scaffold."}]}]}'

# Tunggu hingga pemrosesan selesai... (poll atau dengarkan SSE)
sleep 30

# Putaran 2: Tambahkan persyaratan lanjutan
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "user.message", "content": [{"type": "text", "text": "Add unit tests and a CI configuration to the project."}]}]}'

Kode kesalahan terkait status

Berikut adalah kesalahan umum terkait status yang dapat terjadi saat Anda mengirim event ke Sesi.

Berikut contoh respons kesalahan 409:

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Session is currently processing a turn. Cancel the current turn or wait for completion."
  }
}

Praktik terbaik

1. Penguncian versi — Di lingkungan produksi, selalu buat Sesi dengan menggunakan format {"id": ..., "version": ...}.

2. Pembatalan tepat waktu — Batalkan Sesi yang tidak diperlukan untuk melepaskan sumber daya.

3. Monitor penggunaan — Periksa secara berkala bidang usage untuk menghindari biaya tak terduga.

4. Tandai dengan metadata — Gunakan bidang metadata untuk mencatat konteks bisnis, seperti ID tugas atau sumber pemicu.

FAQ

T: Apakah Sesi memiliki mekanisme timeout?

J: Sesi dalam status idle dipertahankan selama periode tertentu. Sesi yang tidak aktif dalam jangka waktu lama dapat diarsipkan secara otomatis oleh sistem. Kami merekomendasikan membuat Sesi sesuai kebutuhan dan membatalkannya setelah tugas selesai.

T: Apa yang terjadi jika saya mengirim pesan ke Sesi yang sedang dalam status processing?

J: API mengembalikan HTTP 409 conflict_error dengan pesan Session is currently processing a turn. Cancel the current turn or wait for completion. Anda harus membatalkan putaran saat ini atau menunggu Sesi kembali ke status idle sebelum mengirim pesan baru.

Q: Berapa jumlah maksimum giliran yang didukung oleh Sesi?

J: Tidak ada batas ketat jumlah putaran; namun, ukuran jendela konteks model memberikan batas praktis. Seiring percakapan bertambah panjang, konten awal mungkin dipotong.

T: Bagaimana cara mendapatkan riwayat percakapan lengkap Sesi?

J: Panggil operasi GET /sessions/{id}/events untuk mengambil semua event Sesi, termasuk pesan pengguna dan respons Agent.

T: Apakah Sesi yang dibatalkan dapat digunakan kembali?

J: Ya. Setelah Anda membatalkan Sesi, statusnya secara otomatis berubah dari canceling kembali ke idle, dan Sesi tetap tersedia. Anda dapat mengirim user.message berikutnya untuk melanjutkan percakapan. Hanya status archived yang merupakan status terminal. Sesi yang diarsipkan tidak dapat dipulihkan.