어드바이저 도구

어드바이저 도구를 사용하면 더 빠르고 저렴한 **"executor model"(실행자 모델)**이 생성 도중에 더 높은 지능의 **"advisor model"(어드바이저 모델)**에게 전략적 지침을 요청할 수 있습니다. 어드바이저는 전체 대화를 읽고 계획이나 방향 수정을 생성하며, 실행자는 작업을 계속 진행합니다.

이 패턴은 대부분의 턴이 기계적이지만 훌륭한 계획을 갖는 것이 중요한 장기 에이전트 워크로드(코딩 에이전트, 컴퓨터 사용, 다단계 리서치 파이프라인)에 적합합니다. 토큰 생성의 대부분이 실행자 모델 요금으로 이루어지면서도 어드바이저 단독 사용에 가까운 품질을 얻을 수 있습니다.



사용 시기

어드바이저는 다음 구성에 적합합니다:

• 현재 복잡한 작업에 Sonnet을 사용하는 경우: Opus를 어드바이저로 추가하면 비슷하거나 더 낮은 총비용으로 품질을 향상시킬 수 있습니다.
• 현재 Haiku를 사용하고 있으며 지능을 한 단계 높이고 싶은 경우: Opus를 어드바이저로 추가하세요. Haiku 단독 사용보다는 비용이 높지만, 실행자를 더 큰 모델로 전환하는 것보다는 낮습니다.

결과는 작업에 따라 다릅니다. 자체 워크로드에서 평가하세요.

어드바이저는 단일 턴 Q&A(계획할 것이 없음), 사용자가 이미 자신의 비용과 품질 간 균형을 직접 선택하는 순수 패스스루 모델 선택기, 또는 모든 턴이 실제로 어드바이저 모델의 전체 역량을 필요로 하는 워크로드에는 적합하지 않습니다.



모델 호환성

실행자 모델(최상위 model 필드)과 어드바이저 모델(도구 정의 내부의 model 필드)은 유효한 쌍을 이루어야 합니다. 어드바이저는 Claude Sonnet 4.6 이상의 역량을 가진 모델이어야 하며, 최소한 실행자와 동등한 역량을 가져야 합니다. 동등한 역량의 모델(예: Claude Opus 4.7과 Claude Opus 4.8)은 서로에게 조언할 수 있습니다.

유효하지 않은 쌍을 요청하면 API는 지원되지 않는 조합을 명시한 400 invalid_request_error를 반환합니다.



플랫폼 가용성

어드바이저 도구는 Claude API와 Claude Platform on AWS에서 베타로 제공됩니다. 현재 Amazon Bedrock, Google Cloud 또는 Microsoft Foundry에서는 사용할 수 없습니다.



빠른 시작

client = anthropic.Anthropic()

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

print(response)



작동 방식

tools 배열에 어드바이저 도구를 추가하면, 실행자 모델은 다른 도구와 마찬가지로 언제 호출할지 결정합니다. 실행자가 어드바이저를 호출하면:

1. 실행자는 name: "advisor"와 빈 input을 가진 server_tool_use 블록을 생성합니다. 실행자는 타이밍을 알리고, 서버가 컨텍스트를 제공합니다.
2. Anthropic은 서버 측에서 어드바이저 모델에 대한 별도의 추론 패스를 실행합니다. 어드바이저는 Anthropic이 제공하는 자체 시스템 프롬프트 하에서 실행되며, 실행자의 전체 트랜스크립트를 입력의 인용된 컨텍스트로 받습니다. 이 트랜스크립트에는 사용자의 시스템 프롬프트, 도구 정의, 이전 턴과 도구 결과, 그리고 실행자가 이번 턴에서 지금까지 생성한 텍스트가 포함됩니다.
3. 어드바이저의 응답은 advisor_tool_result 블록으로 실행자에게 반환됩니다.
4. 실행자는 조언을 바탕으로 생성을 계속합니다.

이 모든 과정은 단일 /v1/messages 요청 내에서 이루어지며, 사용자 측에서 추가 왕복이 필요하지 않습니다. 예외는 호출 도중에 일시 중지되는 턴으로, 후속 요청으로 재개합니다(일시 중지된 턴 재개하기 참조).

어드바이저 자체는 도구 없이, 컨텍스트 관리 없이 실행됩니다. 어드바이저의 사고 블록은 결과가 반환되기 전에 제거됩니다. 조언 텍스트만 실행자에게 전달됩니다.



도구 파라미터

caching 객체는 {"type": "ephemeral", "ttl": "5m" | "1h"} 형태를 가집니다. 콘텐츠 블록의 cache_control과 달리, 이는 브레이크포인트 마커가 아닙니다. 켜기/끄기 스위치입니다. 캐시 경계의 위치는 서버가 결정합니다.

어드바이저 도구는 모든 도구 정의에서 사용할 수 있는 일반 속성도 허용합니다: cache_control, allowed_callers, defer_loading, strict(구조화된 출력에서 다룸). 각 속성의 의미는 도구 참조를 참조하세요.



응답 구조



성공적인 어드바이저 호출

어드바이저가 호출되면, 어시스턴트의 콘텐츠에서 server_tool_use 블록 뒤에 advisor_tool_result 블록이 이어집니다:

{
  "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은 항상 비어 있습니다. 서버가 전체 트랜스크립트로부터 어드바이저의 뷰를 자동으로 구성합니다. 실행자가 input에 넣는 어떤 것도 어드바이저에게 전달되지 않습니다.



결과 변형

advisor_tool_result.content 필드는 판별 유니온(discriminated union)입니다. 성공적인 호출의 경우, 변형은 어드바이저 모델에 따라 달라집니다:

Claude Fable 5와 Claude Mythos 5 어드바이저는 advisor_redacted_result를 반환합니다. 호환성 표의 다른 어드바이저 모델은 advisor_result를 반환합니다.

두 결과 변형 모두 도구 정의에 max_tokens를 설정한 경우 stop_reason 필드를 포함하며, 설정하지 않은 경우 생략합니다. 이 필드는 어드바이저 하위 호출의 중지 이유를 담으며, 일반적으로 "end_turn"이고, 상한에 도달한 경우 "max_tokens"입니다. 값은 최상위 Messages API stop_reason과 일치합니다.

advisor_result의 경우, text 필드에 사람이 읽을 수 있는 조언이 포함됩니다. advisor_redacted_result의 경우, encrypted_content 필드에 읽을 수 없는 불투명한 블롭이 포함됩니다. 다음 턴에서 서버가 이를 복호화하여 일반 텍스트를 실행자의 프롬프트에 렌더링합니다.

두 경우 모두 후속 턴에서 콘텐츠를 그대로 왕복 전달하세요. 대화 도중에 어드바이저 모델을 전환하는 경우, content.type으로 분기하여 두 형태를 모두 처리하세요.



오류 결과

어드바이저 호출이 실패하면 결과에 오류가 포함됩니다:

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

실행자는 오류를 확인하고 추가 조언 없이 계속 진행합니다. 요청 자체는 실패하지 않습니다.

어드바이저 속도 제한은 어드바이저 모델에 대한 직접 호출과 동일한 모델별 버킷에서 차감됩니다. 어드바이저의 속도 제한은 도구 결과 내부에 too_many_requests로 나타납니다. 실행자의 속도 제한은 HTTP 429로 전체 요청을 실패시킵니다.



다중 턴 대화

후속 턴에서 advisor_tool_result 블록을 포함한 전체 어시스턴트 콘텐츠를 API에 다시 전달하세요:

client = anthropic.Anthropic()

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

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

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

# advisor_tool_result 블록을 포함한 전체 응답 내용을 추가합니다
messages.append({"role": "assistant", "content": response.content})

# 대화를 계속합니다
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

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

메시지 기록에 여전히 advisor_tool_result 블록이 포함되어 있는 상태에서 후속 턴의 tools에서 어드바이저 도구를 생략하면, API는 400 invalid_request_error를 반환합니다.



일시 중지된 턴 재개하기

어드바이저 호출이 아직 대기 중인 상태에서 응답이 stop_reason: "pause_turn"으로 끝날 수 있습니다. 이 경우 응답에는 해당하는 advisor_tool_result 없이 어드바이저의 server_tool_use 블록이 포함됩니다. 재개하려면 해당 어시스턴트 메시지를 콘텐츠를 변경하지 않고 server_tool_use 블록을 유지한 채 messages에 추가하고, 동일한 어드바이저 도구와 베타 헤더로 요청을 다시 보내세요. 사용자 메시지나 tool_result 블록을 추가할 필요는 없습니다. API는 대기 중인 어드바이저 호출을 실행하고 새 응답에서 실행자의 턴을 계속합니다. 재개된 턴은 다시 일시 중지될 수 있습니다. 그런 경우 동일한 단계를 반복하세요. 재개 요청에서 어드바이저 도구를 생략하면 400 invalid_request_error가 반환됩니다. 대신 실행자가 동일한 턴에서 사용자의 도구 중 하나를 호출한 경우, 어드바이저 호출이 아직 대기 중인 상태에서 응답은 stop_reason: "tool_use"로 끝납니다. 평소처럼 tool_result 블록을 보내면, 대기 중인 어드바이저 호출이 다음 요청의 시작 시점에 실행됩니다. 한 턴에서 서버 도구와 클라이언트 도구 혼합하기를 참조하세요.



호출이 부족한 실행자를 위한 대화 중간 넛지

Haiku 실행자가 첫 번째 어시스턴트 턴에서 어드바이저를 호출하지 않은 경우, 두 번째 어시스턴트 턴 전에 짧은 리마인더를 추가 사용자 메시지로 덧붙이세요. Anthropic의 내부 행동 평가에서 이는 Haiku 실행자의 작업 통과율을 약 7퍼센트포인트 높였습니다. Sonnet 실행자에서는 일반 텍스트 넛지가 Anthropic의 테스트에서 측정 가능한 효과가 없었습니다. 이어지는 호출 타이밍 고려 사항은 Sonnet에 특히 관련이 있습니다. Opus 실행자에는 넛지를 적용하지 마세요: Opus에서는 통과율이 약간 낮아졌습니다.

기본 NUDGE_TURN 값 2를 사용하면, 리마인더는 일반적으로 모델이 작업을 파악한 후 접근 방식을 확정하기 전에 도착합니다.

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):
    # 도구 디스패치로 교체하세요. tool_use 블록마다 하나의 tool_result 블록을 반환합니다.
    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-4-8"},
    # ... 기타 도구들
]
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(
        b.type == "server_tool_use" and b.name == "advisor" for b 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})
    # 시스템 프롬프트에서 이미 모델에게 호출을 자제하도록 지시하고 있다면 이 단계는 건너뛰세요.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

넛지는 동일한 메시지의 형제 블록이 아니라 도구 결과 뒤에 별도의 사용자 메시지로 추가하세요. 연속된 사용자 메시지는 유효합니다. Anthropic의 Haiku 및 Sonnet 실행자 테스트에서 두 방식은 동등하게 동작했습니다. 별도 메시지 형태는 또한 리마인더를 도구 출력과 명확하게 구분되도록 유지합니다.

트레이드오프: 넛지는 호출률을 높이므로, 아주 단순한 작업에서도 불필요한 상담이 발생할 수 있습니다. 워크로드에 단순한 작업과 복잡한 작업이 섞여 있다면, 두 턴짜리 작업이 넛지가 발동하기 전에 완료되도록 NUDGE_TURN을 3으로 올리거나, 이미 계산하고 있는 작업 복잡도 신호로 넛지를 게이팅하는 것을 고려하세요. 시스템 프롬프트에 이미 절제 문구("진정한 불확실성이 있을 때만 어드바이저를 사용하세요")가 포함되어 있다면, 두 지시가 충돌하므로 넛지를 완전히 생략하세요.

일반 텍스트 넛지는 Haiku 및 Sonnet 실행자에서 매우 두드러집니다: Anthropic의 테스트에서 넛지를 받은 시도의 74퍼센트(Sonnet)에서 98퍼센트(Haiku)가 턴 2에서 즉시 어드바이저를 호출했습니다. 실행자가 문제를 읽거나 컨텍스트를 수집하기 전에 넛지가 도착하면, 결과적인 어드바이저 호출은 컨텍스트가 부족하고 더 적절한 시점의 이후 호출을 대체할 수 있습니다. 넛지를 추가하기 전에 실행자의 기준 첫 호출 턴을 측정하세요. 실행자가 이미 어드바이저를 안정적으로 호출하고 첫 호출이 일반적으로 턴 N에 발생한다면, NUDGE_TURN을 N보다 크게 설정하세요. Anthropic의 테스트에서, 기준 첫 호출이 턴 7 이후인 워크로드에 턴 2 넛지를 적용하면 작업 성능이 3~4퍼센트포인트 하락하는 것과 상관관계가 있었습니다. 기준 호출률이 86퍼센트인 브라우징 워크로드에서는 동일한 넛지가 작업 성능 손실 없이 참여도를 높였습니다.

넛지 대신 특정 요청에서 상담을 강제하려면, 도구 사용 강제하기의 제약 조건에 따라 tool_choice를 {"type": "tool", "name": "advisor"}로 설정하세요. 도구 사용 강제는 확장 사고와 결합할 수 없습니다: 둘 다 활성화하면 API가 400 invalid_request_error를 반환합니다.



스트리밍

어드바이저 하위 추론은 스트리밍되지 않습니다. 어드바이저가 실행되는 동안 실행자의 스트림이 일시 중지되고, 이후 전체 결과가 단일 이벤트로 도착합니다.

name: "advisor"를 가진 server_tool_use 블록은 어드바이저 호출이 시작됨을 알립니다. 일시 중지는 해당 블록이 닫힐 때(content_block_stop) 시작됩니다. 일시 중지 동안 스트림은 약 30초마다 발생하는 표준 SSE ping 킵얼라이브를 제외하고는 조용합니다. 짧은 어드바이저 호출에서는 ping이 나타나지 않을 수 있습니다.

어드바이저가 완료되면, advisor_tool_result가 단일 content_block_start 이벤트로 완전한 형태로 도착합니다(델타 없음). 그런 다음 실행자 출력이 스트리밍을 재개합니다.

이어서 어드바이저의 토큰 수를 반영하는 업데이트된 usage.iterations 배열을 포함한 message_delta 이벤트가 뒤따릅니다.



사용량 및 청구

어드바이저 호출은 어드바이저 모델의 요금으로 청구되는 별도의 하위 추론으로 실행됩니다. 사용량은 usage.iterations[] 배열에 보고됩니다:

{
  "usage": {
    "input_tokens": 412,
    "cache_read_input_tokens": 0,
    "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-4-8",
        "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
      }
    ]
  }
}

최상위 usage 필드는 실행자 토큰만 반영합니다. 어드바이저 토큰은 다른 요금으로 청구되기 때문에 최상위 합계에 포함되지 않습니다. type: "advisor_message"인 반복(iteration)은 어드바이저 모델의 요금으로 청구되고, type: "message"인 반복은 실행자 모델의 요금으로 청구됩니다.

집계 규칙은 필드마다 다릅니다. 최상위 output_tokens는 모든 실행자 반복의 합계입니다. 최상위 input_tokens와 cache_read_input_tokens는 첫 번째 실행자 반복만 반영합니다. 이후 실행자 반복의 입력은 이전 출력 토큰을 포함하기 때문에 다시 합산되지 않습니다. 비용 추적 로직을 구축할 때는 usage.iterations를 사용하여 반복별 전체 내역을 확인하세요.

어드바이저 출력은 일반적으로 400700 텍스트 토큰이며, 사고를 포함하면 총 1,4001,800 토큰입니다. 비용 절감은 어드바이저가 전체 최종 출력을 생성하지 않는 데서 비롯됩니다. 실행자가 더 낮은 요금으로 그 작업을 수행합니다.

최상위 max_tokens는 실행자 출력에만 적용됩니다. 어드바이저 하위 추론 토큰을 제한하지 않습니다. 어드바이저 출력을 직접 제한하려면 도구 정의에 max_tokens를 설정하세요. 어드바이저의 토큰은 실행자에 적용된 작업 예산에서도 차감되지 않습니다.

Priority Tier는 각 모델에 독립적으로 적용됩니다. 실행자 모델에 대한 Priority Tier 약정은 어드바이저로 확장되지 않습니다. 어드바이저 호출은 조직이 어드바이저 모델에 대한 약정도 보유한 경우에만 Priority Tier로 실행됩니다.



어드바이저 프롬프트 캐싱

두 개의 독립적인 캐싱 레이어가 있습니다.



실행자 측 캐싱

advisor_tool_result 블록은 다른 콘텐츠 블록과 마찬가지로 캐시할 수 있습니다. 후속 턴에서 그 뒤에 배치된 cache_control 브레이크포인트는 캐시 히트됩니다. 클라이언트가 text를 받았든 encrypted_content를 받았든 실행자의 프롬프트에는 항상 일반 텍스트 조언이 포함되므로, 캐싱 동작은 두 결과 변형 모두 동일합니다.



어드바이저 측 캐싱

도구 정의에 caching을 설정하여 동일한 대화 내 호출 전반에 걸쳐 어드바이저 자체 트랜스크립트에 대한 프롬프트 캐싱을 활성화하세요:

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

N번째 호출에서 어드바이저의 프롬프트는 (N-1)번째 호출의 프롬프트에 세그먼트 하나가 더 추가된 것이므로, 접두사는 호출 간에 안정적입니다. caching이 활성화되면 각 어드바이저 호출이 캐시 항목을 기록하고, 다음 호출은 그 지점까지 읽어 델타에 대해서만 비용을 지불합니다. 두 번째 이후의 advisor_message 반복에서 cache_read_input_tokens가 0이 아닌 값이 되는 것을 확인할 수 있습니다.

활성화 시기: 대화당 어드바이저가 두 번 이하로 호출되는 경우, 캐시 쓰기 비용이 읽기로 절약되는 비용보다 큽니다. 캐싱은 대략 세 번의 어드바이저 호출에서 손익분기점에 도달하고 그 이후로 개선됩니다. 긴 에이전트 루프에서는 활성화하고, 짧은 작업에서는 비활성화하세요.

일관성 유지: caching을 한 번 설정하고 대화 전체에서 유지하세요. 대화 도중에 껐다 켜면 캐시 미스가 발생합니다.



다른 도구와 결합하기

어드바이저 도구는 다른 서버 측 및 클라이언트 측 도구와 함께 구성할 수 있습니다. 모두 동일한 tools 배열에 추가하세요:

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

실행자는 동일한 턴에서 웹을 검색하고, 어드바이저를 호출하고, 사용자 정의 도구를 사용할 수 있습니다. 어드바이저의 계획은 실행자가 다음에 어떤 도구를 사용할지에 영향을 줄 수 있습니다.



모범 사례



코딩 및 에이전트 작업을 위한 프롬프팅

어드바이저 도구에는 복잡한 작업의 시작 부분과 어려움에 부딪혔을 때 호출하도록 실행자를 유도하는 내장 설명이 포함되어 있습니다. 리서치 작업의 경우 일반적으로 추가 프롬프팅이 필요하지 않습니다.

코딩 및 에이전트 작업에서 어드바이저는 총 도구 호출 수와 대화 길이를 줄일 때 비슷한 비용으로 더 높은 지능을 제공합니다. 두 가지 타이밍이 이러한 개선을 이끕니다:

1. 몇 번의 탐색적 읽기가 트랜스크립트에 포함된 후의 이른 첫 번째 어드바이저 호출.
2. 어려운 작업의 경우, 파일 쓰기와 테스트 출력이 트랜스크립트에 포함된 후의 마지막 어드바이저 호출.

에이전트가 다른 플래너 유사 도구(예: 할 일 목록 도구)를 노출하는 경우, 어드바이저의 계획이 해당 도구로 흘러들어가도록 그 도구들보다 먼저 어드바이저를 호출하도록 모델에 프롬프트하세요. 권장 시스템 프롬프트는 이른 호출 패턴을 강화합니다. 에이전트가 노출하는 플래너 도구를 가리키는 자체 연결 문장을 추가하세요.



코딩 작업을 위한 권장 시스템 프롬프트

시스템 프롬프트 유도 없이는 실행자가 일부 도메인, 특히 코딩 작업에서 어드바이저를 충분히 호출하지 않는 경향이 있습니다. 일관된 어드바이저 타이밍과 작업당 약 2~3회의 호출을 원하는 코딩 작업의 경우, 어드바이저를 언급하는 다른 문장보다 앞에 다음 블록을 실행자 시스템 프롬프트에 추가하세요.

타이밍 지침:

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.

실행자가 조언을 어떻게 다루어야 하는지(타이밍 블록 바로 뒤에 배치):

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.



코딩 워크로드에서 Haiku를 위한 대체 시스템 프롬프트

Claude Haiku 4.5는 기본 어드바이저 지침을 보수적으로 적용합니다. 이는 리서치 및 조회 워크로드에서 호출률을 적절히 낮게 유지하지만, 이른 어드바이저 상담이 확실히 비용 대비 효과가 있는 코딩 워크로드에서는 품질을 포기하게 됩니다. 내부 코딩 벤치마크에서 다음 블록의 유사 변형(Hard 규칙의 읽기 전용 예외는 측정 후 추가됨)은 내장 기본값 대비 Haiku 통과율을 약 7.5퍼센트포인트 높였습니다.

Haiku 실행자가 주로 코딩 또는 쓰기 작업 워크로드를 실행하는 경우, 앞의 타이밍 및 조언 블록 대신 이 블록을 사용하세요:

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.

주의 사항: 내부 브라우징 이해 벤치마크(n = 1,266)에서 이 블록의 유사 변형은 내장 기본값 대비 약 4퍼센트포인트의 정확도 손실을 초래했습니다. 워크로드에 코딩과 상당한 조회 또는 검색이 섞여 있다면, 권장 블록을 유지하거나, 이미 계산하고 있는 워크로드 유형 신호로 교체를 게이팅하세요.



Opus 실행자에서 어드바이저 호출 늘리기

Opus 실행자는 일반적으로 추가 프롬프팅 없이도 적절한 비율로 어드바이저를 호출합니다. Opus 실행자가 워크로드에서 호출이 부족한 경우, 시스템 프롬프트에 다음 체크포인트를 추가하세요:

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.

주의 사항: Anthropic의 테스트에서 이 블록의 유사 변형(Hard 규칙의 읽기 전용 예외는 측정 후 추가됨)은 호출이 부족한 작업의 통과율을 약 7~10퍼센트포인트 높였지만, 첫 번째 작업에 계획이 필요 없는 작업에서 Opus가 과도하게 호출하게 만들었습니다. 혼합 워크로드에서 순효과는 거의 없었습니다. 상담이 도움이 되었을 작업에서 Opus가 어드바이저를 건너뛰는 것을 관찰한 경우에만 추가하세요. 기본값으로 추가하지 마세요.



어드바이저 출력 길이 줄이기

어드바이저 출력은 어드바이저의 가장 큰 비용 요인이며, 최상위 max_tokens는 이를 제한하지 않습니다. 어드바이저는 실행자의 작업에 대한 인용된 컨텍스트로 시스템 프롬프트와 사용자 메시지를 모두 보기 때문에, 어드바이저에게 직접 말하는 지시가 3인칭 설명보다 훨씬 더 안정적으로 따라집니다. Anthropic이 테스트한 가장 효과적인 배치는 사용자 메시지의 한 줄입니다:

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

이 줄은 요청을 보내기 전에 에이전트 프레임워크에서 프로그래밍 방식으로 접두사로 추가할 수 있습니다. 이 제한은 소프트 제약입니다. 어드바이저가 가끔 이를 초과하므로, 실제 상한의 약 80퍼센트를 요청하세요.

가장 강력한 비용 대비 품질 트레이드오프를 위해 이 접근 방식을 코딩 작업을 위한 권장 시스템 프롬프트의 타이밍 지침(또는 교체한 경우 대체 Haiku 블록)과 함께 사용하세요. 소프트 요청이 아닌 하드 상한이 필요하면 어드바이저 출력 제한하기를 참조하세요.



어드바이저 출력 제한하기

도구 정의에 max_tokens를 설정하여 호출당 어드바이저의 총 출력(사고 및 텍스트)을 제한하세요:

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

최솟값은 1024입니다. 어드바이저 모델 자체의 출력 상한보다 높게 max_tokens를 설정하면 400 오류가 반환됩니다. 상한은 각 어드바이저 호출에 독립적으로 적용되며 동일한 요청 내의 호출 간에 공유되지 않습니다.

이는 단순한 하드 잘라내기가 아닙니다. 서버는 어드바이저에게 남은 토큰 예산도 전달하므로, 어드바이저는 응답을 그에 맞게 구성합니다.

권장 시작점: max_tokens: 2048. Anthropic의 어려운 추론 벤치마크 테스트(구성당 n = 40)에서, 이는 상한을 설정하지 않은 경우와 비교하여 평균 어드바이저 출력을 약 7배 줄였으며, 잘림은 거의 없고 감지 가능한 품질 저하도 없었습니다. 최솟값 1024는 출력을 약 10배 줄였지만 호출의 약 10퍼센트가 잘렸습니다. 모든 구성에서의 정확도 차이는 이 샘플 크기에서 노이즈 범위 내였습니다. 자체 워크로드에서 검증하세요.

어려운 추론 작업은 앞서 더 가벼운 워크로드에 대해 언급한 일반적인 1,400~1,800 토큰보다 상당히 긴 어드바이저 출력을 유발합니다. 이 표는 절감 비율을 산정하는 데 사용하고, 어드바이저 출력의 보편적인 기준선으로 사용하지 마세요.

어드바이저가 상한에 도달하면 결과 블록에 stop_reason: "max_tokens"가 포함됩니다. API는 또한 조언 텍스트에 [Advisor output truncated at max_tokens=2048.](설정한 상한을 명시)를 추가하므로, 실행자는 자신의 컨텍스트에서 잘림을 확인할 수 있습니다. stop_reason을 사용하여 잘린 조언을 감지하고 상한을 올릴지 아니면 실행자가 부분적인 지침으로 진행하도록 할지 결정하세요. 두 신호 모두 도구 정의에 max_tokens를 설정한 경우에만 나타납니다.

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_result",
    "text": "Use a channel-based coordination pattern. The tricky part is\n\n[Advisor output truncated at max_tokens=2048.]",
    "stop_reason": "max_tokens"
  }
}

usage.iterations의 해당 advisor_message 항목에서 output_tokens를 확인하여 각 호출이 상한에 얼마나 근접했는지 확인하세요.

프롬프트 기반 접근 방식과 비교하면, max_tokens는 소프트 요청이 아닌 하드 상한입니다. 비용이나 지연 시간에 대한 보장된 한계가 필요하면 max_tokens를 사용하세요. 사고 도중 잘림의 위험 없이 간결함 쪽으로 유도하고 싶다면 프롬프트 기반 접근 방식(또는 둘 다 함께)을 사용하세요.



effort 설정과 함께 사용하기

코딩 작업의 경우, medium effort의 Sonnet 실행자와 Opus 어드바이저를 결합하면 기본 effort의 Sonnet과 비슷한 지능을 더 낮은 비용으로 달성할 수 있습니다. 최대 지능을 위해서는 실행자를 기본 effort로 유지하세요.



비용 제어

• 대화 수준 예산의 경우, 클라이언트 측에서 어드바이저 호출 수를 세세요. 상한에 도달하면 tools에서 어드바이저 도구를 제거하고 동시에 메시지 기록에서 모든 advisor_tool_result 블록을 제거하여 400 invalid_request_error를 방지하세요(다중 턴 대화의 참고 사항 참조).
• 세 번 이상의 어드바이저 호출이 예상되는 대화에서만 caching을 활성화하세요.



다음 단계