Aliran peristiwa sesi

Aliran acara sesi

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

Semua permintaan API Managed Agents memerlukan header beta managed-agents-2026-04-01. SDK secara otomatis menetapkan header beta.

Jenis peristiwa

Peristiwa mengalir dalam dua arah.

Peristiwa pengguna adalah apa yang Anda kirim ke agen untuk memulai sesi dan mengarahkannya saat berkembang.
Peristiwa sesi, peristiwa span, dan peristiwa agen dikirim kepada Anda untuk observabilitas ke dalam status sesi dan kemajuan agen Anda.

String jenis peristiwa mengikuti konvensi penamaan {domain}.{action}.

Setiap peristiwa mencakup stempel waktu processed_at yang menunjukkan kapan peristiwa dicatat di sisi server. Jika processed_at adalah null, itu berarti peristiwa telah antri oleh harness dan akan ditangani setelah peristiwa sebelumnya selesai diproses.

Mengintegrasikan peristiwa

Skenario tambahan

Menangani panggilan alat kustom

Ketika agen menjalankan alat kustom:

Sesi memancarkan peristiwa agent.custom_tool_use yang berisi nama alat dan masukan.
Sesi dijeda dengan peristiwa session.status_idle yang berisi stop_reason: requires_action. ID peristiwa pemblokiran ada di array stop_reason.requires_action.event_ids.
Jalankan alat di sistem Anda dan kirim peristiwa user.custom_tool_result untuk masing-masing, meneruskan ID peristiwa dalam parameter custom_tool_use_id bersama dengan konten hasil.
Setelah semua peristiwa pemblokiran diselesaikan, sesi beralih kembali ke running.

Konfirmasi alat

Ketika kebijakan izin memerlukan konfirmasi sebelum alat dijalankan:

Sesi mengeluarkan acara agent.tool_use atau agent.mcp_tool_use.
Sesi berhenti dengan acara session.status_idle yang berisi stop_reason: requires_action. ID acara pemblokir berada dalam array stop_reason.requires_action.event_ids.
Kirim acara user.tool_confirmation untuk masing-masing, meneruskan ID acara dalam parameter tool_use_id. Atur result ke "allow" atau "deny". Gunakan deny_message untuk menjelaskan penolakan.
Setelah semua acara pemblokir diselesaikan, sesi kembali ke running.

Melacak penggunaan

Objek sesi mencakup bidang usage dengan statistik token kumulatif. Ambil sesi setelah menjadi idle untuk membaca total terbaru, dan gunakan untuk melacak biaya, memberlakukan 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 semua panggilan model dalam sesi. Bidang cache_creation_input_tokens dan cache_read_input_tokens mencerminkan aktivitas prompt caching. Entri cache menggunakan TTL 5 menit, jadi giliran berturut-turut dalam jendela itu mendapat manfaat dari pembacaan cache, yang mengurangi biaya per-token.

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

                        # Send the result back
                        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

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop := event.stop_reason):
            match stop.type:
                case "requires_action":
                    for event_id in stop.event_ids:
                        # Approve the pending tool call
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.tool_confirmation",
                                    "tool_use_id": event_id,
                                    "result": "allow",
                                },
                            ],
                        )
                case "end_turn":
                    break