Advisor 도구

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

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



사용 시기

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

• 현재 복잡한 작업에 Sonnet을 사용하는 경우: 더 높은 등급의 어드바이저를 추가하세요. Opus는 총 비용을 비슷하거나 더 낮게 유지하며, Claude Fable 5는 품질 향상을 극대화합니다.
• 현재 Haiku를 사용하며 지능을 한 단계 높이고 싶은 경우: Opus 또는 Fable 어드바이저를 추가하세요. Haiku 단독보다 비용이 높아지지만, 실행자를 더 큰 모델로 전환하는 것보다는 낮습니다.

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

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



빠른 시작

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에는 어드바이저의 지침을 담은 advisor_tool_result 블록이 포함됩니다. Claude Opus 5, Claude Fable 5 또는 Claude Mythos 5를 어드바이저로 사용하는 경우, 블록의 content 필드는 advisor_redacted_result 변형(암호화됨; 실행자는 서버 측에서 읽지만 클라이언트는 읽을 수 없음)입니다. 응답에서 조언 텍스트를 직접 보려면 대신 claude-opus-4-8을 어드바이저 모델로 사용하세요. 이 모델은 평문 advisor_result 변형을 반환합니다. 두 형태에 대해서는 결과 변형을, 유효한 조합의 전체 목록은 모델 호환성을 참조하세요.



작동 방식

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

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

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

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



도구 매개변수

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

Advisor 도구는 모든 도구 정의에서 사용 가능한 일반 속성인 cache_control, allowed_callers, defer_loading, strict(구조화된 출력에서 다룸)도 허용합니다. 이들의 의미는 도구 참조를 참조하세요.



응답 구조



성공적인 어드바이저 호출

어드바이저가 호출되면 어시스턴트의 콘텐츠에서 server_tool_use 블록 다음에 advisor_tool_result 블록이 옵니다. 다음 예시는 Claude Opus 4.8 어드바이저가 반환하는 평문 advisor_result 변형을 보여줍니다. 빠른 시작은 Claude Opus 5를 사용하며, 이는 대신 암호화된 advisor_redacted_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 Opus 5, 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에 다시 전달하세요. 이 예시는 response.content에서 평문 조언을 볼 수 있도록 claude-opus-4-8을 어드바이저로 사용합니다. 메커니즘은 모든 어드바이저 모델에서 동일합니다.

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-5",
    max_tokens=1024,
    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-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

메시지 기록에 여전히 advisor_tool_result 블록이 포함되어 있어도 후속 턴에서 tools에서 advisor 도구를 제거할 수 있습니다. 요청은 수락되고 기록 블록은 보존되며, 모델은 해당 턴에서 어드바이저를 호출할 수 없습니다. 해당 기록 블록이 수락되려면 여전히 advisor-tool-2026-03-01 베타 헤더를 보내야 합니다.



일시 중지된 턴 재개

어드바이저 호출이 아직 대기 중인 상태에서 응답이 stop_reason: "pause_turn"으로 끝날 수 있습니다. 이 경우 응답에는 어드바이저의 server_tool_use 블록이 포함되지만 이에 대한 advisor_tool_result는 없습니다. 재개하려면 해당 어시스턴트 메시지를 콘텐츠를 변경하지 않고 server_tool_use 블록을 유지한 채 messages에 추가하고, 동일한 advisor 도구와 베타 헤더로 요청을 다시 보내세요. 사용자 메시지나 tool_result 블록을 추가할 필요는 없습니다. API는 대기 중인 어드바이저 호출을 실행하고 새 응답에서 실행자의 턴을 계속합니다. 재개된 턴이 다시 일시 중지될 수 있습니다. 그런 경우 동일한 단계를 반복하세요. 재개 요청에서 advisor 도구를 생략하면 대기 중인 server_tool_use 블록에 실행할 도구 정의가 없으므로 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-5"},
    # ... 기타 도구들
]
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})
    # 시스템 프롬프트에서 이미 모델에게 호출을 자제하도록 지시한다면 이 부분은 건너뛰세요.
    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"}로 설정하세요. 단, 도구 사용 강제의 제약 조건이 적용됩니다. 도구 사용 강제는 수동 확장 사고(thinking: {type: "enabled"})와 결합할 수 없습니다. 둘 다 활성화하면 API가 400 invalid_request_error를 반환합니다. 적응형 thinking은 강제 도구 사용을 지원합니다.



스트리밍

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

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

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

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



사용량 및 청구

어드바이저 호출은 어드바이저 모델의 요금으로 청구되는 별도의 하위 추론으로 실행됩니다. 사용량은 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
      }
    ]
  }
}

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

모든 최상위 usage 필드는 input_tokens, output_tokens, cache_read_input_tokens를 포함하여 모든 실행자 반복에 걸친 해당 필드의 합계입니다. 각 실행자 반복이 증가하는 대화를 다시 보내므로 이후 반복의 입력에는 이전 반복의 출력이 포함되어, 합산된 input_tokens는 단일 프롬프트의 크기를 초과합니다. 비용 추적 로직을 구축할 때 전체 반복별 분석을 위해 usage.iterations를 사용하세요.

어드바이저 출력은 일반적으로 400700개의 텍스트 토큰이거나, thinking을 포함하여 총 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-5",
        "caching": {"type": "ephemeral", "ttl": "5m"},
    }
]

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

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

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



다른 도구와 결합

Advisor 도구는 다른 서버 측 및 클라이언트 측 도구와 조합할 수 있습니다. 모두 동일한 tools 배열에 추가하세요:

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

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



모범 사례



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

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

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

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 rule의 읽기 전용 예외 조항은 측정 후 추가됨)은 내장 기본값 대비 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 rule의 읽기 전용 예외 조항은 측정 후 추가됨)은 호출이 부족한 작업에서 통과율을 약 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를 설정하여 호출당 어드바이저의 총 출력(thinking과 텍스트 합계)을 제한하세요:

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 도구를 제거하세요. 메시지 기록에서 advisor_tool_result 블록을 제거할 필요는 없습니다(멀티턴 대화의 참고 사항 참조).
• 세 번 이상의 어드바이저 호출이 예상되는 대화에만 caching을 활성화하세요.



모델 호환성

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

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



플랫폼 가용성

조언자 도구는 Claude API와 AWS의 Claude Platform에서 베타로 제공됩니다. 현재 Amazon Bedrock, Google Cloud 또는 Microsoft Foundry에서는 사용할 수 없습니다.



Claude Managed Agents의 조언자

Claude Managed Agents 세션도 조언자를 지원하며, 이는 도구 정의가 아닌 에이전트의 일부로 구성됩니다. 에이전트의 멀티에이전트 로스터에 {"type": "advisor", "model": ...} 항목을 추가하면 세션의 기본 스레드가 턴 중간에 해당 모델에 자문을 구할 수 있습니다. 로스터 항목은 max_uses, max_tokens 또는 caching 옵션을 받지 않으며, 조언은 응답의 advisor_tool_result 블록이 아닌 세션의 이벤트 스트림에서 스레드 이벤트로 전달됩니다. 세션에 조언자 제공하기를 참조하세요.



다음 단계