Sesi multiagen

Orkestrasi multi-agen memungkinkan satu agen untuk 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 mempercepat waktu penyelesaian.

Cara kerjanya

Semua agen berbagi kontainer dan sistem file yang sama, tetapi setiap agen berjalan di thread sesinya sendiri, aliran peristiwa yang terisolasi konteks dengan riwayat percakapan tersendiri. Koordinator melaporkan aktivitas di thread utama (yang sama dengan aliran peristiwa tingkat sesi); thread tambahan dihasilkan saat runtime ketika koordinator memutuskan untuk mendelegasikan.

Thread bersifat persisten: koordinator dapat mengirim tindak lanjut kepada agen yang dipanggilnya sebelumnya, dan agen itu mempertahankan semuanya dari putaran sebelumnya.

Setiap agen menggunakan konfigurasi sendiri (model, system prompt, tools, server MCP, dan skills) seperti yang ditentukan saat agen itu dibuat. Tools dan konteks tidak dibagikan.

Apa yang harus didelegasikan

Sesi multiagen bekerja paling baik ketika ada beberapa tugas khusus dan terspesialisasi dalam tujuan keseluruhan:

• Tinjauan kode: Agen reviewer dengan system prompt yang terfokus dan tools read-only.
• Pembuatan tes: Agen tes yang menulis dan menjalankan tes tanpa menyentuh kode produksi.
• Penelitian: Agen pencarian dengan web tools yang merangkum temuan kembali ke koordinator.

Deklarasikan agen yang dapat dipanggil

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

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-4-7
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
YAML

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

Kemudian buat sesi yang mereferensikan orchestrator:

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

Agen yang dapat dipanggil diselesaikan dari konfigurasi orchestrator. Anda tidak perlu mereferensikannya saat pembuatan sesi.

Thread sesi

Aliran peristiwa tingkat sesi (/v1/sessions/:id/stream) dianggap sebagai thread utama, 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 menggali lebih dalam ke dalam penalaran dan pemanggilan tool agen tertentu.

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

Daftarkan semua thread dalam sesi sebagai berikut:

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

Streaming peristiwa dari thread tertentu:

with client.beta.sessions.threads.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_idle":
                break

Daftarkan peristiwa masa lalu untuk thread:

for event in client.beta.sessions.threads.events.list(
    thread.id,
    session_id=session.id,
):
    print(f"[{event.type}] {event.processed_at}")

Jenis peristiwa multiagen

Peristiwa ini menampilkan aktivitas multiagen pada aliran sesi tingkat atas.

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 muncul di aliran sesi dengan bidang session_thread_id. Sertakan session_thread_id yang sama saat Anda memposting respons Anda sehingga platform merutekannya kembali ke thread yang menunggu.

• session_thread_id ada: peristiwa berasal dari thread subagen. Ulangi pada balasan Anda.
• session_thread_id tidak ada: peristiwa berasal dari thread utama. Balas tanpa bidang.
• Cocokkan pada tool_use_id untuk memasangkan permintaan dengan respons.

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

for event_id in stop.event_ids:
    pending = events_by_id[event_id]
    confirmation = {
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,
        "result": "allow",
    }
    # Echo session_thread_id when the request came from a subagent thread
    if pending.session_thread_id is not None:
        confirmation["session_thread_id"] = pending.session_thread_id
    client.beta.sessions.events.send(session.id, events=[confirmation])