Orkestrasi multiagen

Orkestrasi multiagen memungkinkan satu agen berkoordinasi dengan agen lain untuk menyelesaikan pekerjaan yang kompleks. Agen dapat bertindak secara paralel dengan konteks terisolasi mereka sendiri, 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-nya sendiri, yaitu aliran peristiwa dengan konteks terisolasi yang memiliki riwayat percakapannya sendiri. Koordinator melaporkan aktivitas di primary thread (yang sama dengan aliran peristiwa 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. Penggantian konfigurasi agen tingkat sesi adalah pengecualian; penggantian 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 biarkan koordinator menyintesis hasilnya.
• Spesialisasi: Arahkan ke agen dengan prompt sistem dan alat yang berfokus pada domain, seperti agen keamanan atau agen dokumentasi, daripada membebani satu agen dengan semua kemampuan.
• Eskalasi: Konsultasikan agen atau model yang lebih mampu untuk sebagian subtugas yang kompleks.



Konfigurasikan koordinator

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

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-4-8
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
    - type: agent
      id: $TEST_WRITER_AGENT_ID
YAML

multiagent.agents dapat menerima salah satu dari berikut ini:

• {"type": "agent", "id": agent.id} mereferensikan agent yang telah dibuat sebelumnya berdasarkan ID. Jika tidak ada version yang ditentukan, referensi disematkan ke versi terbaru dari 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 penggantian konfigurasi agen, penggantian tersebut juga berlaku untuk salinan ini; entri daftar yang direferensikan berdasarkan ID tidak terpengaruh.

Konfigurasi koordinator, termasuk daftar 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 sehingga daftarnya mereferensikan versi tersebut.

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



Buat sesi

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

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



Hubungkan agen ke server MCP

Server MCP bercakupan agen (setiap definisi agen mendeklarasikan server dan alatnya sendiri), sedangkan kredensial vault bercakupan 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.

Penggantian 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-4-8",
    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 peristiwa 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 peristiwa 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.

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



Peristiwa primary thread

Peristiwa-peristiwa ini menampilkan aktivitas multiagen pada primary thread di /v1/sessions/{session_id}/events/stream. Peristiwa arah pesan dinamai relatif terhadap thread tempat peristiwa tersebut muncul di alirannya: 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 peristiwa agent.thread_message_received.



Peristiwa session thread

Peristiwa kritis diteruskan (proxy) ke primary thread. Namun, Anda mungkin masih ingin menyelidiki penalaran dan panggilan alat dari agen tertentu. Untuk melakukannya, lakukan streaming atau daftarkan peristiwa dari session thread yang terkait.

Setiap session thread memiliki aliran peristiwanya 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 menampilkan pratinjau thread yang sedang dibacanya: pratinjau thread anak tidak pernah muncul di aliran tingkat sesi, jadi untuk memantau subagen secara langsung, buka aliran thread-nya sendiri. Lihat Pratinjau peristiwa session thread untuk 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, peristiwa 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": ["toolu_01XYZ..."]
  }
}

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

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",
            }
        ],
    )