Aliran event sesi

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

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

Jenis event

Event mengalir dalam dua arah.

Event pengguna adalah apa yang Anda kirim ke agen untuk memulai sesi dan mengarahkannya saat berlangsung.
Event sesi, event span, dan event agen dikirim kepada Anda untuk observabilitas ke dalam status sesi dan kemajuan agen.

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

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

Lihat referensi API event sesi untuk skema lengkap setiap jenis event.

Mengintegrasikan event

Skenario tambahan

Menangani panggilan alat kustom

Ketika agen memanggil alat kustom:

Sesi memancarkan event agent.custom_tool_use yang berisi nama alat dan input.
Sesi berhenti sejenak dengan event session.status_idle yang berisi stop_reason: requires_action. ID event yang memblokir ada di array stop_reason.requires_action.event_ids.
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 beserta konten hasilnya.
Setelah semua event yang memblokir diselesaikan, sesi bertransisi kembali ke running.

Konfirmasi alat

Ketika kebijakan izin memerlukan konfirmasi sebelum alat dieksekusi:

Sesi memancarkan event agent.tool_use atau agent.mcp_tool_use.
Sesi berhenti sementara dengan event session.status_idle yang berisi stop_reason: requires_action. ID event yang memblokir ada di dalam array stop_reason.requires_action.event_ids.
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.
Setelah semua event yang memblokir diselesaikan, sesi bertransisi kembali ke running.

Melacak penggunaan

Objek sesi menyertakan field usage dengan statistik token kumulatif. Ambil sesi setelah sesi tersebut 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 semua panggilan model dalam sesi. Field cache_creation_input_tokens dan cache_read_input_tokens mencerminkan aktivitas prompt caching. Entri cache menggunakan TTL 5 menit, sehingga giliran berturut-turut dalam jendela waktu tersebut mendapat manfaat dari pembacaan cache, yang mengurangi biaya per token.

exec {fd}< <(curl -sS -N --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -H "Accept: text/event-stream")

while IFS= read -r -u "$fd" line; do
  [[ $line == data:* ]] || continue
  data="${line#data: }"
  [[ $(jq -r '.type' <<<"$data") == "session.status_idle" ]] || continue
  case $(jq -r '.stop_reason.type // empty' <<<"$data") in
    requires_action)
      while IFS= read -r event_id; do
        # Cari event penggunaan alat kustom dan jalankan
        result=$(call_tool "$event_id")
        # Kirim hasilnya kembali
        jq -n --arg id "$event_id" --arg result "$result" \
          '{events: [{type: "user.custom_tool_result", custom_tool_use_id: $id, content: [{type: "text", text: $result}]}]}' |
          curl -sS --fail-with-body \
            "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
            -H "x-api-key: $ANTHROPIC_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "anthropic-beta: managed-agents-2026-04-01" \
            -H "content-type: application/json" \
            -d @-
      done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")
      ;;
    end_turn)
      break
      ;;
  esac
done
exec {fd}<&-

exec {fd}< <(curl -sS -N --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -H "Accept: text/event-stream")

while IFS= read -r -u "$fd" line; do
  [[ $line == data:* ]] || continue
  data="${line#data: }"
  [[ $(jq -r '.type' <<<"$data") == "session.status_idle" ]] || continue
  case $(jq -r '.stop_reason.type // empty' <<<"$data") in
    requires_action)
      while IFS= read -r event_id; do
        # Setujui panggilan alat yang tertunda
        jq -n --arg id "$event_id" \
          '{events: [{type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}]}' |
          curl -sS --fail-with-body \
            "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
            -H "x-api-key: $ANTHROPIC_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "anthropic-beta: managed-agents-2026-04-01" \
            -H "content-type: application/json" \
            -d @-
      done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")
      ;;
    end_turn)
      break
      ;;
  esac
done
exec {fd}<&-