Aliran event sesi
Kirim event, streaming respons, dan interupsi atau arahkan ulang sesi Anda saat sedang berjalan.
Komunikasi dengan Claude Managed Agents berbasis event. Anda membuka aliran (stream) untuk mengikuti sesi, mengirim event untuk mengarahkannya, dan menjawabnya ketika sesi berhenti sejenak untuk menunggu input.
Jenis event
Event mengalir dalam dua arah: Anda mengirim event ke agen, dan sesi mengirim event kembali kepada Anda.
- Event yang Anda kirim: Event
user.*memulai sesi dan mengarahkannya seiring berjalannya sesi. Eventsystem.messagemenambahkan konteks tingkat sistem. - Event yang Anda terima: Event sesi, event span, dan event agen melaporkan status sesi dan kemajuan agen.
String jenis event ini mengikuti konvensi penamaan {domain}.{action}. Lihat Jenis event di referensi untuk katalog lengkapnya.
Jenis event webhook bersifat terpisah, dan beberapa namanya berbeda dari nama di aliran. Misalnya, webhook menggunakan session.status_idled alih-alih session.status_idle.
Streaming event
Lakukan “streaming” (streaming) event dari sesi untuk menerima pembaruan real-time saat agen bekerja. Sebuah aliran hanya mengirimkan event yang dipancarkan setelah aliran dibuka, jadi buka aliran sebelum Anda mengirim event untuk menghindari “race condition” (kondisi balapan).
# Buka stream terlebih dahulu, lalu kirim pesan pengguna
with client.beta.sessions.events.stream(session.id) as stream:
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.message",
"content": [{"type": "text", "text": "Summarize the repo README"}],
},
],
)
for event in stream:
match event.type:
case "agent.message":
for block in event.content:
if block.type == "text":
print(block.text, end="")
case "session.status_idle":
break
case "session.error":
error_message = event.error.message if event.error else "unknown"
print(f"\n[Error: {error_message}]")
breakSesi melaporkan error melalui event session.error. Lihat Jenis event untuk field-nya.
Teks respons agen tiba sebagai event agent.message yang di-buffer, masing-masing dipancarkan hanya setelah permintaan model yang menghasilkannya selesai. Untuk merender teks saat model masih menghasilkannya, lihat Pratinjau respons dengan delta event.
Menyambung ulang tanpa kehilangan event
Untuk menyambung ulang ke sesi yang sudah ada tanpa kehilangan event, gabungkan aliran baru dengan riwayat event:
- Buka aliran baru.
- Daftarkan riwayat event lengkap untuk mengisi kumpulan ID event yang sudah terlihat.
- Ikuti aliran langsung, lewati event apa pun yang sudah dikembalikan oleh daftar riwayat.
with client.beta.sessions.events.stream(session.id) as stream:
# Stream terbuka dan sedang buffering. Daftarkan riwayat sebelum mengikuti event langsung.
history = client.beta.sessions.events.list(session.id)
seen_event_ids = {past_event.id for past_event in history}
# Ikuti event langsung, lewati apa pun yang sudah terlihat
for event in stream:
if event.type == "event_start" or event.type == "event_delta":
# Pratinjau delta tidak diaktifkan pada koneksi ini.
continue
if event.id in seen_event_ids:
continue
seen_event_ids.add(event.id)
match event.type:
case "agent.message":
for block in event.content:
if block.type == "text":
print(block.text, end="")
case "session.status_idle":
breakMengirim event
Kirim event user.message untuk memulai atau melanjutkan pekerjaan agen:
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "Analyze the performance of the sort function in utils.py",
},
],
},
],
)Setiap event dalam riwayat sesi menyertakan timestamp processed_at, yang ditetapkan ketika event selesai diproses. Pada event yang Anda kirim, processed_at bernilai None selama event masih mengantre di belakang event sebelumnya. Pengecualiannya adalah user.define_outcome, user.custom_tool_result, dan user.tool_result, yang diproses saat diterima dan dikembalikan dengan processed_at yang sudah terisi.
Merespons ketika sesi menjadi idle
Event session.status_idle berarti agen telah berhenti dan sedang menunggu input. stop_reason.type-nya menjelaskan alasannya:
stop_reason.type | Mengapa sesi berhenti | Apa yang harus dilakukan |
|---|---|---|
end_turn | Agen menyelesaikan gilirannya, atau Anda menginterupsinya. | Kirim user.message ketika Anda memiliki pekerjaan lain untuk agen. |
requires_action | Satu atau lebih panggilan alat memerlukan jawaban dari Anda, seperti panggilan alat kustom atau permintaan konfirmasi. | Jawab setiap panggilan alat yang memblokir. |
budget_reached | Biaya daftar yang dilacak sesi telah mencapai anggarannya. | Ubah atau hapus anggaran. |
Tidak ada event yang Anda kirim yang dapat melanjutkan sesi yang dijeda karena anggarannya. Pekerjaan yang dijeda oleh anggaran akan dilanjutkan secara otomatis ketika Anda mengubah anggaran ke nilai di atas biaya daftar yang telah terpakai, atau menghapusnya. Ketika pekerjaan dilanjutkan, sesi memancarkan event workflow_run.status_running untuk setiap eksekusi workflow yang dijeda oleh anggaran. Eksekusi yang dijeda oleh interupsi tetap dijeda; lihat Melanjutkan sesi pada anggarannya. Lihat Ketika sesi mencapai anggarannya untuk event yang menandai jeda dan event yang masih diterima sesi.
Menjawab panggilan alat yang menjeda sesi
Sesi dijeda saat agen memanggil alat kustom, dan saat panggilan alat memerlukan konfirmasi Anda berdasarkan kebijakan izin. Kedua jeda tersebut mengikuti urutan yang sama:
- Sesi memancarkan panggilan alat sebagai event
agent.custom_tool_use,agent.tool_use, atauagent.mcp_tool_use. - Sesi dijeda dengan event
session.status_idleyangstop_reason.type-nya adalahrequires_action. ID event yang memblokir ada di arraystop_reason.event_ids. - Untuk setiap ID event yang memblokir, kirim event
user.custom_tool_resultatauuser.tool_confirmation. Hasil alat kustom tidak perlu menunggu langkah 2. - Setelah semua event yang memblokir diselesaikan, sesi beralih kembali ke
running.
Dalam sesi multiagen, server juga memposting event yang memblokir dari subagen ke thread utama. Lihat Izin alat dan alat kustom.
Mengembalikan hasil alat kustom
Event agent.custom_tool_use berisi nama alat dan input. Jalankan alat di sistem Anda. Kemudian kirim event user.custom_tool_result, dengan meneruskan ID event di parameter custom_tool_use_id beserta konten hasilnya.
Anda dapat mengirim hasil segera setelah event agent.custom_tool_use tiba, tanpa menunggu session.status_idle. Sesi tetap memancarkan session.status_idle dengan alasan berhenti requires_action untuk panggilan tersebut, dan klien Anda dapat mengabaikannya. Server menerima hasil kedua untuk panggilan yang sama, tetapi hasil tersebut tidak berpengaruh.
Ketika Anda menyambung ulang ke sesi yang dijeda, stop_reason.event_ids pada event session.status_idle terbaru mencantumkan panggilan yang perlu dijawab.
Contoh berikut menjawab setiap panggilan saat panggilan tersebut tiba:
with client.beta.sessions.events.stream(session.id) as stream:
for event in stream:
match event.type:
case "agent.custom_tool_use":
result = call_tool(event.name, event.input)
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 "session.status_idle":
if event.stop_reason and event.stop_reason.type == "end_turn":
breakJika agen memiliki eksekusi workflow yang terbuka, panggilan alat kustom dapat tiba saat sesi tetap running. Event idle requires_action hanya tiba ketika tidak ada satu pun thread sesi yang sedang bekerja. Jangan menunggunya: jawab setiap panggilan ketika event agent.custom_tool_use-nya tiba. Contoh di Mengikuti eksekusi menunjukkan caranya.
Mengonfirmasi panggilan alat
Kirim event user.tool_confirmation, dengan meneruskan ID event di parameter tool_use_id. Atur result ke "allow" atau "deny". Lihat Merespons permintaan konfirmasi untuk mengetahui panggilan mana yang menunggu konfirmasi dan cara menjelaskan penolakan.
Contoh berikut menyetujui setiap panggilan yang tertunda:
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:
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.tool_confirmation",
"tool_use_id": event_id,
"result": "allow",
},
],
)
case "end_turn":
breakContoh sebelumnya menyetujui setiap panggilan setelah sesi menjadi idle. Jika agen memiliki eksekusi workflow yang terbuka, panggilan alat dapat menunggu konfirmasi Anda saat sesi tetap running. Jangan menunggu event idle: ketika event agent.tool_use atau agent.mcp_tool_use tiba dengan evaluated_permission bernilai ask, jawablah. Contoh di Mengikuti eksekusi menjawab panggilan alat kustom dengan cara ini, dan pengantarnya menjelaskan cara menambahkan konfirmasi.
Melanjutkan sesi yang idle
Sesi tetap ada di antara interaksi. Untuk melanjutkan sesi, kirim event user.message ke sesi tersebut seperti biasa:
# Lanjutkan sesi yang dibuat sebelumnya dengan mengirimkan event user.message baru.
# Di produksi, berikan ID tersimpan dari sesi yang ingin Anda lanjutkan.
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "Now run the tests against the changes you made earlier.",
},
],
},
],
)Sesi menyimpan riwayat percakapannya hingga Anda menghapus sesi tersebut. Ketika sesi menjadi idle, Claude Managed Agents melakukan checkpoint pada sandbox-nya. Checkpoint mempertahankan seluruh status sandbox, termasuk sistem file, paket yang terinstal, dan file apa pun yang dibuat oleh agen.
Menginterupsi agen
Kirim event user.interrupt untuk menghentikan agen saat sedang berjalan, lalu lanjutkan dengan event user.message untuk mengarahkannya ulang:
# Agen sedang menganalisis sebuah file...
# Interupsi dengan arahan baru:
client.beta.sessions.events.send(
session.id,
events=[
{"type": "user.interrupt"},
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "Instead, focus on fixing the bug in line 42.",
},
],
},
],
)Panggilan kembali segera setelah event dimasukkan ke antrean. Interupsi kemudian berlaku dalam urutan berikut:
- Agen menerapkan interupsi. Hingga saat itu,
processed_atdari interupsi tetap bernilaiNonedan sesi tetaprunning. Respons model yang sedang berlangsung langsung berhenti, tetapi interupsi dapat memerlukan waktu lebih lama untuk diterapkan saat panggilan alat sedang berjalan. - Event
user.interruptmuncul di aliran, dan giliran yang diinterupsi berakhir dengan eventsession.status_idle. - Agen memulai giliran berikutnya dengan
user.messageyang Anda kirim setelah interupsi.
stop_reason.type dari event idle adalah end_turn, nilai yang sama dengan giliran yang selesai dengan sendirinya. Jika ada eksekusi workflow yang terbuka, interupsi tidak mengakhiri satu pun dari eksekusi tersebut. Eksekusi yang sedang berjalan dapat membuat sesi tetap running, sehingga event session.status_idle pada langkah 2 mungkin tidak tiba. Lihat Menginterupsi sesi dengan eksekusi yang terbuka.
Mendaftar event sebelumnya
Ambil riwayat event lengkap untuk sebuah sesi:
events = client.beta.sessions.events.list(session.id)
for event in events.data:
print(f"[{event.type}] {event.processed_at}")Teruskan filter types untuk hanya mengembalikan jenis event tertentu:
events = client.beta.sessions.events.list(
session.id,
types=["agent.tool_use", "agent.tool_result"],
)
for event in events.data:
print(f"[{event.type}] {event.processed_at}")Mengirim pesan sistem
Pada model yang didukung, kirim event system.message untuk memberikan konteks tingkat sistem yang istimewa kepada agen. Konteks tersebut berlaku untuk giliran yang menyertainya dan semua giliran berikutnya. Gunakan ini ketika agen memerlukan panduan tingkat sistem yang diperbarui di tengah sesi, misalnya persona yang berbeda, batasan yang direvisi, atau konteks yang diambil saat runtime.
content dari event menerima 1–1.000 item teks. Server menambahkan konten tersebut ke konteks sistem sesi sebagai giliran role: "system". Konten ini tidak menggantikan “system prompt” (prompt sistem) tingkat atas, yang ditetapkan oleh field system pada definisi agen.
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "system.message",
"content": [
{
"type": "text",
"text": "The user's current timezone is America/New_York.",
},
],
},
],
)Model yang didukung
Model-model berikut mendukung system.message:
- Claude Fable 5.2
- Claude Mythos 5.2
- Claude Fable 5.1
- Claude Mythos 5.1
- Claude Fable 5
- Claude Mythos 5
- Claude Opus 5.5
- Claude Opus 5
- Claude Opus 4.8
- Claude Sonnet 5.5
- Claude Haiku 5.5
Jika model utama agen tidak mendukung injeksi sistem di tengah percakapan, API menolak event tersebut dengan error validasi model_does_not_support_mid_conversation_system. API tidak memeriksa model subagen, karena system.message hanya masuk ke thread utama.
Pesan sistem saat panggilan alat tertunda
Saat sesi idle dengan alasan berhenti requires_action, system.message harus mengikuti event hasil alat dalam permintaan yang sama. Jika dikirim sendiri atau bersama user.message, pesan tersebut ditolak hingga event alat yang tertunda diselesaikan.
Langkah selanjutnya
Render teks respons agen saat model masih menghasilkannya.
Periksa sesi di Claude Console dan baca penggunaan token serta biaya daftarnya.
Dapatkan notifikasi saat event penting terjadi tanpa polling.
Cari setiap jenis event yang dapat dikirim atau diterima oleh sesi.
Apakah halaman ini membantu?