Alat advisor

Alat advisor memungkinkan model eksekutor yang lebih cepat dan lebih murah untuk berkonsultasi dengan model advisor berkecerdasan lebih tinggi di tengah proses generasi guna mendapatkan panduan strategis. Advisor membaca seluruh percakapan, menghasilkan rencana atau koreksi arah, dan eksekutor melanjutkan tugasnya.

Pola ini cocok untuk beban kerja agentik berjangka panjang (agen coding, computer use, pipeline riset multilangkah) di mana sebagian besar giliran bersifat mekanis tetapi memiliki rencana yang sangat baik adalah hal yang krusial. Anda mendapatkan kualitas yang mendekati advisor-saja sementara sebagian besar generasi token terjadi dengan tarif model eksekutor. Untuk hasil terukur, termasuk bagaimana manfaatnya menyusut seiring kemampuan eksekutor sendiri mendekati kemampuan advisor, lihat Mengoptimalkan biaya dan kecerdasan.



Kapan menggunakannya

Advisor cocok untuk konfigurasi berikut:

• Anda saat ini menggunakan Sonnet untuk tugas kompleks: Tambahkan advisor dengan tingkat lebih tinggi. Opus menjaga total biaya tetap serupa atau lebih rendah; Claude Fable 5 memaksimalkan peningkatan kualitas.
• Anda saat ini menggunakan Haiku dan ingin peningkatan kecerdasan: Tambahkan advisor Opus atau Fable. Perkirakan biaya lebih tinggi daripada Haiku saja, tetapi lebih rendah daripada mengganti eksekutor ke model yang lebih besar.

Hasilnya bergantung pada tugas. Evaluasi pada beban kerja Anda sendiri.

Advisor kurang cocok untuk tanya jawab satu giliran (tidak ada yang perlu direncanakan), pemilih model pass-through murni di mana pengguna Anda sudah memilih sendiri tradeoff biaya dan kualitas mereka, atau beban kerja di mana setiap giliran benar-benar memerlukan kemampuan penuh model advisor.



Mulai cepat

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-5",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Build a concurrent worker pool in Go with graceful shutdown.",
        }
    ],
)

print(response)

content respons menyertakan blok advisor_tool_result yang membawa panduan dari advisor. Dengan claude-opus-5 sebagai advisor, seperti dalam mulai cepat ini, field content pada blok tersebut adalah varian advisor_redacted_result (terenkripsi; eksekutor membacanya di sisi server, tetapi klien Anda tidak). Untuk melihat teks saran secara langsung dalam respons Anda, gunakan claude-opus-4-8 sebagai model advisor, yang mengembalikan varian advisor_result berupa plaintext. Lihat Varian hasil untuk kedua bentuk secara berdampingan dan model advisor mana yang mengembalikan varian mana, serta Kompatibilitas model untuk daftar lengkap pasangan yang valid.



Cara kerjanya

Saat Anda menambahkan alat advisor ke array tools Anda, model eksekutor menentukan kapan memanggilnya, seperti alat lainnya. Ketika eksekutor memanggil advisor:

1. Eksekutor mengeluarkan blok server_tool_use dengan name: "advisor" dan input kosong. Eksekutor memberi sinyal waktu, dan server menyediakan konteks.
2. Anthropic menjalankan proses inferensi terpisah pada model advisor di sisi server. Advisor berjalan di bawah prompt sistem miliknya sendiri yang disediakan Anthropic dan menerima transkrip lengkap eksekutor sebagai konteks kutipan dalam inputnya. Transkrip tersebut mencakup prompt sistem Anda, definisi alat, giliran sebelumnya dan hasil alat, serta teks yang telah dihasilkan eksekutor sejauh ini dalam giliran ini.
3. Respons advisor dikembalikan ke eksekutor sebagai blok advisor_tool_result.
4. Eksekutor melanjutkan generasi, dengan informasi dari saran tersebut.

Semua ini terjadi di dalam satu permintaan /v1/messages, tanpa round trip tambahan di sisi Anda. Pengecualiannya adalah giliran yang berhenti sejenak di tengah panggilan, yang Anda lanjutkan dengan permintaan lanjutan (lihat Melanjutkan giliran yang dijeda).

Advisor itu sendiri berjalan tanpa alat dan tanpa manajemen konteks. Blok thinking-nya dibuang sebelum hasil dikembalikan. Hanya teks saran yang sampai ke eksekutor.



Parameter alat

Objek caching memiliki bentuk {"type": "ephemeral", "ttl": "5m" | "1h"}. Berbeda dengan cache_control pada blok konten, ini bukan penanda breakpoint. Ini adalah sakelar aktif/nonaktif. Server menentukan di mana batas cache ditempatkan.

Alat advisor juga menerima properti generik yang tersedia pada definisi alat apa pun: cache_control, allowed_callers, defer_loading, dan strict (dibahas dalam output terstruktur). Lihat Referensi alat untuk semantiknya.



Struktur respons



Panggilan advisor yang berhasil

Ketika advisor dipanggil, blok server_tool_use diikuti oleh blok advisor_tool_result dalam konten asisten. Contoh berikut menunjukkan varian advisor_result plaintext yang dikembalikan oleh advisor Claude Opus 4.8. Mulai cepat menggunakan Claude Opus 5, yang mengembalikan varian advisor_redacted_result terenkripsi; lihat Varian hasil untuk kedua bentuk secara berdampingan.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me consult the advisor on this."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "advisor",
      "input": {}
    },
    {
      "type": "advisor_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "advisor_result",
        "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
      }
    },
    {
      "type": "text",
      "text": "Here's the implementation. I'm using a channel-based coordination pattern to avoid writer starvation..."
    }
  ]
}

server_tool_use.input selalu kosong. Server menyusun tampilan advisor dari transkrip lengkap secara otomatis. Tidak ada yang dimasukkan eksekutor ke dalam input yang sampai ke advisor.



Varian hasil

Field advisor_tool_result.content adalah discriminated union. Untuk panggilan yang berhasil, variannya bergantung pada model advisor:

Berikut adalah permintaan yang sama dikirim dua kali, identik kecuali model advisor dalam definisi alat, yang menunjukkan kedua varian.

Dengan "model": "claude-opus-4-8", sarannya berupa plaintext:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_result",
    "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
  }
}

Dengan "model": "claude-opus-5", sarannya terenkripsi:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
  }
}

Kedua varian hasil membawa field stop_reason ketika Anda menetapkan max_tokens pada definisi alat, dan menghilangkannya ketika Anda tidak menetapkannya. Field ini berisi stop reason dari sub-panggilan advisor, biasanya "end_turn", atau "max_tokens" ketika batas tercapai. Nilainya sesuai dengan stop_reason tingkat atas Messages API.

Dengan advisor_result, field text berisi saran yang dapat dibaca manusia. Dengan advisor_redacted_result, field encrypted_content berisi blob buram yang tidak dapat Anda baca. Pada giliran berikutnya, server mendekripsinya dan merender plaintext ke dalam prompt eksekutor.

Dalam kedua kasus, kirim kembali konten tersebut apa adanya pada giliran berikutnya. Jika Anda mengganti model advisor di tengah percakapan, lakukan percabangan berdasarkan content.type untuk menangani kedua bentuk.



Hasil error

Jika panggilan advisor gagal, hasilnya membawa error:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_tool_result_error",
    "error_code": "overloaded"
  }
}

Eksekutor melihat error tersebut dan melanjutkan tanpa saran lebih lanjut. Permintaan itu sendiri tidak gagal.

"Rate limit" (batas laju) advisor diambil dari bucket per model yang sama dengan panggilan langsung ke model advisor. Batas laju pada advisor muncul sebagai too_many_requests di dalam hasil alat. Batas laju pada eksekutor menggagalkan seluruh permintaan dengan HTTP 429.



Percakapan multi-giliran

Kirimkan konten asisten lengkap, termasuk blok advisor_tool_result, kembali ke API pada giliran berikutnya. Kirim kembali blok hasil apa adanya: dengan advisor Claude Opus 5, content blok hasil adalah varian advisor_redacted_result terenkripsi, dan server mendekripsinya serta merender saran ke dalam prompt eksekutor pada giliran berikutnya (lihat Varian hasil). Mekanismenya identik untuk model advisor apa pun.

client = anthropic.Anthropic()

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
    }
]

messages = [
    {
        "role": "user",
        "content": "Build a concurrent worker pool in Go with graceful shutdown.",
    }
]

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Tambahkan seluruh konten respons, termasuk blok advisor_tool_result apa pun
messages.append({"role": "assistant", "content": response.content})

# Lanjutkan percakapan
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

Anda dapat menghapus alat advisor dari tools pada giliran lanjutan sementara riwayat pesan masih berisi blok advisor_tool_result. Permintaan diterima dan blok historis dipertahankan; model tidak dapat memanggil advisor pada giliran tersebut. Anda tetap harus mengirim header beta advisor-tool-2026-03-01 agar blok riwayat tersebut diterima.



Melanjutkan giliran yang dijeda

Sebuah respons dapat berakhir dengan stop_reason: "pause_turn" sementara panggilan advisor masih tertunda. Ketika itu terjadi, respons berisi blok server_tool_use advisor tanpa advisor_tool_result untuknya. Untuk melanjutkan, tambahkan pesan asisten tersebut ke messages dengan kontennya tidak diubah, pertahankan blok server_tool_use, dan kirim permintaan lagi dengan alat advisor dan header beta yang sama. Anda tidak perlu menambahkan pesan pengguna atau blok tool_result. API menjalankan panggilan advisor yang tertunda dan melanjutkan giliran eksekutor dalam respons baru. Giliran yang dilanjutkan dapat dijeda lagi. Jika demikian, ulangi langkah yang sama. Menghilangkan alat advisor dari permintaan lanjutan mengembalikan 400 invalid_request_error, karena blok server_tool_use yang tertunda tidak memiliki definisi alat untuk dijalankan; sertakan alat tersebut setiap kali ada panggilan yang tertunda. Jika sebaliknya eksekutor memanggil salah satu alat Anda dalam giliran yang sama, respons berakhir dengan stop_reason: "tool_use" sementara panggilan advisor masih tertunda. Kirim blok tool_result seperti biasa, dan panggilan advisor yang tertunda berjalan di awal permintaan berikutnya. Lihat Mencampur alat server dan alat klien dalam satu giliran.



Dorongan di tengah percakapan untuk eksekutor yang kurang memanggil

Jika eksekutor Haiku belum memanggil advisor pada giliran asisten pertamanya, tambahkan pengingat singkat sebagai pesan pengguna tambahan sebelum giliran asisten kedua. Dalam evaluasi perilaku internal Anthropic, ini meningkatkan tingkat kelulusan tugas sekitar 7 poin persentase pada eksekutor Haiku. Pada eksekutor Sonnet, dorongan teks biasa tidak memiliki efek terukur dalam pengujian Anthropic. Pertimbangan waktu pemanggilan berikut ini sangat relevan untuk Sonnet. Jangan terapkan dorongan ini pada eksekutor Opus: Pada Opus, ini sedikit menurunkan tingkat kelulusan.

Dengan NUDGE_TURN default sebesar 2, pengingat biasanya tiba setelah model memahami tugas tetapi sebelum berkomitmen pada suatu pendekatan.

client = anthropic.Anthropic()

NUDGE_TURN = 2  # inject before this assistant turn if no advisor call yet
NUDGE_TEXT = (
    "You have not consulted the advisor yet. If the task has a non-obvious "
    "design decision or a failure mode you haven't ruled out, call advisor "
    "now before committing to an approach."
)
MAX_TURNS = 10  # agent loop cap


def run_your_tools(content):
    # Ganti dengan dispatch alat Anda. Mengembalikan satu blok tool_result per blok tool_use.
    return [
        {
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": "Replace with your tool output.",
        }
        for block in content
        if block.type == "tool_use"
    ]


tools = [
    {"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-5"},
    # ... alat Anda yang lain
]
task = "Build a concurrent worker pool in Go with graceful shutdown."
messages = [{"role": "user", "content": task}]
advisor_called = False

for turn in range(1, MAX_TURNS + 1):
    response = client.beta.messages.create(
        model="claude-haiku-4-5",
        max_tokens=4096,
        betas=["advisor-tool-2026-03-01"],
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": response.content})
    advisor_called = advisor_called or any(
        block.type == "server_tool_use" and block.name == "advisor"
        for block in response.content
    )
    if response.stop_reason == "end_turn":
        break
    if response.stop_reason == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it

    results = run_your_tools(response.content)  # list of tool_result blocks
    if results:
        messages.append({"role": "user", "content": results})
    # Lewati ini jika prompt sistem Anda sudah menginstruksikan model untuk memanggil dengan hemat.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

Tambahkan dorongan sebagai pesan pengguna tersendiri setelah hasil alat, bukan sebagai blok saudara dalam pesan yang sama. Pesan pengguna berturut-turut adalah valid. Dalam pengujian Anthropic pada eksekutor Haiku dan Sonnet, keduanya berperilaku setara dengan blok saudara. Bentuk pesan terpisah juga menjaga pengingat tetap jelas terpisah dari output alat.

Trade-off: Dorongan meningkatkan tingkat pemanggilan, yang dapat mendorong tugas yang sangat sederhana ke konsultasi yang tidak perlu. Jika beban kerja Anda mencampur tugas sederhana dan kompleks, pertimbangkan untuk menaikkan NUDGE_TURN ke 3 agar tugas dua giliran selesai sebelum dorongan dipicu, atau batasi dorongan berdasarkan sinyal kompleksitas tugas yang sudah Anda hitung. Jika prompt sistem Anda sudah berisi bahasa pengekangan ("simpan advisor untuk ketidakpastian yang sesungguhnya"), lewati dorongan sepenuhnya, karena kedua instruksi tersebut bertentangan.

Dorongan teks biasa sangat menonjol pada eksekutor Haiku dan Sonnet: 74 persen (Sonnet) hingga 98 persen (Haiku) dari percobaan yang diberi dorongan dalam pengujian Anthropic langsung memanggil advisor pada giliran 2. Jika itu terjadi sebelum eksekutor Anda membaca masalah atau mengumpulkan konteks, panggilan advisor yang dihasilkan memiliki konteks rendah dan dapat menggeser panggilan berikutnya yang waktunya lebih tepat. Ukur giliran panggilan pertama baseline eksekutor Anda sebelum menambahkan dorongan. Jika eksekutor sudah memanggil advisor secara andal dan panggilan pertamanya biasanya terjadi pada giliran N, tetapkan NUDGE_TURN lebih besar dari N. Dalam pengujian Anthropic, dorongan giliran-2 pada beban kerja di mana panggilan pertama baseline adalah giliran 7 atau lebih berkorelasi dengan penurunan kinerja tugas 3 hingga 4 poin persentase. Pada beban kerja browse di mana tingkat pemanggilan baseline adalah 86 persen, dorongan yang sama meningkatkan keterlibatan tanpa biaya kinerja tugas.

Untuk memaksa konsultasi pada permintaan tertentu alih-alih memberi dorongan, tetapkan tool_choice ke {"type": "tool", "name": "advisor"}, dengan tunduk pada batasan dalam Memaksa penggunaan alat. Memaksa penggunaan alat tidak dapat digabungkan dengan "extended thinking" (pemikiran diperpanjang) manual (thinking: {type: "enabled"}): API mengembalikan 400 invalid_request_error jika Anda mengaktifkan keduanya. Adaptive thinking mendukung penggunaan alat yang dipaksa.



Streaming

Sub-inferensi advisor tidak melakukan streaming. Stream eksekutor berhenti sejenak saat advisor berjalan; kemudian hasil lengkap tiba dalam satu event.

Blok server_tool_use dengan name: "advisor" menandakan bahwa panggilan advisor sedang dimulai. Jeda dimulai ketika blok tersebut ditutup (content_block_stop). Selama jeda, stream diam kecuali keepalive ping SSE standar yang dikeluarkan kira-kira setiap 30 detik. Panggilan advisor yang singkat mungkin tidak menampilkan ping.

Ketika advisor selesai, advisor_tool_result tiba dalam bentuk lengkap dalam satu event content_block_start (tanpa delta). Output eksekutor kemudian melanjutkan streaming.

Event message_delta menyusul dengan array usage.iterations yang diperbarui yang mencerminkan jumlah token advisor.



Penggunaan dan penagihan

Panggilan advisor berjalan sebagai sub-inferensi terpisah yang ditagih dengan tarif model advisor. Penggunaan dilaporkan dalam array usage.iterations[]:

{
  "usage": {
    "input_tokens": 1760,
    "cache_read_input_tokens": 412,
    "cache_creation_input_tokens": 0,
    "output_tokens": 531,
    "iterations": [
      {
        "type": "message",
        "input_tokens": 412,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 89
      },
      {
        "type": "advisor_message",
        "model": "claude-opus-5",
        "input_tokens": 823,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 1612
      },
      {
        "type": "message",
        "input_tokens": 1348,
        "cache_read_input_tokens": 412,
        "cache_creation_input_tokens": 0,
        "output_tokens": 442
      }
    ]
  }
}

Field usage tingkat atas hanya mencerminkan token eksekutor. Token advisor tidak digabungkan ke dalam total tingkat atas karena ditagih dengan tarif berbeda. Iterasi dengan type: "advisor_message" ditagih dengan tarif model advisor, dan iterasi dengan type: "message" ditagih dengan tarif model eksekutor.

Setiap field usage tingkat atas adalah jumlah field tersebut di seluruh iterasi eksekutor, termasuk input_tokens, output_tokens, dan cache_read_input_tokens. Karena setiap iterasi eksekutor mengirim ulang percakapan yang terus bertambah, input iterasi berikutnya mencakup output iterasi sebelumnya, sehingga jumlah input_tokens melebihi ukuran prompt tunggal mana pun. Gunakan usage.iterations untuk rincian lengkap per iterasi saat membangun logika pelacakan biaya.

Output advisor biasanya 400 hingga 700 token teks, atau 1.400 hingga 1.800 token total termasuk thinking. Penghematan biaya berasal dari advisor yang tidak menghasilkan output akhir lengkap Anda. Eksekutor melakukannya dengan tarifnya yang lebih rendah.

max_tokens tingkat atas hanya berlaku untuk output eksekutor. Ini tidak membatasi token sub-inferensi advisor. Untuk membatasi output advisor secara langsung, tetapkan max_tokens pada definisi alat. Token advisor juga tidak diambil dari anggaran tugas apa pun yang diterapkan pada eksekutor.

Priority Tier berlaku untuk setiap model secara independen. Komitmen Priority Tier pada model eksekutor tidak meluas ke advisor. Panggilan advisor berjalan pada Priority Tier hanya jika organisasi Anda juga memiliki komitmen pada model advisor.



Caching prompt advisor

Ada dua lapisan caching yang independen.



Caching sisi eksekutor

Blok advisor_tool_result dapat di-cache seperti blok konten lainnya. Breakpoint cache_control yang ditempatkan setelahnya pada giliran berikutnya akan mengenai cache. Prompt eksekutor selalu berisi saran plaintext terlepas dari apakah klien Anda menerima text atau encrypted_content, sehingga perilaku caching identik untuk kedua varian hasil.



Caching sisi advisor

Tetapkan caching pada definisi alat untuk mengaktifkan caching prompt untuk transkrip advisor sendiri di seluruh panggilan dalam percakapan yang sama:

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
        "caching": {"type": "ephemeral", "ttl": "5m"},
    }
]

Prompt advisor pada panggilan ke-N adalah prompt panggilan ke-(N-1) dengan satu segmen tambahan, sehingga prefiksnya stabil di seluruh panggilan. Dengan caching diaktifkan, setiap panggilan advisor menulis entri cache, dan panggilan berikutnya membaca hingga titik tersebut dan hanya membayar deltanya. Anda akan melihat cache_read_input_tokens menjadi bukan nol pada iterasi advisor_message kedua dan selanjutnya.

Kapan mengaktifkannya: Penulisan cache lebih mahal daripada penghematan dari pembacaan ketika advisor dipanggil dua kali atau kurang per percakapan. Caching mencapai titik impas pada kira-kira tiga panggilan advisor dan membaik dari sana. Aktifkan untuk loop agen yang panjang, dan biarkan nonaktif untuk tugas singkat.

Jaga konsistensinya: Tetapkan caching sekali dan biarkan untuk seluruh percakapan. Mengaktifkan dan menonaktifkannya di tengah percakapan menyebabkan cache miss.



Menggabungkan dengan alat lain

Alat advisor dapat dikombinasikan dengan alat sisi server dan sisi klien lainnya. Tambahkan semuanya ke array tools yang sama:

tools = [
    {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
    },
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

Eksekutor dapat mencari di web, memanggil advisor, dan menggunakan alat kustom Anda dalam giliran yang sama. Rencana advisor dapat menginformasikan alat mana yang akan digunakan eksekutor selanjutnya.



Praktik terbaik



Prompting untuk tugas coding dan agen

Alat advisor dilengkapi dengan deskripsi bawaan yang mendorong eksekutor untuk memanggilnya di awal tugas kompleks dan ketika menemui kesulitan. Untuk tugas riset, biasanya tidak diperlukan prompting tambahan.

Pada tugas coding dan agen, advisor menghasilkan kecerdasan lebih tinggi dengan biaya serupa ketika ia mengurangi total panggilan alat dan panjang percakapan. Dua waktu pemanggilan mendorong peningkatan ini:

1. Panggilan advisor pertama yang lebih awal, setelah beberapa pembacaan eksploratif ada dalam transkrip.
2. Untuk tugas sulit, panggilan advisor terakhir setelah penulisan file dan output pengujian ada dalam transkrip.

Jika agen Anda mengekspos alat lain yang mirip perencana (misalnya, alat daftar todo), arahkan model untuk memanggil advisor sebelum alat-alat tersebut sehingga rencana advisor mengalir ke dalamnya. Prompt sistem yang disarankan memperkuat pola pemanggilan awal. Tambahkan kalimat pengarah Anda sendiri yang menunjuk ke alat perencana mana pun yang diekspos agen Anda.



Prompt sistem yang disarankan untuk tugas coding

Tanpa pengarahan prompt sistem, eksekutor cenderung kurang memanggil advisor di beberapa domain, khususnya tugas coding. Untuk tugas coding di mana Anda menginginkan waktu pemanggilan advisor yang konsisten dan sekitar dua hingga tiga panggilan untuk setiap tugas, tambahkan blok berikut di awal prompt sistem eksekutor Anda sebelum kalimat lain yang menyebutkan advisor.

Panduan waktu:

You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.

Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck — errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.

Bagaimana eksekutor harus memperlakukan saran (tempatkan langsung setelah blok waktu):

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.



Prompt sistem alternatif untuk Haiku pada beban kerja coding

Claude Haiku 4.5 menerapkan panduan advisor default secara konservatif. Itu menjaga tingkat pemanggilannya tetap rendah secara tepat pada beban kerja riset dan pencarian tetapi mengorbankan kualitas pada beban kerja coding, di mana konsultasi advisor awal secara andal sepadan dengan biayanya. Pada benchmark coding internal, varian dekat dari blok berikut (pengecualian read-only dalam Hard rule ditambahkan setelah pengukuran) meningkatkan tingkat kelulusan Haiku sekitar 7,5 poin persentase dibandingkan default bawaan.

Gunakan blok ini sebagai pengganti blok waktu dan saran sebelumnya ketika eksekutor Haiku Anda menjalankan beban kerja yang didominasi coding atau tugas penulisan:

Consult a stronger reviewer who sees your full conversation transcript.

No parameters. When you call advisor(), your entire history -- task, every tool call and result, your reasoning -- is automatically forwarded. The advisor sees exactly what you've done.

Call advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck -- errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first -- that judgment call is exactly where a second opinion is highest-value.

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

Catatan: Pada benchmark pemahaman browse internal (n = 1.266), varian dekat dari blok ini mengorbankan sekitar 4 poin persentase akurasi relatif terhadap default bawaan. Jika beban kerja Anda mencampur coding dengan pencarian atau pengambilan yang substansial, tetap gunakan blok yang disarankan, atau batasi penggantian berdasarkan sinyal jenis beban kerja yang sudah Anda hitung.



Meningkatkan panggilan advisor pada eksekutor Opus

Eksekutor Opus biasanya memanggil advisor pada tingkat yang tepat tanpa prompting tambahan. Jika eksekutor Opus Anda kurang memanggil pada beban kerja Anda, tambahkan checkpoint berikut ke prompt sistem Anda:

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first. That judgment call is exactly where a second opinion is highest-value. (This does not apply to simple factual lookups or arithmetic; those you answer directly.)

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

Catatan: Dalam pengujian Anthropic, varian dekat dari blok ini (pengecualian read-only dalam Hard rule ditambahkan setelah pengukuran) meningkatkan tingkat kelulusan pada tugas yang kurang dipanggil sekitar 7 hingga 10 poin persentase tetapi menyebabkan Opus terlalu sering memanggil pada tugas yang tindakan pertamanya tidak memerlukan perencanaan. Efek bersihnya kira-kira datar pada beban kerja campuran. Hanya tambahkan jika Anda telah mengamati Opus melewatkan advisor pada tugas di mana konsultasi akan membantu. Jangan tambahkan sebagai default.



Memangkas panjang output advisor

Output advisor adalah pendorong biaya terbesar advisor, dan max_tokens tingkat atas tidak membatasinya. Advisor melihat prompt sistem Anda dan pesan pengguna Anda sebagai konteks kutipan tentang tugas eksekutor, sehingga instruksi yang ditujukan langsung kepada advisor diikuti jauh lebih andal daripada deskripsi orang ketiga. Penempatan paling efektif yang diuji Anthropic adalah sebuah baris dalam pesan pengguna:

(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)

Baris ini dapat ditambahkan di awal secara programatis oleh framework agen Anda sebelum mengirim permintaan. Batas ini adalah batasan lunak. Advisor sesekali melebihinya, jadi mintalah sekitar 80 persen dari batas atas Anda yang sebenarnya.

Pasangkan pendekatan ini dengan panduan waktu dalam Prompt sistem yang disarankan untuk tugas coding (atau blok Haiku alternatif jika Anda menggantinya) untuk tradeoff biaya-versus-kualitas yang paling kuat. Untuk batas atas keras alih-alih permintaan lunak, lihat Membatasi output advisor.



Membatasi output advisor

Tetapkan max_tokens pada definisi alat untuk membatasi total output advisor (thinking ditambah teks) per panggilan:

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
        "max_tokens": 2048,
    }
]

Nilai minimumnya adalah 1024. Menetapkan max_tokens di atas batas output model advisor sendiri mengembalikan error 400. Batas ini berlaku untuk setiap panggilan advisor secara independen dan tidak dibagi di seluruh panggilan dalam permintaan yang sama.

Ini bukan sekadar pemotongan keras. Server juga memberikan kepada advisor anggaran token yang tersisa, sehingga advisor membentuk responsnya agar sesuai.

Titik awal yang direkomendasikan: max_tokens: 2048. Dalam pengujian Anthropic pada benchmark penalaran sulit (n = 40 per konfigurasi), ini mengurangi rata-rata output advisor sekitar 7x dibandingkan dengan membiarkan batas tidak ditetapkan, dengan pemotongan hampir nol dan tanpa degradasi kualitas yang terdeteksi. Nilai minimum 1024 mengurangi output sekitar 10x tetapi memotong sekitar 10 persen panggilan. Perbedaan akurasi di seluruh konfigurasi berada dalam batas noise pada ukuran sampel ini. Validasi pada beban kerja Anda sendiri.

Tugas penalaran sulit memunculkan output advisor yang jauh lebih panjang daripada 1.400 hingga 1.800 token tipikal yang dikutip sebelumnya untuk beban kerja yang lebih ringan. Gunakan tabel ini untuk mengukur rasio penghematan, bukan sebagai baseline universal untuk output advisor.

Ketika advisor mencapai batas, blok hasil membawa stop_reason: "max_tokens" pada kedua varian hasil, model advisor mana pun yang Anda gunakan. Gunakan stop_reason untuk mendeteksi saran yang terpotong dan memutuskan apakah akan menaikkan batas atau membiarkan eksekutor melanjutkan dengan panduan parsial. API juga menambahkan [Advisor output truncated at max_tokens=2048.] (menyebutkan batas Anda) ke teks saran, sehingga eksekutor melihat pemotongan dalam konteksnya sendiri; dengan advisor advisor_result plaintext, penanda tersebut juga terlihat oleh klien Anda. Kedua sinyal hanya muncul ketika Anda menetapkan max_tokens pada definisi alat.

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
    "stop_reason": "max_tokens"
  }
}

Periksa output_tokens pada entri advisor_message yang sesuai dalam usage.iterations untuk melihat seberapa dekat setiap panggilan dengan batasnya.

Dibandingkan dengan pendekatan berbasis prompt, max_tokens adalah batas atas keras alih-alih permintaan lunak. Gunakan max_tokens ketika Anda memerlukan batas terjamin untuk biaya atau latensi. Gunakan pendekatan berbasis prompt (atau keduanya bersama-sama) ketika Anda ingin condong ke arah keringkasan tanpa risiko terpotong di tengah pemikiran.



Memasangkan dengan pengaturan effort

Untuk tugas coding, memasangkan eksekutor Sonnet pada effort medium dengan advisor Opus mencapai kecerdasan yang sebanding dengan Sonnet pada effort default, dengan biaya lebih rendah. Untuk kecerdasan maksimum, pertahankan eksekutor pada effort default.



Kontrol biaya

• Untuk anggaran tingkat percakapan, hitung panggilan advisor di sisi klien. Ketika Anda mencapai batas Anda, hapus alat advisor dari tools; Anda tidak perlu menghapus blok advisor_tool_result dari riwayat pesan Anda (lihat catatan dalam Percakapan multi-giliran).
• Aktifkan caching hanya untuk percakapan di mana Anda memperkirakan tiga panggilan advisor atau lebih.



Kompatibilitas model

Model eksekutor (field model tingkat atas) dan model penasihat (field model di dalam definisi alat) harus membentuk pasangan yang valid. Penasihat harus berupa Claude Sonnet 4.6 atau model yang lebih mumpuni, dan setidaknya harus sama mumpuninya dengan eksekutor. Model dengan kemampuan setara (misalnya, Claude Opus 4.7 dan Claude Opus 4.8) dapat saling menasihati.

Jika Anda meminta pasangan yang tidak valid, API mengembalikan 400 invalid_request_error yang menyebutkan kombinasi yang tidak didukung tersebut.



Ketersediaan platform

Alat penasihat tersedia dalam versi beta di Claude API dan di Claude Platform on AWS. Saat ini alat tersebut belum tersedia di Amazon Bedrock, Google Cloud, atau Microsoft Foundry.



Penasihat di Claude Managed Agents

Sesi Claude Managed Agents juga mendukung penasihat, yang dikonfigurasi sebagai bagian dari agen, bukan sebagai definisi alat: tambahkan entri {"type": "advisor", "model": ...} ke daftar multiagen milik agen, dan thread utama sesi dapat berkonsultasi dengan model tersebut di tengah giliran. Entri daftar ini tidak menerima opsi max_uses, max_tokens, atau caching, dan saran disampaikan sebagai event thread pada aliran event sesi, bukan sebagai blok advisor_tool_result dalam respons. Lihat Memberi sesi sebuah penasihat.



Langkah selanjutnya