Pratinjau respons dengan event delta

Secara default, teks respons agen mencapai aliran event sesi sebagai event agent.message yang di-buffer. Masing-masing dipancarkan hanya setelah permintaan model yang menghasilkannya selesai. Event delta memungkinkan Anda menampilkan teks tersebut secara bertahap, sebagai pratinjau langsung, saat model masih menghasilkannya.

Pratinjau adalah alat bantu tampilan berbasis "best-effort" (upaya terbaik), dan agent.message yang di-buffer selalu menjadi catatan otoritatif. Klien yang mengabaikan pratinjau tetap menerima aliran yang lengkap dan benar.

Mengaktifkan pratinjau

Pratinjau bersifat opt-in per koneksi aliran. Tambahkan parameter kueri event_deltas[] ke aliran yang Anda baca, dan ulangi sekali untuk setiap jenis event yang ingin Anda pratinjau. Nilai yang diterima adalah agent.message dan agent.thinking. Nilai lain apa pun mengembalikan error 400, begitu pula permintaan dengan lebih dari 100 nilai.

Kedua endpoint aliran menerima parameter ini:

• Aliran tingkat sesi: GET /v1/sessions/{session_id}/events/stream
• Aliran thread sesi: GET /v1/sessions/{session_id}/threads/{thread_id}/stream

Pratinjau subagen muncul di aliran thread milik subagen tersebut.

[] adalah pola glob shell, jadi beri tanda kutip pada URL setiap kali Anda membangun permintaan di shell. Contoh-contoh ini melakukan percent-encoding pada tanda kurung siku sebagai %5B%5D, yang juga berfungsi.

Event pratinjau

Ketika event yang dipratinjau dimulai, aliran memancarkan event_start yang membawa jenis dan id event yang akan datang:

{
  "type": "event_start",
  "event": {
    "type": "agent.message",
    "id": "sevt_01abc..."
  }
}

Untuk agent.message, start tersebut diikuti oleh event event_delta yang membawa teks bertahap. Setiap delta menyebutkan event yang diperluasnya di event_id dan blok konten yang diperluasnya di delta.index:

{
  "type": "event_delta",
  "event_id": "sevt_01abc...",
  "delta": {
    "type": "content_delta",
    "index": 0,
    "content": {
      "type": "text",
      "text": "Here is the summary"
    }
  }
}

Untuk agent.thinking, hanya event_start yang dipancarkan, sebagai sinyal bahwa blok thinking telah dimulai. Tidak ada event event_delta yang menyusul. Event agent.thinking yang di-buffer yang mengakhiri pratinjau adalah sinyal kemajuan dan tidak membawa konten thinking.

Tidak seperti event yang dipersistenkan, event_start dan event_delta tidak memiliki id atau processed_at sendiri. Satu-satunya pengenal yang mereka bawa adalah id dari event yang mereka pratinjau. String jenisnya juga merupakan pengecualian dari konvensi penamaan {domain}.{action} pada event yang dipersistenkan.

Mengakumulasi dan merekonsiliasi

Setiap SDK yang mendukung event delta menyertakan helper akumulator yang menangani pencatatan index untuk Anda. Pola manual di bagian ini berfungsi di setiap bahasa ketika Anda memerlukan pencatatan kustom. Terapkan pola ini pada jenis event yang dihasilkan.

Dalam pola manual, simpan teks pratinjau dalam map sementara dengan kunci (event_id, index), dan perlakukan event yang di-buffer sebagai catatan. Rekonsiliasikan keduanya per permintaan model.

Sebuah giliran dibuka dengan satu event session.status_running. Pada giliran yang selesai secara normal, setiap permintaan model kemudian menghasilkan event-event berikut, secara berurutan:

1. span.model_request_start
2. event_start
3. Event-event event_delta
4. agent.message yang di-buffer
5. span.model_request_end (di tab Event span)

Di wire, ini adalah bagian yang dipratinjau dari urutan tersebut, diselingi dengan event ter-buffer lain milik koneksi:

event_start     {"event": {"type": "agent.message", "id": "sevt_01abc..."}}
event_delta     {"event_id": "sevt_01abc...", "delta": {"type": "content_delta", "index": 0, "content": {"type": "text", "text": "..."}}}
...
agent.message   {"id": "sevt_01abc...", "content": [...]}

Baris event_delta berulang sekali per fragmen teks. Proses setiap event saat tiba:

1. Pada event_start, catat id yang diumumkan. Pengenal-pengenalnya selalu selaras: event_start.event.id, setiap event_delta.event_id, dan id dari agent.message yang di-buffer adalah nilai yang sama.
2. Pada setiap event_delta, tambahkan delta.content.text ke entri di (event_id, delta.index) dan tampilkan teks yang telah terakumulasi sejauh ini. Delta pertama untuk sebuah index membuat entri tersebut.
3. Ketika agent.message yang di-buffer tiba, cocokkan berdasarkan id, buang pratinjau yang terakumulasi, dan tampilkan konten pesan sebagai gantinya.
4. Pada span.model_request_end, tutup pratinjau apa pun yang belum direkonsiliasi oleh event ter-buffer-nya. Tidak ada lagi delta yang akan datang untuknya. Jika giliran mengalami error atau diinterupsi, event yang di-buffer mungkin tidak pernah tiba, tetapi span.model_request_end tetap tiba.

Pola ini bergantung pada dua jaminan:

• Menggabungkan delta-delta pratinjau sesuai urutan kedatangan, dengan kunci (event_id, index), menghasilkan prefiks dari content[index].text di event yang di-buffer. Ini belum tentu keseluruhan teks, karena delta mungkin dibuang saat beban tinggi.
• Sebuah koneksi memancarkan paling banyak satu event_start per event_id, dan event yang di-buffer adalah hal terakhir yang dikirimkan koneksi tersebut untuk id itu.

Helper akumulator SDK

Helper setiap SDK menangani pencatatan index. Helper Go, Java, Ruby, dan C# juga menyimpan pratinjau yang sedang diakumulasi dengan kunci id event. Dengan helper Python, TypeScript, dan PHP, kelola map tersebut sendiri dan gabungkan setiap delta ke dalam entri untuk id-nya.

Contoh-contoh berikut mengaktifkan pratinjau agent.message dan merekonsiliasinya dengan event yang di-buffer:

# Snapshot pratinjau, dengan kunci id event. accumulate_managed_agents_event melipat setiap
# event_start / event_delta menjadi snapshot agent.message; agent.message
# yang di-buffer akan menggantikannya.
previews: dict[str, BetaManagedAgentsAgentMessageEvent] = {}

# Aktifkan pratinjau agent.message pada koneksi ini
with client.beta.sessions.events.stream(
    session.id, event_deltas=["agent.message"]
) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Describe the repo in one sentence."}],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "event_start":
                snapshot = accumulate_managed_agents_event(None, event)
                if snapshot is not None:
                    previews[event.event.id] = snapshot
                print(f"event_start             {event.event.type} {event.event.id}")
            case "event_delta":
                preview = accumulate_managed_agents_event(previews.get(event.event_id), event)
                if preview is not None:
                    previews[event.event_id] = preview
                    text = "".join(block.text for block in preview.content)
                    print(f"event_delta             preview: {text!r}")
            case "agent.message":
                # Event yang di-buffer adalah catatan resminya: ia menggantikan dan menutup pratinjau
                preview = accumulate_managed_agents_event(previews.pop(event.id, None), event)
                text = "".join(block.text for block in preview.content)
                print(f"agent.message           {event.id} {text!r}")
            case "span.model_request_end":
                # Tidak ada delta lagi yang akan datang. Tutup setiap pratinjau yang
                # event buffer-nya tidak pernah tiba.
                for event_id in previews:
                    print(f"span.model_request_end  closing preview for {event_id}")
                previews.clear()
            case "session.status_idle":
                break

Pratinjau event thread sesi

Dalam sesi multiagen, setiap thread sesi memiliki aliran event sendiri. Aliran ini menerima parameter event_deltas[] yang sama dengan nilai yang sama.

Sebuah koneksi hanya mempratinjau thread yang sedang dibacanya. Aliran tingkat sesi mempratinjau thread utama, dan pratinjau thread anak tidak pernah diposting silang ke sana. Untuk melihat teks subagen saat model menghasilkannya, buka aliran thread subagen tersebut.

Path aliran thread diakhiri dengan /threads/{thread_id}/stream. /events/stream hanya ada di tingkat sesi, jadi tidak ada endpoint /threads/{thread_id}/events/stream.

event_start dan event_delta memiliki bentuk yang sama di aliran thread seperti di aliran tingkat sesi, dan pola mengakumulasi dan merekonsiliasi berlaku sebagaimana tertulis. Jalankan satu instans akumulator per koneksi aliran.

# Daftar thread milik sesi dan pilih satu anak: thread anak membawa parent_thread_id
# non-null, sedangkan parent_thread_id thread utama bernilai null.
child_thread = next(
    thread
    for thread in client.beta.sessions.threads.list(session.id)
    if thread.parent_thread_id is not None
)

# Stream thread anak menerima parameter event_deltas yang sama dengan
# stream sesi.
with client.beta.sessions.threads.events.stream(
    child_thread.id,
    session_id=session.id,
    event_deltas=["agent.message"],
) as stream:
    for event in stream:
        match event.type:
            case "event_delta":
                print(event.delta.content.text, end="")
            case "agent.message":
                # Event yang di-buffer adalah catatan otoritatif; render kontennya
                print()
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
                print()
            case "session.thread_status_idle":
                break

Loop pembacaan keluar pada session.thread_status_idle, event yang dipancarkan ketika giliran thread sesi selesai dan thread menjadi idle.

Keterbatasan

• Best effort: Saat beban tinggi, server mungkin membuang delta untuk sebuah event. Ketika itu terjadi, Anda menerima prefiks teks yang berkesinambungan lalu tidak ada delta lebih lanjut untuk event tersebut. agent.message yang di-buffer tetap tiba secara lengkap. Jangan pernah memperlakukan pratinjau yang terakumulasi sebagai final.
• Tidak ada replay saat menyambung ulang: Delta hanya dikirimkan ke koneksi yang mengaktifkannya, selama koneksi tersebut terbuka. Ini berlaku sama untuk aliran tingkat sesi maupun setiap aliran thread sesi. Koneksi yang dibuka setelah permintaan model dimulai tidak menerima delta untuk event yang sedang berlangsung tersebut. Tidak ada cara untuk meminta ulang delta yang terlewat.
• Satu thread, hanya teks: Pratinjau mencakup teks asisten di thread yang sedang dibaca koneksi. Penggunaan alat, hasil alat, dan hasil MCP tidak pernah dipratinjau.
• Tidak pernah dipersistenkan: event_start dan event_delta hanya ada di aliran langsung. Keduanya tidak muncul di riwayat event sesi (GET /v1/sessions/{session_id}/events) atau di riwayat event thread sesi mana pun.

Memecahkan masalah pratinjau

Langkah selanjutnya