Sesi multiagen

Multiagen adalah fitur Research Preview. Minta akses untuk mencobanya.

Orkestrasi multi-agen memungkinkan satu agen berkoordinasi dengan agen lain untuk menyelesaikan pekerjaan yang kompleks. Agen dapat bekerja secara paralel dengan konteks terisolasi masing-masing, yang membantu meningkatkan kualitas output dan mempercepat waktu penyelesaian.

Semua permintaan Managed Agents API memerlukan header beta managed-agents-2026-04-01. Header beta tambahan diperlukan untuk fitur research preview. SDK menetapkan header beta ini secara otomatis.

Cara kerjanya

Semua agen berbagi container dan filesystem yang sama, tetapi setiap agen berjalan dalam thread sesinya sendiri, yaitu aliran event yang terisolasi konteksnya dengan riwayat percakapan tersendiri. Koordinator melaporkan aktivitas di thread utama (yang sama dengan aliran event tingkat sesi); thread tambahan dibuat saat runtime ketika koordinator memutuskan untuk mendelegasikan.

Thread bersifat persisten: koordinator dapat mengirim tindak lanjut ke agen yang dipanggilnya sebelumnya, dan agen tersebut menyimpan semua informasi dari giliran sebelumnya.

Setiap agen menggunakan konfigurasinya sendiri (model, system prompt, tools, server MCP, dan skill) sebagaimana didefinisikan saat agen tersebut dibuat. Tools dan konteks tidak dibagikan.

Apa yang perlu didelegasikan

Sesi multiagen bekerja paling baik ketika ada beberapa tugas yang terdefinisi dengan baik dan terspesialisasi dalam tujuan keseluruhan:

Tinjauan kode: Agen peninjau dengan system prompt yang terfokus dan tools hanya-baca.
Pembuatan pengujian: Agen pengujian yang menulis dan menjalankan pengujian tanpa menyentuh kode produksi.
Riset: Agen pencarian dengan tools web yang merangkum temuan kembali ke koordinator.

Deklarasikan agen yang dapat dipanggil

Saat mendefinisikan agen Anda, cantumkan ID tambahan dari agen yang diizinkan untuk dipanggil:

Setiap entri dalam callable_agents harus berupa ID dari agen yang sudah ada. Hanya satu tingkat delegasi yang didukung: koordinator dapat memanggil agen lain, tetapi agen-agen tersebut tidak dapat memanggil agen milik mereka sendiri.

Kemudian buat sesi yang merujuk ke orkestrator:

Agen yang dapat dipanggil diselesaikan dari konfigurasi orkestrator. Anda tidak perlu merujuknya saat pembuatan sesi.

Thread sesi

Aliran event tingkat sesi (/v1/sessions/:id/stream) dianggap sebagai thread utama, yang berisi tampilan ringkas dari semua aktivitas di semua thread. Anda tidak akan melihat jejak individual agen yang dipanggil, tetapi Anda akan melihat awal dan akhir pekerjaan mereka. Thread sesi adalah tempat Anda menelusuri lebih dalam penalaran dan pemanggilan tool agen tertentu.

Status sesi juga merupakan agregasi dari semua aktivitas agen; jika setidaknya satu thread berstatus running, maka status sesi keseluruhan juga akan menjadi running.

Daftarkan semua thread dalam sesi sebagai berikut:

Stream event dari thread tertentu:

Daftarkan event masa lalu untuk sebuah thread:

Tipe event multiagen

Event-event ini menampilkan aktivitas multiagen pada aliran sesi tingkat atas.

Tipe	Deskripsi
`session.thread_created`	Koordinator membuat thread baru. Menyertakan `session_thread_id` dan `model`.
`session.thread_idle`	Thread agen menyelesaikan pekerjaan saat ini.
`agent.thread_message_sent`	Agen mengirim pesan ke thread lain. Menyertakan `to_thread_id` dan `content`.
`agent.thread_message_received`	Agen menerima pesan dari thread lain. Menyertakan `from_thread_id` dan `content`.

Izin tool dan tool kustom dalam thread

Ketika thread callable_agent membutuhkan sesuatu dari klien Anda (izin untuk menjalankan tool always_ask, atau hasil dari tool kustom) permintaan tersebut muncul di aliran sesi dengan field session_thread_id. Sertakan session_thread_id yang sama saat Anda memposting respons agar platform mengarahkannya kembali ke thread yang menunggu.

session_thread_id ada: event berasal dari thread subagen. Sertakan kembali dalam balasan Anda.
session_thread_id tidak ada: event berasal dari thread utama. Balas tanpa field tersebut.
Cocokkan tool_use_id untuk memasangkan permintaan dengan respons.

Contoh di bawah ini memperluas penangan konfirmasi tool untuk merutekan balasan. Pola yang sama berlaku untuk user.custom_tool_result.

orchestrator=$(curl -fsS https://api.anthropic.com/v1/agents \
  -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 @- <<EOF
{
  "name": "Engineering Lead",
  "model": "claude-sonnet-4-6",
  "system": "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ],
  "callable_agents": [
    {"type": "agent", "id": "$REVIEWER_AGENT_ID", "version": $REVIEWER_AGENT_VERSION},
    {"type": "agent", "id": "$TEST_WRITER_AGENT_ID", "version": $TEST_WRITER_AGENT_VERSION}
  ]
}
EOF
)

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -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 '{"agent": "'$ORCHESTRATOR_ID'", "environment_id": "'$ENVIRONMENT_ID'"}')

curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "[\(.agent_name)] \(.status)"'

curl -fsSN "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" |
  while IFS= read -r line; do
    [[ $line == data:* ]] || continue
    json=${line#data: }
    case $(jq -r '.type' <<<"$json") in
      agent.message)
        printf '%s' "$(jq -j '.content[] | select(.type == "text") | .text' <<<"$json")"
        ;;
      session.thread_idle)
        break
        ;;
    esac
  done

curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "[\(.type)] \(.processed_at)"'

while IFS= read -r event_id; do
  pending=$(jq -r --arg id "$event_id" '.[$id]' <<<"$events_by_id")
  thread_id=$(jq -r '.session_thread_id // empty' <<<"$pending")
  jq -n --arg id "$event_id" --arg thread "$thread_id" '
    {events: [
      {type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}
      + (if $thread != "" then {session_thread_id: $thread} else {} end)
    ]}' |
    curl -fsS "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")