Orkestrasi multiagen

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

Tidak yakin apakah pengaturan multiagen cocok untuk masalah Anda? Lihat kapan menggunakan sistem multiagen (dan kapan tidak).

Cara kerjanya

Semua agen berbagi sandbox, filesystem, dan kredensial vault yang sama, tetapi setiap agen berjalan dalam session thread (thread sesi) miliknya sendiri, yaitu aliran event yang terisolasi konteksnya dengan riwayat percakapannya sendiri. Koordinator melaporkan aktivitas di primary thread (thread utama), yang sama dengan aliran event tingkat sesi; thread tambahan dibuat saat runtime ketika koordinator mendelegasikan pekerjaan.

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

Setiap agen menggunakan konfigurasinya sendiri: model, prompt sistem, alat, server MCP, dan skill. Override konfigurasi agen tingkat sesi adalah pengecualian; override tersebut berlaku untuk koordinator dan salinan self-nya. Alat, server MCP, dan konteks tidak dibagikan.

Apa yang perlu didelegasikan

Koordinasi multiagen paling cocok untuk tugas kompleks yang memerlukan pekerjaan di berbagai permukaan, atau di mana beberapa tugas dengan cakupan yang jelas berkontribusi pada tujuan keseluruhan.

Pola yang bekerja dengan baik:

• Paralelisasi: Sebarkan subtugas independen secara bersamaan (mencari di beberapa sumber, menganalisis file terpisah) dan minta koordinator mensintesis hasilnya.
• Spesialisasi: Arahkan ke agen dengan prompt sistem dan alat yang berfokus pada domain tertentu, seperti agen keamanan atau agen dokumentasi, daripada membebani satu agen dengan semua kemampuan.
• Eskalasi: Konsultasikan dengan agen atau model yang lebih mumpuni untuk sebagian subtugas yang kompleks.

Konfigurasikan koordinator

Saat mendefinisikan agen Anda, atur multiagent untuk mendeklarasikan daftar (roster) agen yang dapat didelegasikan oleh koordinator:

ant beta:agents create < coordinator.agent.yaml

name: Engineering Lead
model: claude-opus-5
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
multiagent:
  type: coordinator
  agents:
    - type: agent
      id: $REVIEWER_AGENT_ID # replace before running command
    - type: agent
      id: $TEST_WRITER_AGENT_ID # replace before running command

multiagent.agents dapat menerima salah satu dari berikut ini:

• {"type": "agent", "id": agent.id} mereferensikan agent yang telah dibuat sebelumnya berdasarkan ID. Jika version tidak ditentukan, referensi disematkan ke versi terbaru agen tersebut pada saat koordinator dibuat.
• {"type": "agent", "id": agent.id, "version": agent.version} menyematkan versi agen tertentu.
• {"type": "self"} memungkinkan koordinator membuat salinan dirinya sendiri. Jika sesi dibuat dengan override konfigurasi agen, override tersebut juga berlaku untuk salinan ini; entri roster yang direferensikan berdasarkan ID tidak terpengaruh.
• {"type": "advisor", "model": "<model id>"} memberikan primary thread sesi sebuah advisor yang dapat dikonsultasikan di tengah giliran. Maksimal satu entri advisor per roster. Lihat Berikan sesi sebuah advisor.

Konfigurasi koordinator, termasuk roster multiagent.agents-nya, di-snapshot saat koordinator dibuat atau diperbarui. Agen yang direferensikan tetap disematkan ke versi yang diselesaikan pada saat itu dan tidak secara otomatis mengambil pembaruan selanjutnya pada definisinya. Untuk mendelegasikan ke versi yang lebih baru dari agen yang direferensikan, perbarui koordinator agar roster-nya mereferensikan versi tersebut.

Koordinator hanya dapat mendelegasikan ke satu tingkat agen; mereferensikan agen yang memiliki roster multiagent.agents sendiri akan menggagalkan permintaan pembuatan atau pembaruan dengan kesalahan validasi. Maksimal 20 agen unik dapat dicantumkan dalam multiagent.agents, tetapi koordinator dapat memanggil beberapa salinan dari setiap agen.

Ketika agen menyematkan geografi inferensi (model.inference_geo dalam definisi agen), sematan koordinator dan sematan setiap anggota roster harus semuanya diatur ke nilai yang sama atau semuanya tidak diatur. Roster yang tidak cocok ditolak dengan kesalahan validasi 400, baik saat agen disimpan maupun saat override pembuatan sesi mengubah salah satu sematan tersebut.

Berikan sesi sebuah advisor

Entri advisor dalam multiagent.agents memberikan primary thread sesi sebuah advisor (penasihat): model yang dapat dikonsultasikan di tengah giliran untuk panduan strategis, seperti merencanakan pendekatan, keluar dari kebuntuan, atau meninjau pekerjaan sebelum selesai. Entri ini memiliki tepat dua field, type dan model:

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 '{
    "name": "Backend engineer",
    "model": "claude-sonnet-5",
    "system": "You implement backend features end to end. Consult the advisor before major backend design decisions.",
    "multiagent": {
      "type": "coordinator",
      "agents": [
        {"type": "advisor", "model": "claude-opus-5"}
      ]
    }
  }'

Sebuah roster dapat berisi maksimal satu entri advisor, bersama dengan bentuk roster lainnya. Entri ini menempati nama roster yang dicadangkan anthropic.advisor: roster yang mencantumkan entri advisor sekaligus anggota yang secara harfiah bernama anthropic.advisor ditolak dengan kesalahan validasi 400. Dalam respons, entri advisor ditampilkan terakhir dalam roster terlepas dari posisi saat dikirimkan.

Model advisor harus memenuhi batas kemampuan minimum, dan model agen itu sendiri tidak boleh lebih mumpuni daripada advisor-nya; model dengan kemampuan setara dapat dipasangkan. Pasangan yang tidak valid ditolak dengan kesalahan validasi 400 saat agen disimpan. Pasangan yang valid mengikuti tabel kompatibilitas model alat advisor.

Advisor juga tersedia sebagai alat server pada Messages API. Permukaan Managed Agents berbeda dalam konfigurasi dan pengiriman: entri roster tidak memiliki field max_uses, max_tokens, atau caching, dan saran tiba melalui event thread alih-alih blok advisor_tool_result.

Cara kerja konsultasi

Setiap konsultasi berjalan sebagai thread yang dibuat oleh platform bernama anthropic.advisor yang mengakhiri dirinya sendiri saat konsultasi selesai, dan saran dikirimkan ke primary thread sebagai event agent.thread_message_received. Sebuah konsultasi memancarkan event thread standar, yang diidentifikasi dengan nama cadangan anthropic.advisor (event siklus hidup thread membawanya sebagai agent_name, dan pengiriman saran membawanya sebagai from_agent_name), biasanya dalam urutan ini:

1. session.thread_created
2. session.thread_status_running
3. agent.thread_message_received (saran)
4. session.thread_status_idle (stop_reason: end_turn)
5. session.thread_status_terminated

Tidak ada event agent.tool_use yang dipancarkan untuk konsultasi, dan tidak ada event agent.thread_message_sent yang muncul di aliran event sesi, karena input konsultasi disusun oleh platform alih-alih dikirim oleh agen. Jika Anda mencantumkan event milik thread advisor itu sendiri, saran juga muncul di sana sebagai event agent.thread_message_sent. Pengiriman saran (event 3) tidak dijamin tiba sebelum event idle dan terminated dari thread advisor, jadi jangan perlakukan event tersebut sebagai sinyal bahwa saran sudah dikirimkan.

Apakah klien Anda dapat membaca saran tersebut bergantung pada kebijakan model advisor, dan ini mencerminkan pembagian varian hasil pada alat advisor Messages API. Model advisor yang mengembalikan hasil plaintext di sana mengirimkan saran sebagai konten teks yang dapat dibaca di sini; model advisor yang mengembalikan hasil yang disunting (redacted) di sana mengirimkan placeholder [{"type": "redacted"}] sebagai konten pesan di setiap permukaan klien, sementara agen itu sendiri tetap membaca saran lengkap di sisi server. Dalam contoh sebelumnya, Claude Opus 5 adalah advisor dengan hasil redacted, sehingga klien Anda melihat placeholder sementara agen membaca saran lengkap; pilih Claude Opus 4.8 sebagai advisor jika Anda ingin saran dapat dibaca di aliran event. Pemikiran advisor tidak pernah ditampilkan. Klien tidak dapat mengirim blok redacted sendiri; event yang berisi blok tersebut ditolak dengan kesalahan validasi 400.

Konsultasi yang gagal atau terinterupsi tidak pernah menggagalkan giliran agen: agen melanjutkan setelah pemberitahuan umum bahwa konsultasi gagal. user.interrupt tingkat sesi selama konsultasi mengakhiri thread advisor tanpa saran yang dikirimkan; user.interrupt dengan session_thread_id milik thread advisor hanya membatalkan konsultasi tersebut.

Thread advisor

Advisor bukan agen roster: ia tidak terlihat oleh alat list_agents koordinator, tidak dapat dikirimi pesan dengan send_to_agent, dan hanya primary thread sesi yang dapat berkonsultasi dengannya. Agen roster tidak dapat.

Thread advisor dikecualikan dari batas thread bersamaan. Thread ini muncul dalam daftar thread sesi dengan agent diatur ke bentuk advisor persis seperti yang dikonfigurasi ({"type": "advisor", "model": ...}) dan parent_thread_id diatur ke primary thread.

Caching prompt di sisi advisor bersifat otomatis; tidak ada yang perlu dikonfigurasi. Konsultasi ditagih dengan tarif model advisor, dan tokennya muncul dalam penggunaan thread advisor dan dalam total penggunaan sesi.

Menghapus advisor

Untuk menghapus advisor, perbarui agen dengan roster yang tidak lagi menyertakan entri advisor. Jika advisor adalah satu-satunya entri roster, kosongkan roster sepenuhnya dengan mengatur "multiagent": null.

Buat sesi

Buat sesi yang mereferensikan koordinator. Koordinator mendelegasikan ke agen dalam roster-nya sesuai kebutuhan.

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
)

Hubungkan agen ke server MCP

Server MCP memiliki cakupan agen (setiap definisi agen mendeklarasikan server dan alatnya sendiri), sedangkan kredensial vault memiliki cakupan sesi (vault_ids yang diteruskan saat pembuatan sesi berlaku untuk setiap thread). Dua implikasi untuk integrasi Anda:

• Untuk mengautentikasi server MCP, sertakan kredensial vault untuk setiap server MCP yang digunakan di semua agen.
• Untuk membatasi akses agen, deklarasikan hanya server yang dibutuhkannya dalam definisi agennya.

Override konfigurasi agen saat pembuatan sesi dapat menggantikan server MCP koordinator dan server MCP salinan self-nya.

research_agent = client.beta.agents.create(
    name="researcher",
    model="claude-haiku-4-5",
    mcp_servers=[
        {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}],
)

coordinator = client.beta.agents.create(
    name="coordinator",
    model="claude-opus-5",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [{"type": "agent", "id": research_agent.id}],
    },
)

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)
print(session.id)

Dalam contoh ini, hanya researcher yang mendeklarasikan server MCP GitHub, sehingga koordinator tidak memiliki akses. vault_ids sesi menyediakan kredensial GitHub ke thread researcher.

Thread

Aliran event tingkat sesi (/v1/sessions/{session_id}/events/stream) dianggap sebagai primary thread, yang berisi tampilan ringkas dari semua aktivitas di semua thread. Anda tidak melihat aktivitas lengkap dari subagen, tetapi Anda melihat awal dan akhir pekerjaan mereka, serta event yang memblokir seperti permintaan izin alat.

Session thread adalah tempat Anda menelusuri aktivitas agen tertentu.

status sesi adalah agregasi dari semua aktivitas agen; jika setidaknya satu thread berstatus running, maka status sesi keseluruhan juga running.

Anggaran sesi adalah satu batas bersama untuk semua thread dalam sesi. Saat batas tercapai, thread berhenti sementara secara independen, dan biaya setiap thread dihitung berdasarkan model yang dilayani oleh thread itu sendiri.

for thread in client.beta.sessions.threads.list(session.id):
    print(f"[{thread.agent.name}] {thread.status}")

Event primary thread

Event-event ini menampilkan aktivitas multiagen pada primary thread di /v1/sessions/{session_id}/events/stream. Event arah pesan dinamai relatif terhadap thread tempat event tersebut muncul: agent.thread_message_received berarti sebuah pesan tiba di thread ini dari thread lain, dan agent.thread_message_sent berarti thread ini mengirim pesan. Tugas yang didelegasikan koordinator, misalnya, tiba di aliran milik thread anak sebagai event agent.thread_message_received.

Konsultasi advisor memancarkan event thread yang sama ini dengan nama cadangan anthropic.advisor (sebagai agent_name pada event siklus hidup thread dan from_agent_name pada pengiriman saran); lihat Berikan sesi sebuah advisor untuk urutannya.

Event session thread

Event penting diproksikan ke primary thread. Namun, Anda mungkin masih ingin menyelidiki penalaran dan panggilan alat dari agen tertentu. Untuk melakukannya, lakukan streaming atau cantumkan event dari session thread yang terkait.

Setiap session thread memiliki aliran event sendiri di /v1/sessions/{session_id}/threads/{thread_id}/stream, dan menerima parameter event_deltas[] yang sama dengan aliran tingkat sesi, sehingga Anda dapat melihat pratinjau teks subagen saat model menghasilkannya. Sebuah koneksi hanya mempratinjau thread yang sedang dibacanya: pratinjau thread anak tidak pernah muncul di aliran tingkat sesi, jadi untuk memantau subagen secara langsung, buka aliran thread miliknya sendiri. Lihat Pratinjau event session thread untuk cara mengaktifkan, mengakumulasi, dan merekonsiliasi pratinjau.

with client.beta.sessions.threads.events.stream(
    thread.id,
    session_id=session.id,
) as stream:
    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.thread_status_idle":
                break

Izin alat dan alat kustom

Jika subagen membutuhkan sesuatu dari klien Anda, seperti izin untuk menjalankan alat always_ask, atau hasil dari alat kustom, event tersebut diposting silang ke primary thread dengan session_thread_id yang mengidentifikasi session thread asalnya.

{
  "type": "session.thread_status_idle",
  "id": "sevt_01ABC...",
  "session_thread_id": "sth_01DEF...",
  "agent_name": "code-reviewer",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["sevt_01XYZ..."]
  }
}

Posting user.tool_confirmation (dengan tool_use_id) atau user.custom_tool_result (dengan custom_tool_use_id); server merutekan respons ke thread yang benar secara otomatis.

Contoh berikut memperluas handler konfirmasi alat untuk merutekan balasan. Pola yang sama berlaku untuk user.custom_tool_result.

for event_id in stop.event_ids:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.tool_confirmation",
                "tool_use_id": event_id,
                "result": "allow",
            }
        ],
    )