Advisor tool

advisor tool을 사용하면 더 빠르고 저비용의 executor 모델이 생성 중간에 더 높은 지능의 advisor 모델에 전략적 지침을 요청할 수 있습니다. advisor는 전체 대화를 읽고 계획이나 과정 수정을 생성하며(일반적으로 400700개의 텍스트 토큰, 생각 포함 1,4001,800개의 토큰), executor가 작업을 계속합니다.

이 패턴은 대부분의 턴이 기계적이지만 훌륭한 계획이 중요한 장기 agentic 워크로드(코딩 에이전트, 컴퓨터 사용, 다단계 연구 파이프라인)에 적합합니다. executor 모델 속도로 대부분의 토큰 생성이 일어나면서 advisor 단독 품질에 가까운 결과를 얻을 수 있습니다.

사용 시기

초기 벤치마크는 다음 구성에서 의미 있는 개선을 보여줍니다:

• 현재 복잡한 작업에 Sonnet을 사용 중입니다: Opus를 advisor로 추가하여 유사하거나 더 낮은 총 비용으로 품질을 향상시킵니다.
• 현재 Haiku를 사용 중이고 지능 수준을 높이고 싶습니다: Opus를 advisor로 추가하세요. Haiku 단독보다 높은 비용이 들지만 executor를 더 큰 모델로 전환하는 것보다는 낮습니다.

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

advisor는 단일 턴 Q&A(계획할 것이 없음), 사용자가 이미 자신의 비용과 품질 트레이드오프를 선택하는 순수 통과 모델 선택기, 모든 턴이 advisor 모델의 전체 기능을 진정으로 필요로 하는 워크로드에는 적합하지 않습니다.

모델 호환성

executor 모델(최상위 model 필드)과 advisor 모델(도구 정의 내 model 필드)은 유효한 쌍을 형성해야 합니다. advisor는 최소한 executor만큼 능력이 있어야 합니다.

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

플랫폼 가용성

advisor tool은 Claude API(Anthropic)에서 베타로 사용 가능합니다.

빠른 시작

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-7",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Build a concurrent worker pool in Go with graceful shutdown.",
        }
    ],
)

print(response)

작동 방식

advisor tool을 tools 배열에 추가하면 executor 모델은 다른 도구처럼 호출 시기를 결정합니다. executor가 advisor를 호출할 때:

1. executor는 name: "advisor"와 빈 input을 포함한 server_tool_use 블록을 내보냅니다. executor가 타이밍을 신호하면 서버가 컨텍스트를 제공합니다.
2. Anthropic은 advisor 모델 서버 측에서 별도의 추론 패스를 실행하여 executor의 전체 기록을 전달합니다. advisor는 시스템 프롬프트, 모든 도구 정의, 모든 이전 턴, 모든 이전 도구 결과를 봅니다.
3. advisor의 응답은 advisor_tool_result 블록으로 executor에게 반환됩니다.
4. executor는 조언을 받아 생성을 계속합니다.

이 모든 것은 단일 /v1/messages 요청 내에서 발생합니다. 귀하 측에서 추가 왕복이 없습니다.

advisor 자체는 도구 없이 컨텍스트 관리 없이 실행됩니다. 그 생각 블록은 결과가 반환되기 전에 삭제되며, 조언 텍스트만 executor에게 도달합니다.

도구 매개변수

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

응답 구조

성공적인 advisor 호출

advisor가 호출되면 server_tool_use 블록 다음에 assistant의 콘텐츠에 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은 항상 비어 있습니다. 서버는 전체 기록에서 advisor의 보기를 자동으로 구성합니다. executor가 input에 넣는 것은 advisor에게 도달하지 않습니다.

결과 변형

advisor_tool_result.content 필드는 판별된 합집합입니다. 받는 변형은 advisor 모델에 따라 다릅니다:

advisor_result를 사용하면 text 필드에 인간이 읽을 수 있는 조언이 포함됩니다. advisor_redacted_result를 사용하면 encrypted_content 필드에 읽을 수 없는 불투명 blob이 포함됩니다. 다음 턴에서 서버는 이를 해독하고 일반 텍스트를 executor의 프롬프트로 렌더링합니다.

두 경우 모두 후속 턴에서 콘텐츠를 그대로 왕복시킵니다. 대화 중간에 advisor 모델을 전환하면 content.type에서 분기하여 두 형태를 모두 처리합니다.

오류 결과

advisor 호출이 실패하면 결과는 오류를 전달합니다:

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

executor는 오류를 보고 추가 조언 없이 계속됩니다. 요청 자체는 실패하지 않습니다.

Advisor 속도 제한은 advisor 모델에 대한 직접 호출과 동일한 모델별 버킷에서 가져옵니다. advisor의 속도 제한은 도구 결과 내에 too_many_requests로 나타나고, executor의 속도 제한은 HTTP 429로 전체 요청을 실패시킵니다.

다중 턴 대화

후속 턴에서 API에 advisor_tool_result 블록을 포함한 전체 assistant 콘텐츠를 다시 전달합니다:

import anthropic

client = anthropic.Anthropic()

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

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

# Append the full response content, including any advisor_tool_result blocks
messages.append({"role": "assistant", "content": response.content})

# Continue the conversation
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,
)

후속 턴에서 tools에서 advisor tool을 생략하면서 메시지 기록에 여전히 advisor_tool_result 블록이 포함되어 있으면 API는 400 invalid_request_error를 반환합니다.

스트리밍

advisor 하위 추론은 스트리밍되지 않습니다. executor의 스트림은 advisor가 실행되는 동안 일시 중지되고 전체 결과가 단일 이벤트에 도착합니다.

name: "advisor"를 포함한 server_tool_use 블록은 advisor 호출이 시작되고 있음을 신호합니다. 일시 중지는 해당 블록이 닫힐 때(content_block_stop) 시작됩니다. 일시 중지 중에 스트림은 표준 SSE ping keepalive를 제외하고는 조용하며, 대략 30초마다 내보내집니다. 짧은 advisor 호출은 ping을 표시하지 않을 수 있습니다.

advisor가 완료되면 advisor_tool_result는 단일 content_block_start 이벤트에서 완전히 형성되어 도착합니다(델타 없음). 그러면 executor 출력이 스트리밍을 재개합니다.

message_delta 이벤트가 뒤따르며 advisor의 토큰 수를 반영하는 업데이트된 usage.iterations 배열이 있습니다.

사용 및 청구

Advisor 호출은 advisor 모델의 요금으로 청구되는 별도의 하위 추론으로 실행됩니다. 사용량은 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-7",
        "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 필드는 executor 토큰만 반영합니다. Advisor 토큰은 다른 요금으로 청구되기 때문에 최상위 합계에 포함되지 않습니다. type: "advisor_message"를 포함한 반복은 advisor 모델의 요금으로 청구되고, type: "message"를 포함한 반복은 executor 모델의 요금으로 청구됩니다.

집계 규칙은 필드에 따라 다릅니다. 최상위 output_tokens는 모든 executor 반복의 합입니다. 최상위 input_tokens과 cache_read_input_tokens는 첫 번째 executor 반복만 반영합니다. 후속 executor 반복의 입력은 이전 출력 토큰을 포함하기 때문에 다시 합산되지 않습니다. 비용 추적 로직을 구축할 때 전체 반복별 분석을 위해 usage.iterations을 사용하세요.

Advisor 출력은 일반적으로 400700개의 텍스트 토큰 또는 생각 포함 1,4001,800개의 토큰입니다. 비용 절감은 advisor가 전체 최종 출력을 생성하지 않는다는 사실에서 비롯됩니다. executor가 더 낮은 요금으로 생성합니다.

최상위 max_tokens는 executor 출력에만 적용됩니다. advisor 하위 추론 토큰을 제한하지 않습니다. advisor의 토큰도 executor에 적용된 작업 예산에서 가져오지 않습니다.

Advisor 프롬프트 캐싱

두 개의 독립적인 캐싱 계층이 있습니다.

Executor 측 캐싱

advisor_tool_result 블록은 다른 콘텐츠 블록처럼 캐시 가능합니다. 후속 턴에서 그 뒤에 배치된 cache_control 중단점이 적중합니다. executor의 프롬프트는 클라이언트가 text 또는 encrypted_content를 받았는지 여부에 관계없이 항상 일반 텍스트 조언을 포함하므로 캐싱 동작은 두 결과 변형 모두에 동일합니다.

Advisor 측 캐싱

도구 정의에서 caching을 설정하여 같은 대화 내 호출 전반에 걸쳐 advisor의 자체 기록에 대한 프롬프트 캐싱을 활성화합니다:

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

N번째 호출의 advisor 프롬프트는 (N-1)번째 호출의 프롬프트에 하나의 세그먼트가 더 추가된 것이므로 접두사는 호출 전반에 걸쳐 안정적입니다. caching이 활성화되면 각 advisor 호출은 캐시 항목을 작성합니다. 다음 호출은 그 지점까지 읽고 델타에 대해서만 비용을 지불합니다. 두 번째 이상의 advisor_message 반복에서 cache_read_input_tokens가 0이 아닌 값이 됩니다.

활성화 시기: 캐시 쓰기 비용이 대화당 advisor가 2회 이하로 호출될 때 읽기가 절감하는 비용보다 많습니다. 캐싱은 대략 3번의 advisor 호출에서 손익분기점에 도달하고 그 이상에서 개선됩니다. 긴 에이전트 루프에 활성화하세요. 짧은 작업에는 비활성화 상태로 유지하세요.

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

다른 도구와 결합

advisor tool은 다른 서버 측 및 클라이언트 측 도구와 구성됩니다. 모두 동일한 tools 배열에 추가합니다:

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

executor는 같은 턴에서 웹을 검색하고, advisor를 호출하고, 사용자 정의 도구를 사용할 수 있습니다. advisor의 계획은 executor가 다음에 어떤 도구를 사용할지 알려줄 수 있습니다.

모범 사례

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

advisor tool은 executor를 복잡한 작업의 시작 근처에서 호출하도록 유도하고 어려움에 부딪힐 때 호출하도록 유도하는 기본 제공 설명과 함께 제공됩니다. 연구 작업의 경우 일반적으로 추가 프롬프팅이 필요하지 않습니다.

코딩 및 에이전트 작업에서 advisor는 총 도구 호출 및 대화 길이를 줄일 때 유사한 비용으로 더 높은 지능을 생성합니다. 두 가지 타이밍이 이 개선을 주도합니다:

1. 기록에 몇 가지 탐색적 읽기가 있은 후의 초기 첫 advisor 호출.
2. 어려운 작업의 경우 파일 쓰기 및 테스트 출력이 기록에 있은 후의 최종 advisor 호출.

에이전트가 다른 계획자 같은 도구를 노출하면(예: 할 일 목록 도구) 모델이 해당 도구 전에 advisor를 호출하도록 프롬프트하여 advisor의 계획이 그들로 흘러가도록 합니다. 아래 제안된 시스템 프롬프트는 초기 호출 패턴을 강화합니다. 에이전트가 노출하는 계획자 도구를 가리키는 자신의 깔때기 문장을 추가하세요.

코딩 작업을 위한 제안된 시스템 프롬프트

advisor를 언급하는 다른 문장 전에 다음 블록을 executor 시스템 프롬프트 앞에 추가하는 코딩 작업의 경우 일관된 advisor 타이밍과 작업당 약 2~3회의 호출을 원합니다. 내부 코딩 평가에서 이 패턴은 Sonnet 비용에 가까운 최고의 지능을 생성했습니다.

타이밍 지침:

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.

executor가 조언을 어떻게 취급해야 하는지(타이밍 블록 바로 뒤에 배치):

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.

Advisor 출력 길이 트리밍

Advisor 출력은 advisor의 가장 큰 비용 동인입니다. 비용을 줄이려면 advisor를 언급하는 다른 문장 전에 단일 간결성 지침을 시스템 프롬프트 앞에 추가하세요. 내부 테스트에서 다음 줄은 호출 빈도를 변경하지 않으면서 총 advisor 출력 토큰을 대략 35~45% 감소시켰습니다:

The advisor should respond in under 100 words and use enumerated steps, not explanations.

위의 타이밍 블록과 쌍을 이루어 가장 강력한 비용 대 품질 트레이드오프를 얻습니다.

노력 설정과 쌍 맞추기

코딩 작업의 경우 Sonnet executor를 중간 노력과 쌍으로 맞추고 Opus advisor를 사용하면 기본 노력의 Sonnet과 비교 가능한 지능을 더 낮은 비용으로 달성합니다. 최대 지능을 위해 executor를 기본 노력으로 유지하세요.

비용 제어

• 대화 수준 예산의 경우 클라이언트 측에서 advisor 호출을 계산하세요. 한계에 도달하면 tools에서 advisor tool을 제거하고 그리고 메시지 기록에서 모든 advisor_tool_result 블록을 제거하여 400 invalid_request_error를 피하세요.
• 대화당 3회 이상의 advisor 호출을 예상하는 경우에만 caching을 활성화하세요.

제한 사항

• Advisor 출력은 스트리밍되지 않습니다. 하위 추론이 실행되는 동안 스트림 일시 중지를 예상하세요.
• advisor 호출에 대한 기본 제공 대화 수준 한계가 없습니다. 클라이언트 측에서 추적하고 한계를 설정하세요.
• max_tokens는 executor 출력에만 적용됩니다. advisor 토큰을 제한하지 않습니다.
• Anthropic Priority Tier는 모델별로 적용됩니다. executor 모델의 Priority Tier는 advisor로 확장되지 않습니다. advisor 모델에 특별히 Priority Tier가 필요합니다.