Aliran event sesi

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. Event system.message menambahkan 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}]")
                break

Sesi 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:

1. Buka aliran baru.
2. Daftarkan riwayat event lengkap untuk mengisi kumpulan ID event yang sudah terlihat.
3. 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 live.
    history = client.beta.sessions.events.list(session.id)
    seen_event_ids = {past_event.id for past_event in history}

    # Ikuti event live, 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":
                break

Mengirim 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:

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 workflow run yang dijeda oleh anggaran. Run 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 ketika agen memanggil alat kustom, dan ketika panggilan alat memerlukan konfirmasi Anda berdasarkan kebijakan izin. Kedua jeda mengikuti urutan yang sama:

1. Sesi memancarkan panggilan alat sebagai event agent.custom_tool_use, agent.tool_use, atau agent.mcp_tool_use.
2. Sesi dijeda dengan event session.status_idle yang stop_reason.type-nya adalah requires_action. ID event yang memblokir ada di array stop_reason.event_ids.
3. Untuk setiap ID event yang memblokir, kirim event user.custom_tool_result atau user.tool_confirmation. Hasil alat kustom tidak perlu menunggu langkah 2.
4. Setelah semua event yang memblokir diselesaikan, sesi beralih kembali ke running.

Dalam sesi multiagen, event yang memblokir dari subagen juga diposting 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. Hasil kedua untuk panggilan yang sama akan diterima dan 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":
                # Jalankan alat
                result = call_tool(event.name, 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 "session.status_idle":
                if event.stop_reason and event.stop_reason.type == "end_turn":
                    break

Jika agen memiliki workflow run 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 run 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:
                        # 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

Contoh sebelumnya menyetujui setiap panggilan setelah sesi menjadi idle. Jika agen memiliki workflow run 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 run 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.",
                },
            ],
        },
    ],
)

Riwayat percakapan dipertahankan kecuali sesi dihapus secara eksplisit. Ketika sesi menjadi idle, sandbox-nya di-checkpoint. 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 di tengah eksekusi, 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:

1. Agen menerapkan interupsi. Hingga saat itu, processed_at milik interupsi tetap None dan sesi tetap running. Respons model yang sedang berlangsung langsung berhenti, tetapi interupsi dapat memerlukan waktu lebih lama untuk diterapkan saat panggilan alat sedang berjalan.
2. Event user.interrupt muncul di aliran, dan giliran yang diinterupsi berakhir dengan event session.status_idle.
3. Agen memulai giliran berikutnya dengan user.message yang Anda kirim setelah interupsi.

stop_reason.type dari event idle adalah end_turn, nilai yang sama dengan giliran yang selesai dengan sendirinya. Jika ada workflow run yang terbuka, interupsi tidak mengakhiri satu pun dari run tersebut. Run yang sedang berjalan dapat membuat sesi tetap running, sehingga event session.status_idle pada langkah 2 mungkin tidak tiba. Lihat Menginterupsi sesi dengan run 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–1000 item teks. Konten tersebut ditambahkan ke konteks sistem sesi sebagai giliran role: "system". Konten ini tidak menggantikan "system prompt" (prompt sistem) tingkat atas, yang diatur 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

system.message didukung oleh model-model berikut:

• 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, event ditolak dengan error validasi model_does_not_support_mid_conversation_system. Model subagen tidak diperiksa, 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