Aliran event sesi

Komunikasi dengan Claude Managed Agents berbasis event. Anda mengirim event pengguna ke agen, dan menerima kembali event agen dan event sesi untuk melacak status.



Jenis event

Event mengalir dalam dua arah.

• Event pengguna dan event sistem adalah yang Anda kirim ke agen: event user.* memulai sesi dan mengarahkannya saat sesi berjalan; system.message memperbarui prompt sistem agen di antara giliran.
• Event sesi, event span, dan event agen dikirim kepada Anda untuk observabilitas ke dalam status sesi dan progres agen Anda. Koneksi stream yang memilih untuk ikut serta juga menerima event delta.

String jenis event sesi, span, agen, pengguna, dan sistem mengikuti konvensi penamaan {domain}.{action}. Event pratinjau delta khusus stream (event_start, event_delta) adalah pengecualian. Lihat Jenis event di referensi untuk katalog lengkapnya.

Setiap event yang dipersistensi menyertakan timestamp processed_at yang menunjukkan kapan event tersebut dicatat di sisi server. Jika processed_at bernilai null, itu berarti event telah diantrekan oleh harness dan ditangani setelah event sebelumnya selesai diproses.



Mengintegrasikan event



Event delta

Secara default, teks respons agen mencapai stream sebagai event agent.message yang di-buffer, masing-masing dipancarkan hanya setelah permintaan model yang menghasilkannya selesai. Event delta memungkinkan Anda merender teks tersebut secara inkremental, sebagai pratinjau langsung, saat model masih menghasilkannya. Pratinjau bukanlah respons: pratinjau adalah alat bantu tampilan best-effort, dan agent.message yang di-buffer selalu menjadi catatan otoritatif. Klien yang mengabaikan pratinjau tetap menerima stream yang lengkap dan benar.



Memilih untuk menerima pratinjau

Pratinjau bersifat opt-in per koneksi stream. Tambahkan parameter kueri event_deltas[] ke GET /v1/sessions/{session_id}/events/stream, 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. Hanya stream event tingkat sesi yang mendukung parameter ini. Stream event thread sesi menolaknya.

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

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

Untuk agent.message, start diikuti oleh event event_delta yang membawa teks inkremental. 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"
    }
  }
}

Ketika event agent.thinking dipratinjau, hanya event_start yang dipancarkan. Tidak ada event event_delta yang mengikuti, dan konten tiba dalam event agent.thinking yang di-buffer seperti biasa.

Tidak seperti event yang dipersistensi, event_start dan event_delta tidak memiliki id atau processed_at sendiri. Satu-satunya pengidentifikasi yang mereka bawa adalah id dari event yang mereka pratinjau.



Akumulasi dan rekonsiliasi

SDK Python, TypeScript, dan Go menyertakan helper akumulator yang mengindeks pratinjau berdasarkan id event dan menangani pembukuan index untuk Anda. Pola manual berfungsi di setiap bahasa: di SDK lainnya, terapkan pola ini ke jenis event yang dihasilkan.

Dalam pola manual, perlakukan pratinjau sebagai buffer sementara dan event yang di-buffer sebagai catatan. Indeks buffer berdasarkan (event_id, index). Rekonsiliasi per permintaan model: sebuah giliran dibuka dengan satu event session.status_running, lalu pada giliran yang selesai secara normal, setiap permintaan model menghasilkan, secara berurutan, span.model_request_start, event_start, event-event event_delta, agent.message yang di-buffer, dan akhirnya span.model_request_end (di tab Event span). Proses setiap event saat tiba:

1. Pada event_start, catat id yang diumumkan. Pengidentifikasi 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 render teks yang sedang berjalan. Delta pertama untuk sebuah index membuat entri tersebut.
3. Ketika agent.message yang di-buffer tiba, cocokkan berdasarkan id, buang pratinjau yang terakumulasi, dan render konten pesan sebagai gantinya.
4. Pada span.model_request_end, tutup pratinjau apa pun yang belum direkonsiliasi oleh event yang di-buffer-nya. Tidak ada lagi delta yang akan datang untuknya. Jika giliran mengalami error atau diinterupsi, event yang di-buffer mungkin tidak pernah tiba; span.model_request_end tetap tiba.

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

# Aktifkan (opt in) 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 pratinjau apa pun 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



Keterbatasan

Pratinjau disetel untuk responsivitas. Bangun dengan mempertimbangkan batasan berikut:

• Best effort: Di bawah beban tinggi, server mungkin membuang delta untuk sebuah event. Ketika itu terjadi, Anda menerima prefiks teks yang berurutan dan kemudian tidak ada delta lebih lanjut untuk event tersebut. agent.message yang di-buffer tetap tiba lengkap. Jangan pernah memperlakukan pratinjau yang terakumulasi sebagai final.
• Tidak ada replay saat reconnect: Delta hanya dikirimkan ke koneksi yang memilih untuk ikut serta, selama koneksi tersebut terbuka. Jika stream terputus, ikuti prosedur reconnect di tab Streaming event: buka kembali stream dan ambil daftar riwayat event. Riwayat mencakup event yang di-buffer apa pun yang dipancarkan saat Anda terputus, termasuk agent.message yang ditunggu oleh pratinjau Anda. Tidak ada cara untuk meminta ulang delta yang terlewat.
• Thread utama, teks saja: Pratinjau mencakup teks asisten pada thread utama sesi. Penggunaan alat, hasil alat, hasil MCP, dan aktivitas pada thread sesi lainnya tidak pernah dipratinjau.
• agent.thinking hanya start: Pratinjau agent.thinking hanya memancarkan event_start sebagai sinyal bahwa blok thinking telah dimulai; tidak ada event event_delta yang mengikutinya.
• Tidak pernah dipersistensi: event_start dan event_delta hanya ada di stream langsung. Mereka tidak muncul di riwayat event sesi (GET /v1/sessions/{session_id}/events).



Skenario tambahan



Menangani panggilan alat kustom

Ketika agen memanggil alat kustom:

1. Sesi memancarkan event agent.custom_tool_use yang berisi nama alat dan input.
2. Sesi berhenti sementara dengan event session.status_idle yang berisi stop_reason: requires_action. ID event yang memblokir ada di array stop_reason.event_ids.
3. Jalankan alat di sistem Anda dan kirim event user.custom_tool_result untuk masing-masing, dengan meneruskan ID event di parameter custom_tool_use_id bersama dengan konten hasil.
4. Setelah semua event yang memblokir diselesaikan, sesi bertransisi kembali ke running.

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop_reason := event.stop_reason):
            match stop_reason.type:
                case "requires_action":
                    for event_id in stop_reason.event_ids:
                        # Cari event custom tool use dan jalankan
                        tool_event = events_by_id[event_id]
                        result = call_tool(tool_event.name, tool_event.input)

                        # Kirim hasilnya kembali
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.custom_tool_result",
                                    "custom_tool_use_id": event_id,
                                    "content": [{"type": "text", "text": result}],
                                },
                            ],
                        )
                case "end_turn":
                    break



Konfirmasi alat

Ketika kebijakan izin memerlukan konfirmasi sebelum alat dieksekusi:

1. Sesi memancarkan event agent.tool_use atau agent.mcp_tool_use.
2. Sesi berhenti sementara dengan event session.status_idle yang berisi stop_reason: requires_action. ID event yang memblokir ada di array stop_reason.event_ids.
3. Kirim event user.tool_confirmation untuk masing-masing, dengan meneruskan ID event di parameter tool_use_id. Atur result ke "allow" atau "deny". Gunakan deny_message untuk menjelaskan penolakan.
4. Setelah semua event yang memblokir diselesaikan, sesi bertransisi kembali ke running.

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop_reason := event.stop_reason):
            match stop_reason.type:
                case "requires_action":
                    for event_id in stop_reason.event_ids:
                        # Setujui panggilan alat yang tertunda
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.tool_confirmation",
                                    "tool_use_id": event_id,
                                    "result": "allow",
                                },
                            ],
                        )
                case "end_turn":
                    break



Melanjutkan sesi idle

Sesi tetap ada di antara interaksi. Riwayat percakapan dipertahankan kecuali sesi dihapus secara eksplisit. Ketika sesi menjadi idle, sandbox-nya di-checkpoint, mempertahankan seluruh status sandbox, termasuk filesystem, paket yang terinstal, dan file apa pun yang dibuat agen. Ini memungkinkan Anda melanjutkan dengan bersih dari ketidakaktifan.

Untuk melanjutkan sesi, kirim event user.message ke sesi tersebut seperti biasa:

# Di produksi, berikan ID tersimpan dari sesi yang ingin Anda lanjutkan.
ant beta:sessions:events send --session-id "$SESSION_ID" <<'YAML'
events:
  - type: user.message
    content:
      - type: text
        text: Now run the tests against the changes you made earlier.
YAML



Mengirim pesan sistem

Kirim event system.message untuk memperbarui prompt sistem agen di antara giliran. Tidak seperti field system pada definisi agen (yang ditetapkan saat pembuatan sesi), system.message memungkinkan Anda mengubah prompt sistem saat sesi berjalan. Gunakan ini ketika agen memerlukan panduan tingkat sistem yang diperbarui di tengah sesi: persona yang berbeda, batasan yang direvisi, atau konteks yang diambil saat runtime yang seharusnya membentuk perilaku model ke depannya.

ant beta:sessions:events send --session-id "$SESSION_ID" <<'YAML'
events:
  - type: system.message
    content:
      - type: text
        text: "The user's current timezone is America/New_York."
YAML

system.message tidak dapat dikirim saat sesi idle dengan stop_reason: requires_action. content menerima 1–1000 item teks.



Melacak penggunaan

Objek sesi menyertakan field usage dengan statistik token kumulatif. Ambil sesi setelah menjadi idle untuk membaca total terbaru, dan gunakan untuk melacak biaya, menerapkan anggaran, atau memantau konsumsi.

{
  "id": "sesn_01...",
  "status": "idle",
  "usage": {
    "input_tokens": 5000,
    "output_tokens": 3200,
    "cache_creation_input_tokens": 2000,
    "cache_read_input_tokens": 20000
  }
}

input_tokens melaporkan token input yang tidak di-cache dan output_tokens melaporkan total token output di seluruh panggilan model dalam sesi. Field cache_creation_input_tokens dan cache_read_input_tokens mencerminkan aktivitas caching prompt. Entri cache menggunakan TTL 5 menit, sehingga giliran berturut-turut dalam jendela waktu tersebut mendapat manfaat dari pembacaan cache, yang mengurangi biaya per token.



Observabilitas Console

Console menyediakan tampilan timeline visual dari sesi agen Anda. Navigasikan ke bagian Claude Managed Agents di Console untuk melihat:

• Daftar sesi: Semua sesi dengan status, waktu pembuatan, dan modelnya
• Tampilan tracing: Tampilan kronologis event (konten, timestamp, penggunaan token) dalam sebuah sesi. Tampilan tracing hanya dapat diakses oleh Developer dan Admin.
• Eksekusi alat: Detail setiap panggilan alat dan hasilnya



Tips debugging

• Periksa event sesi: Error sesi disampaikan melalui event session.error
• Tinjau hasil alat: Kegagalan eksekusi alat sering kali menjelaskan perilaku agen yang tidak terduga
• Lacak penggunaan token: Pantau konsumsi token untuk mengoptimalkan prompt dan mengurangi biaya
• Gunakan prompt sistem: Tambahkan instruksi logging ke prompt sistem agar agen menjelaskan penalarannya