Struktur data Sesi dan Event - Seri Qoder CN - Alibaba Cloud Documentation Center

Referensi untuk objek Session dan Event yang dikembalikan oleh Forward Session API.

Objek Session

Endpoint Create, Get, List, Update, dan Archive Session semuanya mengembalikan objek ini.

{
  "id": "sess_xxx",
  "type": "session",
  "identity_id": "idn_xxx",
  "template": {
    "id": "tmpl_support",
    "type": "template",
    "name": "Customer support assistant",
    "model": "ultimate",
    "version": 3
  },
  "source_type": "api",
  "status": "idle",
  "title": "Customer support conversation",
  "incremental_streaming_enabled": true,
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "stats": {
    "active_seconds": 30,
    "duration_seconds": 3600
  },
  "usage": {
    "credits": 12.5
  },
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T11:00:00Z"
}

Field	Type	Selalu dikembalikan	Deskripsi
`id`	string	Ya	ID Session dengan awalan `sess_`.
`type`	string	Ya	Selalu `"session"`.
`identity_id`	string	Ya	ID Forward Identity yang mengidentifikasi end user pemilik Session ini.
`template`	object	Ya	Rangkuman Forward Template. Lihat tabel rangkuman Template di bawah.
`source_type`	string	Ya	Sumber Session: `api`, `im`, atau `schedule`.
`status`	string	Ya	Status waktu proses Session: `idle`, `running`, `rescheduling`, `canceling`, atau `terminated`. Status arsip dinyatakan melalui `archived_at`.
`title`	string	Ya	Judul Session.
`incremental_streaming_enabled`	boolean	Ya	Apakah event streaming inkremental diaktifkan untuk Session ini. Nilai default-nya adalah `false` jika tidak ditentukan saat pembuatan. Tidak dapat diubah setelah Session dibuat.
`metadata`	object	Tidak	Metadata bisnis yang ditentukan oleh pemanggil.
`config`	object	Tidak	Konfigurasi Session. Diabaikan jika tidak ada konfigurasi yang diberikan.
`config.environment_variables`	object	Tidak	Variabel lingkungan tingkat Session dalam bentuk pasangan kunci-nilai.
`stats`	object	Tidak	Statistik penggunaan Session. Lihat tabel statistik Session di bawah.
`usage`	object	Tidak	Informasi penggunaan. Dapat diabaikan jika modul penagihan tidak diaktifkan.
`usage.credits`	number	Tidak	Kredit yang dikonsumsi.
`archived_at`	string \| null	Ya	Timestamp arsip. `null` jika Session belum diarsipkan.
`created_at`	string	Ya	Waktu pembuatan dalam format RFC 3339.
`updated_at`	string	Ya	Waktu pembaruan terakhir dalam format RFC 3339.

Rangkuman Template

Field	Type	Selalu dikembalikan	Deskripsi
`id`	string	Ya	ID Forward Template.
`type`	string	Ya	Selalu `"template"`.
`name`	string	Ya	Nama Template.
`model`	string	Ya	Tier model atau identifikasi model yang digunakan oleh Template.
`version`	integer	Ya	Nomor versi Template.

Statistik Session

Field	Type	Selalu dikembalikan	Deskripsi
`active_seconds`	integer	Tidak	Waktu pemrosesan aktif dalam detik. Biasanya bernilai `0` untuk Session baru.
`duration_seconds`	integer	Tidak	Durasi total Session dalam detik. Biasanya bernilai `0` untuk Session baru.

Objek Event

Event yang dikembalikan oleh API berupa objek JSON dengan muatan yang bervariasi tergantung pada type. Setiap event memiliki kumpulan field umum yang sama, ditambah field muatan spesifik tipe.

{
  "id": "evt_xxx",
  "type": "agent.message",
  "session_id": "sess_xxx",
  "content": [
    {
      "type": "text",
      "text": "Here is the analysis result."
    }
  ],
  "processed_at": "2026-06-22T11:00:03Z"
}

Field	Type	Selalu dikembalikan	Deskripsi
`id`	string	Ya	ID Event dengan awalan `evt_`.
`type`	string	Ya	Tipe event.
`session_id`	string	Ya	ID Session tempat event ini berasal.
`processed_at`	string	Tidak	Waktu event diproses, dalam format RFC 3339. Dapat tidak tersedia pada event tertentu yang dihasilkan agen atau event inkremental.

Field muatan yang diizinkan untuk setiap tipe event tercantum di bawah. Field umum id, type, session_id, dan processed_at tidak diulang dalam tabel ini.

Jenis peristiwa	Field yang diizinkan
`user.message`	`content`
`user.interrupt`	Tidak ada
`user.tool_confirmation`	`tool_use_id`, `result`, `deny_message`
`user.tool_result`	`tool_use_id`, `content`, `is_error`
`user.custom_tool_result`	`custom_tool_use_id`, `content`, `is_error`
`user.define_outcome`	`description`, `rubric`, `outcome_id`, `max_iterations`
`system.message`	`content`
`agent.message`	`content`
`agent.thinking`	Tidak ada
`agent.message_start`	`message_id`, `message`
`agent.content_block_start`	`message_id`, `index`, `content_block`
`agent.content_block_delta`	`message_id`, `index`, `delta`
`agent.content_block_stop`	`message_id`, `index`
`agent.message_delta`	`message_id`, `delta`, `usage`
`agent.message_stop`	`message_id`
`agent.tool_use`	`name`, `input`, `evaluated_permission`
`agent.tool_result`	`tool_use_id`, `content`, `is_error`
`agent.custom_tool_use`	`name`, `input`
`agent.mcp_tool_use`	`mcp_server_name`, `name`, `input`, `evaluated_permission`
`agent.mcp_tool_result`	`mcp_tool_use_id`, `content`, `is_error`
`agent.artifact_delivered`	`file_id`, `original_filename`, `size`, `content_type`
`session.status_running`	Tidak ada
`session.status_idle`	`stop_reason`
`session.status_terminated`	Tidak ada
`session.error`	`error`
`session.updated`	`agent`, `metadata`, `title`

Tipe event yang dapat ditulis klien

POST /api/v1/forward/sessions/{session_id}/events hanya menerima tipe event berikut.

Tipe	Field wajib	Deskripsi
`user.message`	`content`	Pesan pengguna. `content` harus berupa array non-kosong dari blok konten dan mendukung tipe blok seperti `text`, `image`, dan `document`.
`user.interrupt`	Tidak ada	Meminta agar giliran saat ini diinterupsi.
`user.tool_confirmation`	`tool_use_id`, `result`	Konfirmasi pemanggilan tool. `result` harus berupa `allow` atau `deny`. Saat menolak, Anda juga dapat mengirimkan `deny_message`.
`user.tool_result`	`tool_use_id`	Mengembalikan hasil tool bawaan. `content` dan `is_error` bersifat opsional.
`user.custom_tool_result`	`custom_tool_use_id`	Mengembalikan hasil tool kustom yang ditentukan klien. `content` dan `is_error` bersifat opsional.
`user.define_outcome`	`description`, `rubric`	Menentukan hasil yang diinginkan beserta rubrik evaluasinya. `max_iterations` bersifat opsional.

system.message merupakan tipe event publik tetapi tidak diterima sebagai event yang dapat ditulis oleh klien Forward.

Tipe event publik

Saat Anda mengambil riwayat event atau berlangganan aliran SSE, Anda mungkin menerima salah satu tipe event publik berikut:

user.message, user.interrupt, user.tool_confirmation, user.tool_result, user.custom_tool_result, user.define_outcome, system.message, agent.message, agent.thinking, agent.message_start, agent.content_block_start, agent.content_block_delta, agent.content_block_stop, agent.message_delta, agent.message_stop, agent.tool_use, agent.tool_result, agent.custom_tool_use, agent.mcp_tool_use, agent.mcp_tool_result, agent.artifact_delivered, session.status_running, session.status_idle, session.status_terminated, session.error, dan session.updated.

Event streaming inkremental

Eksposur event streaming inkremental dikendalikan oleh field incremental_streaming_enabled yang ditetapkan saat pembuatan Session, bukan oleh parameter permintaan pada kueri riwayat atau langganan SSE:

true: Aliran event mengembalikan output asisten parsial sebelum agent.message final. Kueri riwayat mengembalikan event inkremental yang sama.
false atau diabaikan: Mode standar. Hanya event publik lengkap yang dikembalikan; tidak ada event inkremental yang dikirimkan.

Saat streaming inkremental diaktifkan, agent.message final lengkap tetap dikembalikan. Klien dapat menggunakan event inkremental untuk rendering langsung dan mengandalkan agent.message final sebagai sumber kebenaran untuk persistensi dan rekonsiliasi tampilan.

Hanya enam tipe event tingkat atas berikut yang bersifat inkremental:

Jenis Peristiwa	Field utama	Deskripsi
`agent.message_start`	`message_id`, `message`	Menandai awal pesan asisten.
`agent.content_block_start`	`message_id`, `index`, `content_block`	Menandai awal blok konten, seperti teks, pemikiran, atau penggunaan tool.
`agent.content_block_delta`	`message_id`, `index`, `delta`	Mengirimkan fragmen inkremental untuk blok konten pada `index`.
`agent.content_block_stop`	`message_id`, `index`	Menandai akhir blok konten pada `index`.
`agent.message_delta`	`message_id`, `delta`, `usage`	Mengirimkan penambahan tingkat pesan seperti `stop_reason`, `stop_sequence`, dan informasi penggunaan.
`agent.message_stop`	`message_id`	Menandai akhir pesan asisten.

text_delta, thinking_delta, signature_delta, input_json_delta, dan tool_output_delta bukan tipe event tingkat atas. Mereka hanya muncul sebagai nilai dari agent.content_block_delta.delta.type.

`delta.type`	Field	Deskripsi
`text_delta`	`text`	Fragmen output teks. Klien dapat menggabungkan `delta.text` untuk merekonstruksi teks lengkap.
`thinking_delta`	`thinking`	Fragmen output pemikiran model atau penyedia.
`signature_delta`	`signature`	Fragmen signature untuk blok pemikiran. Hanya dikirimkan jika signature tersedia.
`input_json_delta`	`partial_json`	Fragmen dari input JSON alat.
`tool_output_delta`	bervariasi	Disediakan untuk streaming output tool di masa depan. Saat ini, `agent.tool_result` lengkap tetap menjadi otoritatif.

Contoh agent.content_block_delta:

{
  "id": "evt_delta_xxx",
  "type": "agent.content_block_delta",
  "session_id": "sess_xxx",
  "message_id": "msg_xxx",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "Here"
  },
  "processed_at": "2026-06-22T11:00:01Z"
}

Aturan untuk menguraikan event inkremental:

Baik baris event: SSE maupun data.type JSON menggunakan tipe event publik.
agent.content_block_delta.index membedakan antara beberapa blok konten.
processed_at dapat tidak tersedia pada event inkremental. Klien harus menganggapnya sebagai opsional.
Setelah gangguan jaringan, gunakan header Last-Event-ID yang membawa ID Event terakhir yang diterima untuk melanjutkan.
Mengatur include_thinking=false akan menyaring thinking_delta, signature_delta, dan semua event awal/akhir blok konten pemikiran yang dapat dikenali.
Mengatur include_tool_calls=false akan menyaring input_json_delta, tool_output_delta, dan semua event awal/akhir blok konten tool yang dapat dikenali.