Sesi multi-agen

Orkestrasi multi-agen 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.



Cara kerjanya

Semua agen berbagi sandbox, filesystem, dan kredensial vault yang sama, tetapi setiap agen berjalan di session thread (utas sesi) miliknya sendiri, yaitu aliran event dengan konteks terisolasi yang memiliki riwayat percakapan sendiri. Koordinator melaporkan aktivitas di primary thread (utas 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 telah dipanggil 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 sebaiknya didelegasikan

Koordinasi multi-agen paling cocok untuk tugas kompleks yang memerlukan pekerjaan di berbagai permukaan, atau ketika 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 menyintesis hasilnya.
• Spesialisasi: Arahkan ke agen dengan prompt sistem dan alat yang berfokus pada domain tertentu, seperti agen keamanan atau agen dokumentasi, alih-alih membebani satu agen dengan semua kemampuan.
• Eskalasi: Konsultasikan dengan agen atau model yang lebih mumpuni untuk sebagian subtugas yang kompleks.



Mengonfigurasi 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 version tidak ditentukan, referensi akan 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 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 di-resolve 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 daftarnya mereferensikan versi tersebut.

Koordinator hanya dapat mendelegasikan ke satu tingkat agen; kedalaman > 1 akan diabaikan. Maksimal 20 agen unik dapat dicantumkan dalam multiagent.agents, tetapi koordinator dapat memanggil beberapa salinan dari setiap agen.



Membuat sesi

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

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



Menghubungkan agen ke server MCP

Server MCP memiliki cakupan per agen (setiap definisi agen mendeklarasikan server dan alatnya sendiri), sedangkan kredensial vault memiliki cakupan per 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 dibutuhkan 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-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 milik researcher.



Thread

Aliran event tingkat sesi (/v1/sessions/:id/events/stream) dianggap sebagai primary thread, yang berisi tampilan ringkas dari semua aktivitas di seluruh 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 secara mendalam.

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



Event primary thread

Event berikut menampilkan aktivitas multi-agen pada primary thread di /v1/sessions/:id/events/stream.



Event session thread

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



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 di-cross-post ke primary thread dengan session_thread_id yang mengidentifikasi session thread asal.

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