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).

Serahkan pekerjaan ke agen lain

Agen yang dijalankan oleh sebuah sesi dapat menyerahkan pekerjaan ke agen lain dengan dua cara. Dengan subagents (subagen), agen mendelegasikan tugas sendiri dan membaca apa yang dilaporkan setiap subagen. Dengan dynamic workflows (alur kerja dinamis), agen menulis sebuah workflow: program yang menjalankan banyak agen di latar belakang dan menggabungkan hasilnya. Agen juga dapat berkonsultasi dengan model advisor (penasihat) untuk mendapatkan panduan sementara ia mengerjakan pekerjaannya sendiri.

Anda menentukan mana di antara ini yang dapat digunakan agen, dan agen menentukan kapan menggunakannya. Untuk memandu pilihan tersebut, beri tahu agen dalam prompt sistemnya kapan harus menggunakan eksekusi workflow. Lihat Beri tahu agen kapan menggunakan eksekusi. Anda juga dapat membatasi agen hanya pada agen-agen yang Anda cantumkan.

Dengan subagen, agen itu sendiri yang menentukan apa yang terjadi selanjutnya. Thread subagen tetap tersedia hingga Anda mengarsipkannya, sehingga agen dapat mengirimkan pesan lanjutan kepadanya. Dengan alur kerja dinamis, Claude menulis program untuk mengorkestrasi agen tanpa keterlibatan langsung Claude. Konteks dan hasil diteruskan secara terprogram dari satu agen ke agen lain, sehingga thread sesi utama bebas untuk berkomunikasi dengan pengguna dan memeriksa satu atau beberapa workflow yang sedang berjalan untuk melaporkan kemajuan. Agen tidak dapat mengirim pesan lanjutan ke thread milik sebuah eksekusi, dan server mengarsipkan masing-masing thread tersebut paling lambat saat eksekusinya berakhir.

Anda mengatur ini di blok multiagent pada definisi agen, yang memiliki sebuah type. Dengan tipe multiagent_20261001, sebuah agen dapat menggunakan ketiganya bersama-sama, dan Anda dapat mengaktifkan atau menonaktifkan masing-masing. Secara default, subagents dan workflows keduanya diaktifkan. subagents dan workflows masing-masing memiliki inline_agents yang diaktifkan, yaitu pengaturan untuk agen yang didefinisikan sendiri oleh agen atau workflow:

{
  "multiagent": { "type": "multiagent_20261001" }
}

Untuk mengatur agen mana yang dapat dipanggil oleh agen, lihat Agen predefined dan inline. Untuk menonaktifkan sebuah pengaturan, lihat Aktifkan alur kerja dinamis.

Agen predefined dan inline

Setiap subagen, dan setiap agen dalam sebuah eksekusi workflow, adalah salah satu dari dua jenis:

• Agen predefined (agen yang telah ditentukan sebelumnya): Agen yang sudah Anda buat, dan yang Anda cantumkan di blok multiagent. Agen ini menggunakan konfigurasinya sendiri: model, prompt sistem, alat, server MCP, dan skill.
• Agen inline: Agen yang tidak disimpan. Agen yang dijalankan sesi, atau sebuah workflow, mendefinisikannya saat membagikan pekerjaan. Agen ini menggunakan model, alat, server MCP, dan skill milik agen tersebut.

Kedua jenis berfungsi di bawah subagents dan di bawah workflows:

subagents.predefined_agents dan workflows.predefined_agents adalah dua daftar terpisah. Agen di satu daftar tidak ditambahkan ke daftar lainnya. Kedua daftar kosong secara default. Entri di salah satu daftar mengambil salah satu bentuk berikut:

• {"type": "agent", "id": agent.id} mereferensikan agent yang telah dibuat sebelumnya berdasarkan ID. Jika tidak ada version yang ditentukan, referensi disematkan ke versi terbaru agen saat agen yang mencantumkannya dibuat, atau saat sebuah pembaruan mengirimkan daftar tersebut.
• {"type": "agent", "id": agent.id, "version": agent.version} menyematkan versi agen tertentu.
• agent.id saja, sebagai string, adalah singkatan dari {"type": "agent", "id": agent.id}.
• {"type": "self"} mencantumkan agen itu sendiri, sehingga salinan dirinya dapat mengerjakan pekerjaan. Jika sesi dibuat dengan override konfigurasi agen, override tersebut juga berlaku untuk salinan-salinan ini. Entri yang direferensikan berdasarkan ID tidak terpengaruh.

Aturan untuk entri-entri ini, dan untuk agen yang disebutkannya, berlaku untuk kedua daftar. Lihat Cantumkan subagen.

Agen inline aktif secara default di bawah kedua pengaturan. Untuk hanya mengizinkan agen yang Anda cantumkan, atur inline_agents ke {"type": "disabled"} di bawah subagents, di bawah workflows, atau di bawah keduanya. Pengaturan dengan agen inline dinonaktifkan memerlukan setidaknya satu agen dalam daftar predefined_agents-nya. Dengan daftar kosong, permintaan gagal dengan error 400. Pada pembaruan, server memeriksa pengaturan sebagaimana adanya setelah pembaruan.

Agen berikut hanya mengizinkan agen yang dicantumkannya. Agen ini dapat mendelegasikan ke satu agen dan ke salinan dirinya sendiri, dan sebuah workflow dapat menggunakan versi 2 dari agen lain:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": ["agent_01J8XkN5uT3vHpLqRfWdY2", { "type": "self" }]
    },
    "workflows": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": [
        { "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h", "version": 2 }
      ]
    }
  }
}

Delegasikan ke subagen

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 agen menyintesis hasilnya.
• Spesialisasi: Rutekan ke agen dengan prompt sistem dan alat yang berfokus pada domain, seperti agen keamanan atau agen dokumentasi, alih-alih membebani satu agen dengan setiap kemampuan.
• Eskalasi: Konsultasikan dengan agen atau model yang lebih mampu untuk sebagian subtugas yang kompleks. Untuk berkonsultasi dengan model, berikan advisor pada sesi.

Cara kerjanya

Semua agen berbagi sandbox, sistem file, dan kredensial vault yang sama, tetapi setiap agen berjalan di session thread (thread sesi) miliknya sendiri, yaitu aliran event dengan konteks terisolasi yang memiliki riwayat percakapannya sendiri. Agen yang dijalankan sesi melaporkan aktivitas di primary thread (thread utama), yang merupakan aliran event tingkat sesi. Thread tambahan dibuat saat runtime ketika agen mendelegasikan pekerjaan. Sebuah eksekusi workflow juga membuat thread.

Thread subagen bersifat persisten. Agen dapat mengirim tindak lanjut ke subagen yang dipanggilnya sebelumnya, dan subagen tersebut mempertahankan semua hal dari giliran-giliran sebelumnya.

Konfigurasi mana yang digunakan subagen bergantung pada apakah ia merupakan agen predefined atau inline. Override konfigurasi agen tingkat sesi berlaku untuk agen yang dijalankan sesi dan untuk salinan self-nya. Setiap agen mempertahankan riwayat percakapannya sendiri.

Cantumkan subagen

Saat mendefinisikan agen Anda, atur daftar predefined_agents dari subagents di blok multiagent untuk mencantumkan agen-agen yang dapat menjadi tujuan delegasinya:

# Buat subagent, lalu baca ID-nya dari lockfile.
ant apply reviewer.md test-writer.md
REVIEWER_AGENT_ID=$(jq -er '.resources["./reviewer.md"].id' claude-lock.json)
TEST_WRITER_AGENT_ID=$(jq -er '.resources["./test-writer.md"].id' claude-lock.json)

# Tulis definisi agent, dengan mencantumkan setiap subagent berdasarkan ID.
cat > engineering-lead.md <<EOF
---
name: Engineering Lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents:
      - type: agent
        id: $REVIEWER_AGENT_ID
      - type: agent
        id: $TEST_WRITER_AGENT_ID
---

You coordinate engineering work. Delegate code review to the reviewer agent
and test writing to the test agent.
EOF

# Buat agent.
ant apply engineering-lead.md reviewer.md test-writer.md

---
name: reviewer
model: claude-haiku-5-5
---

You are a code reviewer.

---
name: test-writer
model: claude-haiku-5-5
---

You write unit tests.

Agen juga dapat mendelegasikan ke agen inline kecuali Anda menonaktifkannya. Untuk pengaturan tersebut, dan untuk bentuk-bentuk yang dapat diambil oleh entri daftar predefined_agents dari subagents, lihat Agen predefined dan inline.

"advisor": {"type": "enabled", "model": "<model id>"} memberikan thread utama sesi sebuah advisor yang dapat dikonsultasikan di tengah giliran. Advisor adalah pengaturan di blok multiagent, bukan entri dalam daftar ini. Lihat Berikan advisor pada sesi.

Alur kerja dinamis juga diaktifkan secara default dengan tipe ini, sehingga agen ini dapat merencanakan pekerjaan besar yang menjalankan banyak agen di latar belakang. Untuk menonaktifkannya, atau untuk mencantumkan agen yang dapat digunakan workflow, lihat Aktifkan alur kerja dinamis.

Aturan berikut berlaku untuk agen yang Anda cantumkan di daftar predefined_agents dari subagents, dan juga untuk agen yang Anda cantumkan di daftar predefined_agents dari workflows:

• Penyematan: Konfigurasi agen, termasuk daftar predefined_agents dari subagents, diambil snapshot-nya saat agen dibuat atau diperbarui. Agen yang direferensikan tetap disematkan ke versi yang diresolusi saat itu dan tidak mengambil pembaruan selanjutnya pada definisinya. Pembaruan yang tidak mengirimkan daftar tersebut mempertahankan versi yang sudah disematkan. Untuk mendelegasikan ke versi yang lebih baru dari agen yang direferensikan, perbarui agen sehingga daftar predefined_agents dari subagents mereferensikan versi tersebut.
• Satu tingkat: Agen hanya dapat mendelegasikan ke satu tingkat agen. Mereferensikan agen lain yang memiliki multiagent yang diatur akan menggagalkan permintaan pembuatan atau pembaruan dengan error validasi 400.
• Hingga 20 agen: Daftar predefined_agents dari subagents dapat mencantumkan hingga 20 agen unik. Batas ini berlaku per daftar: daftar predefined_agents dari workflows juga dapat mencantumkan hingga 20. Agen dapat memanggil beberapa salinan dari setiap subagen, dalam batas thread sesi.
• Geografi inferensi: Agen dan setiap agen yang Anda cantumkan, di daftar predefined_agents dari subagents atau dari workflows, harus menyematkan geografi inferensi yang sama (inference_geo di model pada definisi agen), atau tidak satu pun dari mereka boleh menyematkannya. Ketidakcocokan di salah satu daftar ditolak dengan error validasi 400. Pemeriksaan tersebut dijalankan baik saat agen disimpan maupun saat override pembuatan sesi mengubah salah satu sematan.

Buat sesi

Buat sesi yang mereferensikan agen. Agen mendelegasikan ke agen-agen yang Anda cantumkan di daftar predefined_agents dari subagents sesuai kebutuhan. Agen juga dapat mendelegasikan ke agen inline kecuali Anda menonaktifkannya.

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

Hubungkan agen ke server MCP

Server MCP memiliki cakupan per agen: setiap definisi agen mendeklarasikan server dan alatnya sendiri. Agen inline tidak memiliki definisi agen, sehingga menggunakan server MCP dan alat milik agen yang dijalankan sesi. 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 dibutuhkannya dalam definisi agennya. Anda tidak dapat membatasi agen inline dengan cara ini. Untuk hanya mengizinkan agen yang Anda cantumkan, nonaktifkan inline_agents di subagents dan workflows, dan cantumkan setidaknya satu agen di masing-masing. Lihat Agen predefined dan inline.

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

Dengan environment limited, pembuatan sesi gagal dengan error 400 ketika agen, atau agen yang Anda cantumkan di daftar predefined_agents dari subagents atau workflows, mendeklarasikan server MCP yang host-nya tidak ada di allowed_hosts. Mengatur allow_mcp_servers ke true di pengaturan jaringan environment akan menonaktifkan pemeriksaan ini.

Buat researcher, yang mendeklarasikan server MCP GitHub, dan agen yang mendelegasikan ke researcher:

# Buat researcher, lalu baca ID-nya dari lockfile.
ant apply researcher.md
research_agent_id=$(jq -er '.resources["./researcher.md"].id' claude-lock.json)

# Tulis definisi agen, dengan mencantumkan researcher berdasarkan ID.
cat > lead.md <<EOF
---
name: lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents:
      - type: agent
        id: $research_agent_id
---
EOF

# Buat agen.
ant apply lead.md researcher.md

---
name: researcher
model: claude-haiku-5-5
mcp_servers:
  - type: url
    name: github
    url: https://api.githubcopilot.com/mcp/
tools:
  - type: mcp_toolset
    mcp_server_name: github
---

Kemudian buat sesi dengan vault yang menyimpan kredensial GitHub:

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

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

Thread

Thread sesi setiap agen memiliki aliran event-nya sendiri. Untuk mencantumkan, menginterupsi, atau mengarsipkan thread, membaca event-nya, dan menangani izin alat di seluruh thread, lihat Thread sesi.

Alur kerja dinamis

Dengan alur kerja dinamis, sebuah agen dapat menangani pekerjaan dengan banyak bagian, seperti meninjau ratusan dokumen atau memeriksa silang banyak sumber. Agen menulis sebuah workflow (alur kerja): program yang menjalankan banyak agen dalam beberapa fase dan menggabungkan apa yang mereka kembalikan. Server menjalankannya di latar belakang sebagai workflow run (eksekusi workflow), sementara agen terus bekerja atau mengakhiri gilirannya. Anda mengaktifkan atau menonaktifkan alur kerja dinamis dengan pengaturan workflows di blok multiagent milik agen. Agen-agen dalam sebuah eksekusi dapat bekerja pada saat yang sama, sehingga tugas panjang dapat selesai lebih cepat dibandingkan jika satu agen mengerjakan setiap bagian secara bergiliran.

• Bagaimana eksekusi dimulai: Anda mendeskripsikan pekerjaan dalam sebuah user.message. Dari situ, agen menentukan apakah dan kapan memulai eksekusi, sehingga tidak ada panggilan API tambahan. Sebagai gantinya, Anda memengaruhi keputusan agen dengan mendeskripsikan kapan menggunakan eksekusi di user.message atau di prompt sistem agen. (Kebijakan izin berlaku untuk alat yang dipanggil oleh agen-agen dalam eksekusi, bukan untuk memulai eksekusi.)
• Agen mana yang digunakan: Agen inline yang didefinisikan workflow, agen predefined yang Anda cantumkan di daftar predefined_agents dari workflows, atau keduanya. Jika Anda tidak mencantumkan satu pun, workflow mendefinisikan semuanya. Agen inline menggunakan model milik agen yang dijalankan sesi. Agar sebuah eksekusi dapat menggunakan model lain untuk sebagian agennya, buat mereka sebagai agen dan cantumkan di daftar predefined_agents dari workflows.
• Cara Anda mengikutinya: Event eksekusi tiba di aliran event sesi, dan setiap agen dalam eksekusi bekerja di thread sesi yang dapat Anda cantumkan, baca, dan stream. Lihat Eksekusi workflow untuk event, interupsi, batas, dan apa yang ditampilkan thread milik sebuah eksekusi.

Aktifkan alur kerja dinamis

Saat mendefinisikan agen Anda, atur multiagent.type ke "multiagent_20261001" dan aktifkan workflows. Alur kerja dinamis dan pendelegasian (subagents) sama-sama aktif secara default dengan tipe ini. Untuk alur kerja dinamis saja, tambahkan "subagents": {"type": "disabled"}.

Sebelum Anda mengubah multiagent.type milik agen yang sudah ada, lihat cara memindahkan agen ke tipe ini.

ant apply contract-reviewer.md

---
name: Contract Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  workflows:
    type: enabled
---

You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.

Agar workflow dapat menggunakan agen yang sudah Anda buat, cantumkan agen-agen tersebut di workflows.predefined_agents. Pengaturan subagents dan advisor ditempatkan di blok multiagent yang sama. Untuk mencantumkan subagen, lihat Delegasikan ke subagen. Untuk mengatur advisor, lihat Berikan advisor pada sesi. Agen ini memungkinkan workflow menggunakan satu agen yang Anda buat, mencantumkan dua subagen, dan memiliki advisor:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "workflows": {
      "type": "enabled",
      "predefined_agents": [{ "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h" }]
    },
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}

Setiap pengaturan diaktifkan atau dinonaktifkan secara terpisah:

Untuk mengetahui apa yang dimasukkan ke setiap daftar, dan cara mengizinkan hanya agen yang Anda cantumkan, lihat Agen predefined dan inline.

Perhatikan hal-hal berikut:

• Pembaruan: Pembaruan yang mempertahankan tipe multiagent_20261001 hanya mengubah apa yang dikirimkannya:
  • Pengaturan atau field yang tidak Anda sertakan mempertahankan nilai tersimpannya.
  • Pengaturan atau field yang Anda kirim sebagai null mengambil nilai default-nya, begitu pula semua yang ada di dalamnya, apa pun yang telah Anda simpan.
  • Daftar predefined_agents yang Anda kirim menggantikan daftar yang tersimpan.
  • Pengaturan yang Anda kirim dengan type yang berbeda menggantikan pengaturan yang tersimpan, dan field yang tidak Anda sertakan di dalamnya mengambil nilai default-nya.
  • Setiap objek yang Anda kirim memerlukan type-nya, dan advisor yang aktif memerlukan model-nya.
• Menonaktifkannya: Atur workflows ke {"type": "disabled"}. Pengaturan ini tetap nonaktif hingga ada pembaruan yang mengaktifkannya kembali. Mengirim null akan mengaktifkannya, karena default-nya adalah aktif. Hal yang sama berlaku untuk subagents.
• Sesi yang sudah ada: Sesi menyalin pengaturan saat sesi dibuat, sehingga mengubah agen di kemudian hari tidak mengubah sesi yang sudah ada.
• Agen yang dapat Anda cantumkan: Agen yang memiliki multiagent yang diatur tidak dapat dicantumkan sebagai subagen dari agen lain, atau di daftar predefined_agents dari workflows di agen lain. Agen dapat mencantumkan dirinya sendiri di salah satu daftar dengan {"type": "self"}, yang terbaca kembali sebagai id dan version miliknya sendiri.
• Nama alat: Prefiks ant__ dicadangkan. Jika agen Anda sudah memiliki alat kustom yang namanya diawali dengan ant__, pembaruan akan gagal dengan error 400 hingga Anda mengirim tools tanpa nama tersebut. Sesi baru juga ditolak dengan error 400 jika agennya, atau agen di salah satu daftar, memiliki alat seperti itu. Ganti nama atau hapus alat tersebut dalam pembaruan yang sama yang mengaktifkan alur kerja dinamis. Lihat Alat kustom.
• Anggaran: Atur anggaran sesi saat Anda membuat sesi untuk membatasi pengeluaran sesi, termasuk eksekusi; Anda tidak dapat menambahkannya ke sesi yang sudah ada. Eksekusi dijeda saat sesi mencapai anggaran, dan eksekusi yang dijeda oleh anggaran akan dilanjutkan saat Anda menaikkan atau menghapusnya, kecuali jika interupsi juga menjedanya. Lihat Biaya dan anggaran.

Beri tahu agen kapan menggunakan eksekusi

Mengaktifkan alur kerja dinamis memberi agen kemampuan untuk memulai eksekusi workflow. Agen menentukan kapan harus memulainya. Untuk memandu pilihan tersebut, tambahkan instruksi seperti berikut ke prompt sistem agen. Agen peninjau kontrak di Aktifkan alur kerja dinamis menggunakan prompt sistem ini:

You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.

Untuk menyesuaikannya, sebutkan tugas-tugas dalam domain agen Anda yang memerlukan eksekusi, serta tugas-tugas kecil yang harus dikerjakan sendiri oleh agen. Anda juga dapat memandu cara eksekusi mengerjakan pekerjaan, seperti dalam contoh-contoh berikut:

• Cara membagi pekerjaan: "Dalam sebuah eksekusi, gunakan satu agen per kontrak. Kemudian minta agen kedua meninjau setiap kontrak, bukan hanya kontrak yang menurut agen pertama bermasalah, dan mencari apa yang terlewat oleh agen pertama. Apa pun yang gagal dalam peninjauan dikerjakan ulang dan ditinjau kembali."
• Apa yang harus dilakukan saat agen gagal: "Satu agen yang gagal tidak boleh membuat eksekusi gagal. Jika agen gagal membaca kontrak, cantumkan kontrak tersebut sebagai tidak tercakup. Saat eksekusi berakhir, beri tahu saya kontrak mana yang tidak tercakup."
• Batas waktu: "Berikan eksekusi batas waktu satu jam."
• Rencanakan terlebih dahulu: "Sebelum Anda memulai eksekusi, jelaskan fase-fasenya dan berapa banyak agen yang dijalankan di setiap fase. Kemudian tunggu persetujuan saya." Tidak ada langkah persetujuan sebelum eksekusi dimulai, sehingga tidak ada yang memberlakukan hal ini.

Batasi eksekusi hanya untuk tugas-tugas yang memerlukannya, karena setiap agen dalam eksekusi menggunakan token.

Kemudian buat sesi dengan agen tersebut, seperti yang Anda lakukan dengan agen mana pun, dan jelaskan pekerjaannya dalam user.message. Anda juga dapat meminta eksekusi dalam pesan tersebut.

Untuk event eksekusi, menginterupsi sesi dengan eksekusi yang masih terbuka, apa yang berubah selama eksekusi terbuka, serta anggaran dan batas, lihat Eksekusi workflow.

Berikan advisor pada sesi

Pengaturan advisor yang aktif di blok multiagent milik agen memberikan advisor pada thread utama sesi: model yang dapat dikonsultasikan di tengah giliran untuk panduan strategis, seperti merencanakan pendekatan, keluar dari kebuntuan, atau meninjau pekerjaan sebelum selesai. Pengaturan ini nonaktif secara default. Untuk mengaktifkannya, atur advisor ke {"type": "enabled", "model": "..."}, yang memiliki tepat dua field, type dan model:

ant apply backend-engineer.md

---
name: Backend engineer
model: claude-sonnet-5
multiagent:
  type: multiagent_20261001
  advisor:
    type: enabled
    model: claude-opus-5-5
---

You implement backend features end to end. Consult the advisor before major backend design decisions.

Contoh ini hanya mengatur advisor. Dua pengaturan lainnya, subagents dan workflows, mempertahankan nilai default-nya, sehingga keduanya aktif, dan agen juga dapat mendelegasikan ke agen inline serta memulai eksekusi workflow. Untuk agen yang berkonsultasi dengan advisor dan mengerjakan semua pekerjaan sendiri, atur keduanya ke {"type": "disabled"}.

Anda tidak dapat mencantumkan advisor di daftar predefined_agents dari subagents atau workflows. advisor yang aktif mencadangkan nama anthropic.advisor. Selama aktif, tidak ada daftar yang dapat memuat agen yang secara harfiah bernama anthropic.advisor: permintaan akan ditolak dengan error validasi 400.

Model advisor harus memenuhi batas kemampuan minimum, dan model milik agen itu sendiri tidak boleh lebih mampu daripada advisor-nya; model dengan kemampuan yang setara dapat dipasangkan. Pasangan yang tidak valid ditolak dengan error validasi 400 saat agen disimpan, dan sekali lagi saat sesi dibuat. Pasangan tersebut juga diperiksa saat setiap konsultasi dimulai: jika sudah tidak valid, konsultasi tersebut gagal dan sesi tetap berlanjut. Pasangan yang valid mengikuti tabel kompatibilitas model pada alat advisor.

Advisor juga tersedia sebagai alat server di Messages API. Permukaan Managed Agents berbeda dalam konfigurasi dan penyampaian: pengaturan advisor tidak memiliki field max_uses, max_tokens, atau caching, dan saran tiba melalui event thread, bukan melalui blok advisor_tool_result.

Cara kerja konsultasi

Setiap konsultasi berjalan sebagai thread yang dibuat oleh platform bernama anthropic.advisor yang menghentikan dirinya sendiri saat konsultasi selesai, dan saran disampaikan ke thread utama sebagai event agent.thread_message_received. Konsultasi memancarkan event thread standar, yang diidentifikasi dengan nama cadangan anthropic.advisor (event siklus hidup thread membawanya sebagai agent_name, dan penyampaian 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, bukan dikirim oleh agen. Jika Anda mencantumkan event milik thread advisor itu sendiri, saran juga muncul di sana sebagai event agent.thread_message_sent. Penyampaian saran (event 3) tidak dijamin tiba sebelum event idle dan terminated milik thread advisor, jadi jangan perlakukan event-event tersebut sebagai sinyal bahwa saran sudah disampaikan.

Apakah klien Anda dapat membaca saran bergantung pada kebijakan model advisor. Hal ini mencerminkan pembagian varian hasil pada alat advisor Messages API. Model advisor yang mengembalikan hasil plaintext di sana akan menyampaikan teks yang dapat dibaca di sini. Model yang mengembalikan hasil yang disunting (redacted) akan menyampaikan placeholder [{"type": "redacted"}] di setiap permukaan klien, sementara agen tetap membaca saran lengkap di sisi server. Contoh sebelumnya menggunakan model Opus terbaru yang tersedia bagi Anda sebagai advisor. Claude Opus 5.5 mengembalikan hasil yang disunting, sehingga klien Anda hanya melihat placeholder. Untuk membaca saran di aliran event, gunakan advisor yang mengembalikan plaintext, seperti Claude Opus 4.8. Kebijakan model dapat berubah tanpa perubahan pada API, jadi tangani blok text maupun redacted. Beberapa model agen hanya dapat dipasangkan dengan advisor yang mengembalikan hasil yang disunting; lihat tabel kompatibilitas alat advisor. Pemikiran advisor tidak pernah ditampilkan. Klien tidak dapat mengirim blok redacted sendiri; event yang memuatnya akan ditolak dengan error validasi 400.

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

Thread advisor

Advisor bukan subagen. Alat list_agents milik agen tidak menampilkannya, dan send_to_agent, yang mengirimkan pesan lanjutan ke subagen, tidak dapat menjangkaunya. Hanya thread utama sesi yang dapat berkonsultasi dengannya; subagen tidak dapat.

Thread advisor dikecualikan dari batas 25 thread anak. Thread ini muncul di daftar thread sesi. agent-nya berbentuk advisor, {"type": "advisor", "model": ...}, dengan model yang Anda konfigurasikan, dan parent_thread_id-nya adalah thread utama.

Caching prompt di sisi advisor berlangsung otomatis; tidak ada yang perlu dikonfigurasi. Konsultasi ditagih sesuai tarif model advisor, dan token-nya muncul di penggunaan thread advisor serta di total penggunaan sesi. Konsultasi juga dihitung terhadap anggaran sesi, dengan harga daftar model advisor. Setiap konsultasi mengirimkan percakapan thread utama sejauh ini kepada advisor, sehingga konsultasi di akhir sesi yang panjang menggunakan lebih banyak token input.

Menghapus advisor

Untuk menghapus advisor, perbarui agen dengan advisor diatur ke {"type": "disabled"}. Pada agen yang sudah memiliki tipe multiagent_20261001, pengaturan yang tidak disertakan dalam pembaruan mempertahankan nilai tersimpannya, sehingga Anda tidak perlu mengirim subagents atau workflows lagi. Dengan alasan yang sama, pembaruan yang tidak menyertakan advisor akan mempertahankan advisor. Sebelum Anda mengubah multiagent.type milik agen yang sudah ada, lihat cara memindahkan agen ke tipe ini.

Pindah dari tipe coordinator

Seperti multiagent_20261001, tipe coordinator memungkinkan agen mendelegasikan ke subagen yang Anda cantumkan dan berkonsultasi dengan model advisor. Dengan tipe coordinator, agen tidak dapat memulai eksekusi workflow atau mendefinisikan subagen sendiri. API menerima kedua tipe tersebut.

Untuk memindahkan agen ke multiagent_20261001, perbarui agen dengan blok multiagent bertipe tersebut:

1. Atur type ke "multiagent_20261001".
2. Cantumkan agen-agen yang dapat dipanggil oleh agen di subagents.predefined_agents. Entri-entrinya mempertahankan bentuk yang dimilikinya saat ini.
3. Jika agen memiliki advisor, atur advisor ke {"type": "enabled", "model": "..."} dengan model advisor tersebut.
4. Kirim seluruh blok dalam satu pembaruan.

Sebagai contoh, blok ini memberikan agen dua subagen dan satu advisor:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}

Blok tersebut tidak menyertakan workflows dan subagents.inline_agents, sehingga keduanya mengambil nilai default-nya dan aktif. Agen yang dipindahkan juga dapat memulai eksekusi workflow dan mendefinisikan subagen sendiri. Untuk menjaga salah satunya tetap nonaktif, atur ke {"type": "disabled"} dalam pembaruan yang sama. Lihat Aktifkan alur kerja dinamis dan Agen predefined dan inline.

Jika agen memiliki advisor dan tidak memiliki subagen, atur subagents ke {"type": "disabled"} untuk menjaga pendelegasian tetap nonaktif. Permintaan yang menonaktifkan subagents.inline_agents dan tidak mencantumkan agen apa pun akan gagal dengan error 400.

Pembaruan menggantikan seluruh blok multiagent, jadi kirim kembali daftar agen dan advisor, seperti yang dilakukan contoh tersebut. Apa yang tidak Anda sertakan akan mengambil nilai default-nya:

• subagents.predefined_agents: Daftarnya kosong, sehingga agen kehilangan subagen yang telah Anda cantumkan.
• advisor: Advisor dinonaktifkan.

Setelah agen memiliki tipe multiagent_20261001, pengaturan yang tidak disertakan dalam pembaruan berikutnya mempertahankan nilai tersimpannya.

Pembaruan tidak mengubah sesi yang sudah ada. Untuk menggunakan blok yang baru, buat sesi setelah pembaruan.