AI/Claude

Claude API 신기능 : Advisor Strategy(어드바이저 전략) - 비용은 낮추고 성능은 올리는 Advisor Tool API

안녕하세요! 갓대희 입니다.

AI 에이전트 개발자라면 한 번쯤 마주치는 딜레마가 있다. 성능이 필요하면 Opus, 비용이 걱정되면 Haiku나 Sonnet — 이 둘 중 하나를 골라야 했다. Anthropic이 2026년 초 이 이분법을 깨는 패턴을 공식 API로 내놨다. 이름은 Advisor Strategy다.

핵심 아이디어는 단순하다. 빠른 모델(executor)이 작업을 진행하다 복잡한 판단이 필요한 순간에만 Opus(advisor)에게 묻는다. Opus는 도구도 실행하지 않고, 짧은 계획만 전달한다. executor는 그 조언을 받아 재개한다.

이 글에서는 두 가지를 다룬다. 하나는 공식 Advisor Tool API — Python SDK와 TypeScript SDK, curl로 바로 붙일 수 있는 코드 예시. 다른 하나는 advisor-opus 커뮤니티 플러그인 — Claude Code에서 슬래시 커맨드 하나로 Opus에게 묻는 방법이다.

등장 배경 — 왜 Advisor Strategy가 필요했나
핵심 개념 — 동작 원리와 API 구조
벤치마크 — 실제로 얼마나 좋아졌나
공식 API 사용법 — Python SDK · TypeScript SDK · curl 예시
advisor-opus 플러그인 설치 및 사용법
사용 시나리오별 선택 가이드
베타 제한사항 · 트러블슈팅 Q&A
도입 플레이북

1. 등장 배경 — 왜 Advisor Strategy가 필요했나

에이전트 프레임워크를 만들어본 개발자라면 공통된 벽에 부딪혔을 것이다. Opus를 쓰면 품질은 좋지만 비용이 부담스럽고, Haiku나 Sonnet을 쓰면 복잡한 추론 단계에서 실수가 나온다.

Anthropic 공식 블로그에 따르면, 현장 개발자들이 이미 이 패턴에 독립적으로 수렴하고 있었다. 비싼 Opus를 전체 작업에 쓸 것인지, 저렴한 모델로 품질을 낮출 것인지 — 이 이분법이 에이전트 설계의 공통된 병목이었다. Advisor Strategy는 이 둘 사이에 세 번째 길을 제시한다. executor가 작업을 계속 담당하되, 복잡한 판단이 필요한 시점에만 Opus에게 자문을 구하는 것이다.

핵심은 "모델 전환 없는 실시간 자문"이다. 작업 중간에 Opus로 갈아타는 것이 아니라, executor가 실행을 멈추지 않고 Opus의 조언만 구해서 계속 진행한다.

Anthropic이 이 패턴을 공식 API로 표준화했다.

2. 핵심 개념 — 동작 원리와 API 구조

executor가 advisor에게 묻는 흐름

공식 문서에 따르면 동작 흐름은 다음과 같다.

"The executor model (Sonnet/Haiku) runs tasks end-to-end, calling tools and iterating. When facing difficult decisions, it consults Opus for guidance—which provides plans, corrections, or stop signals—then resumes execution."

(해석) executor 모델(Sonnet/Haiku)은 작업을 처음부터 끝까지 담당하며 도구를 호출하고 반복 실행한다. 복잡한 판단이 필요한 순간에는 Opus에 자문을 구해 계획·수정·중단 신호를 받은 뒤 실행을 재개한다.

executor는 작업 전체를 처음부터 끝까지 담당한다. 복잡한 판단이 필요한 시점에만 advisor를 호출하고, advisor의 계획이나 수정 신호를 받아 실행을 재개한다. advisor는 도구를 직접 실행하지 않는다.

advisor가 토큰을 적게 쓰는 것도 설계의 일부다. 공식 문서에 따르면 advisor는 요청당 400-700 text token만 생성한다. 전체 출력이 아닌 짧은 계획만 반환하기 때문에, Opus를 계속 돌리는 것보다 비용이 훨씬 낮아진다.

API 페이로드 구조

공식 API 문서에서 확인한 핵심 파라미터는 세 가지다.

type: advisor_20260301 — advisor tool임을 선언하는 고정 값
name: advisor — 변경 불가 고정 값
model: claude-opus-4-7 — 현재 API 문서 기준으로 advisor로 지원되는 유일한 모델

버전 주의: Anthropic 블로그 발행 시점(2026-04-09)에는 claude-opus-4-6이 언급됐으나, 현재 공식 API 문서에서는 claude-opus-4-7만 advisor로 지원한다. 공식 문서를 우선 적용한다.

모델 페어링은 공식 문서에서 다음과 같이 명시한다.

Executor 모델	Advisor 모델
claude-haiku-4-5-20251001	claude-opus-4-7
claude-sonnet-4-6	claude-opus-4-7
claude-opus-4-6	claude-opus-4-7
claude-opus-4-7	claude-opus-4-7

한 줄로 요약하면: advisor는 항상 claude-opus-4-7이고, executor는 네 가지 중에서 선택한다.

응답 구조

advisor를 호출하면 응답에 두 가지 블록이 추가된다. server_tool_use로 advisor 호출 시작을 알리고, advisor_tool_result로 Opus의 조언이 전달된다. 공식 문서 기준 실제 응답 구조는 아래와 같다.

{"type": "server_tool_use", "id": "srvtoolu_abc123", "name": "advisor", "input": {}}

결과:

{
  "type": "advisor_tool_result",
  "content": {
    "type": "advisor_result",
    "text": "어드바이저의 조언 텍스트"
  }
}

이 advisor_tool_result 블록을 멀티턴 대화에서 반드시 보존해야 한다는 점이 중요하다. 이 내용은 섹션 7(트러블슈팅)에서 다시 다룬다.

3. 벤치마크 — 실제로 얼마나 좋아졌나

SWE-bench Multilingual

Anthropic 공식 블로그에서 공개한 수치다.

"Sonnet with Opus as an advisor showed a 2.7 percentage point increase on SWE-bench Multilingual over Sonnet alone, while reducing cost per agentic task by 11.9%."

(해석) Opus를 advisor로 쓴 Sonnet은 SWE-bench Multilingual에서 Sonnet 단독 대비 2.7%p 성능 향상을 기록했으며, 에이전트 작업당 비용은 11.9% 줄었다.

이 수치가 의미하는 바는 단순하지 않다. 성능을 올리면서 비용도 줄였다 — 보통은 둘 중 하나를 포기해야 하는 트레이드오프를 Advisor Strategy가 동시에 해소했다는 점이다. 공식 블로그 본문에는 2.7%p와 11.9%만 명시되며, 세부 점수(74.8%/72.1%)는 커뮤니티 소스(decodethefuture.org)에서 확인된 수치다.

측정 조건도 확인할 필요가 있다. 공식 블로그에 따르면 Sonnet 4.6 단독 측정에는 adaptive thinking이 사용됐고, Sonnet 4.6 + Advisor 조합에는 thinking을 비활성화한 권장 시스템 프롬프트가 적용됐다. 비교 전제를 이해하고 적용하는 것이 중요하다.

BrowseComp

코딩 외 영역의 수치도 주목할 만하다. 공식 블로그에 따르면:

"Haiku with an Opus advisor reached 41.2% on BrowseComp—more than double its standalone 19.7% score."

(해석) Opus를 advisor로 쓴 Haiku는 BrowseComp에서 41.2%를 기록했다 — 단독 점수 19.7%의 두 배 이상이다.

Haiku 단독 19.7%에서 Haiku+Opus advisor 41.2%로 2배 이상 뛰었다. 이 조합은 Sonnet 단독 대비 성능이 29% 낮지만 비용은 85% 낮다는 점도 같은 출처에서 확인된다.

결국 용도가 갈린다. 코딩·버그 수정이면 Sonnet+Opus. 웹 탐색처럼 Haiku로 처리 가능하지만 판단이 필요한 작업이라면 Haiku+Opus가 비용 절감폭이 훨씬 크다.

Terminal-Bench 2.0

터미널 작업 벤치마크에서도 공식 블로그에 따르면 Sonnet과 Haiku executor 모두 Opus advisor 페어링 시 성능이 향상됐다. 89개 태스크, 5회 평균 측정 기준이다.

실 사용 사례 — Eve Legal

벤치마크 외에 실 고객 사례도 공개됐다. Anthropic 공식 블로그에 수록된 Eve Legal 사례다.

"On structured document extraction tasks, the advisor tool enables Haiku 4.5 to dynamically scale intelligence by consulting Opus 4.6 as complexity demands, matching frontier-model quality at 5× lower cost." — Anuraj Pandey, Machine Learning Engineer, Eve Legal

(해석) 구조화 문서 추출 작업에서 advisor 도구는 Haiku 4.5가 복잡도에 따라 Opus 4.6에 자문을 구하며 지능을 동적으로 확장할 수 있게 해준다. 그 결과 프론티어 모델 수준의 품질을 5배 낮은 비용으로 달성했다. — Anuraj Pandey, Machine Learning Engineer, Eve Legal

구조화 문서 추출 작업에서 Haiku 4.5가 Opus를 advisor로 활용해 프론티어 모델 수준의 품질을 5배 낮은 비용으로 달성했다는 사례다. 인용문은 당시 Opus 4.6 기준이며, 현재 API에서는 Opus 4.7이 advisor로 지원된다.

4. 공식 API 사용법 — Python SDK · TypeScript SDK · curl 예시

베타 헤더 필수 설정

모든 요청에 anthropic-beta: advisor-tool-2026-03-01 헤더를 포함해야 한다. Python SDK에서는 betas=["advisor-tool-2026-03-01"]로 전달한다. 공식 문서에서 확인된 필수 요구사항이다.

베타 헤더 누락 시 API 호출이 실패한다. 현재 GA(정식 출시) 상태가 아니므로, 모든 요청에 반드시 베타 헤더를 포함해야 한다.

공식 권장 시스템 프롬프트

공식 문서는 코딩 작업에서 advisor를 효과적으로 쓰기 위한 시스템 프롬프트 작성 지침을 제공한다. 핵심은 실질적 작업 착수 전에 advisor를 호출하도록 executor에게 지시하는 것이다.

"Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption."

(해석) 실질적인 작업에 착수하기 전에 advisor를 호출하라 — 코드를 쓰기 전, 해석을 확정하기 전, 가정 위에 구현을 쌓기 전에.

글 쓰기 전, 해석을 확정하기 전, 가정 위에 구현을 쌓기 전 — 이 세 시점이 advisor 호출의 최적 타이밍이다.

advisor 출력 토큰을 35-45% 줄이는 팁도 공식 문서에 나와 있다. 시스템 프롬프트에 다음 지시를 추가하면 된다.

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

Python SDK 최소 동작 예시

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",      # executor 모델
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],  # 베타 헤더 필수
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",          # 변경 불가 고정값
            "model": "claude-opus-4-7", # advisor 모델
        }
    ],
    messages=[{"role": "user", "content": "Build a concurrent worker pool in Go with graceful shutdown."}],
)
print(response.content)

TypeScript SDK 최소 동작 예시

공식 문서에 수록된 TypeScript SDK 예시다. Python SDK와 구조는 동일하며, client.beta.messages.create()에 betas 배열을 함께 전달한다.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function main() {
  const response = await client.beta.messages.create({
    model: "claude-sonnet-4-6",   // executor 모델
    max_tokens: 4096,
    betas: ["advisor-tool-2026-03-01"],  // 베타 헤더 필수
    tools: [
      {
        type: "advisor_20260301",
        name: "advisor",          // 변경 불가 고정값
        model: "claude-opus-4-7"  // advisor 모델
      }
    ],
    messages: [
      {
        role: "user",
        content: "Build a concurrent worker pool in Go with graceful shutdown."
      }
    ]
  });

  console.log(response);
}

main().catch(console.error);

Python SDK 멀티턴 완전 예시

공식 문서에 수록된 멀티턴 예시다. Go 워커 풀 구현을 요청하고, 이어서 추가 제약을 붙이는 시나리오다.

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

# 멀티턴: assistant 응답 전체를 히스토리에 추가 (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,
)

response.content 전체를 messages에 추가하는 부분이 핵심이다. advisor_tool_result 블록을 빠뜨리면 다음 요청에서 400 에러가 발생한다.

curl 예시

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: advisor-tool-2026-03-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 4096,
    "tools": [
      {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-7"
      }
    ],
    "messages": [
      {"role": "user", "content": "작업 내용을 입력하세요"}
    ]
  }'

max_uses와 캐싱 설정

max_uses 파라미터로 요청당 advisor 호출 횟수를 제한할 수 있다. 공식 문서에 따르면 초과 시 advisor_tool_result_error와 함께 max_uses_exceeded 에러 코드가 반환되며, executor는 advisor 없이 계속 실행된다. 이 제한은 요청 단위(per-request)이며, 대화(conversation) 전체에 걸친 cap은 별도로 존재하지 않는다.

대화 수준에서 advisor 호출을 제한하려면 클라이언트 쪽에서 직접 카운트해야 한다. 공식 문서에 따르면 한도에 도달한 시점에 tools 배열에서 advisor를 제거하고, 메시지 히스토리에서 advisor_tool_result 블록도 함께 제거해야 한다. advisor_tool_result 블록을 남긴 채 advisor를 tools에서 제거하면 400 에러가 발생한다.

같은 advisor를 여러 번 호출하는 시나리오라면 캐싱이 비용을 줄여준다. 공식 문서에서 확인된 설정이다. ttl은 "5m"(5분)과 "1h"(1시간) 두 값을 지원하며, 기본값은 "5m"이다. tools 배열의 advisor 정의 안에 추가한다.

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

캐시 쓰기 비용이 읽기 절감보다 크므로, 대략 3회 이상 호출하는 시나리오에서 손익분기점에 도달한다. 단, extended thinking을 활성화하는 경우 clear_thinking 설정과의 상호작용에 주의가 필요하다. clear_thinking의 keep 값이 "all"이 아닌 경우 advisor 쪽에서 매 턴 캐시 미스가 발생해 비용이 늘어난다. extended thinking을 별도 설정 없이 활성화하면 API 기본값(keep: {type: "thinking_turns", value: 1})이 이 문제를 자동으로 유발한다. keep: "all"로 설정하면 advisor 캐시 안정성이 유지된다.

토큰 사용량 추적 — 비용 계산 가이드

공식 문서에 따르면 top-level usage 필드는 executor 토큰만 반영한다. advisor 토큰은 top-level usage에 합산되지 않으며, usage.iterations 배열에서 별도로 확인한다. 실제 비용 계산 시에는 두 모델의 청구 요금이 다르므로 iterations를 반드시 분리해서 집계해야 한다.

usage.iterations 배열의 각 항목은 다음과 같이 구분된다.

{
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 850,
    "iterations": [
      {
        "type": "message",
        "input_tokens": 1200,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 120
      },
      {
        "type": "advisor_message",
        "input_tokens": 4800,
        "cache_read_input_tokens": 3200,
        "cache_creation_input_tokens": 0,
        "output_tokens": 95
      },
      {
        "type": "message",
        "input_tokens": 1350,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 730
      }
    ]
  }
}

type: "message"는 executor(Sonnet/Haiku) 요금으로, type: "advisor_message"는 advisor(Opus) 요금으로 별도 청구된다. top-level input_tokens는 executor의 첫 번째 iteration만 반영한다는 점에 주의한다. Batch processing을 사용하는 경우 usage.iterations는 아이템별로 보고된다.

실전에서 흔한 실수는 top-level usage.output_tokens만 보고 advisor 비용을 누락하는 것이다. 위 예시에서 advisor_message의 output_tokens(95)는 Opus 요금으로 별도 산정되므로, 비용 대시보드에서 iterations를 집계하지 않으면 실제 비용을 과소 추정하게 된다. advisor_message가 예상보다 많이 찍힌다면 max_uses 파라미터로 요청당 advisor 호출 횟수에 상한을 두는 것이 비용 통제의 첫 번째 수단이다.

5. advisor-opus 플러그인 설치 및 사용법

플러그인 개요

advisor-opus는 Claude Code에서 Advisor Strategy를 슬래시 커맨드로 쓸 수 있게 만든 커뮤니티 플러그인이다. MIT 라이선스로 공개되어 있다.

Deprecated 상태: GitHub README에 명시된 내용이다: "Claude Code에 /advisor 기능이 공식 출시(혹은 출시 예정)되어, 이 플러그인은 deprecated 되었습니다. 이 플러그인이 제공하던 Advisor 패턴이 Claude Code에 네이티브로 내장됩니다. 공식 기능을 사용하세요: Claude Code 세션에서 /advisor를 입력하면 됩니다. 다만, 이 플러그인은 skill 호출 시점을 직접 커스터마이즈할 수 있어 여전히 유용합니다. Repo는 계속 유지되며, 설치하여 사용할 수 있습니다."

Claude Code /advisor — Experimental 상태 (v2.1.117, 2026-04-22 기준): Claude Code changelog에 따르면 내장 /advisor 기능은 현재 GA(정식 출시)가 아닌 experimental 상태다. "Advisor Tool (experimental)" 레이블이 붙어 있으며 세션 시작 시 startup notification이 표시된다. 운영 환경 도입 전 experimental 상태임을 고려해야 한다.

설치 3단계

GitHub README에서 확인한 설치 절차다.

# 1. 마켓플레이스에서 플러그인 추가
/plugin marketplace add shalomeir/advisor-opus

# 2. 플러그인 설치
/plugin install advisor-opus@advisor-opus

# 3. 플러그인 리로드
/reload-plugins

ex)

> /plugin marketplace add shalomeir/advisor-opus

> /plugin install advisor-opus@advisor-opus

> /reload-plugins

제공 커맨드 3종

플러그인 README에 따르면 세 가지 커맨드가 있다.

커맨드	역할
`/advisor-opus:plan`	작업 시작 전 전략적 계획 수립 — end state, critical path, risks, next steps
`/advisor-opus:advise`	아키텍처·방향 결정 시 두 번째 의견 (second opinion)
`/advisor-opus:review`	커밋 전 정확성·보안 검토

한 줄 요약: plan은 시작 전, advise는 방향이 헷갈릴 때, review는 커밋 직전에 쓴다.

자동 호출 로직과 모델 추천

플러그인은 호출 타이밍도 정의해 놨다. README에 따르면 PLANNING(복잡 작업 전), COMPLETION(코드 작성 후 커밋 전), PIVOT/REACTIVE(방향 전환이나 막혔을 때) 세 시점이 기준이다. 복잡한 작업당 최대 2회(최대 4회 수준), 단순 작업은 건너뛴다.

executor 모델별 추천도 같은 문서에서 명확하다.

Executor	추천 여부	이유
Haiku	강력 추천	지능 격차가 커서 Opus 조언의 효과가 극대화됨
Sonnet	추천	비용과 의미 있는 Opus 조언 사이 균형점
Opus	비추천	지능 이점 없음, 자동 호출 비활성화

v0.2.0 변경 사항

2026-04-10 출시된 v0.2.0에서 공식 Advisor Tool 모범 사례에 맞춰 플러그인을 전면 재작성했다. 출력 제한도 150단어에서 100단어로 축소됐다. 공식 API의 "100단어 이내" 권장 지침을 반영한 변경이다.

6. 사용 시나리오별 선택 가이드

시나리오 A — API를 직접 통합하는 개발자

자체 에이전트 프레임워크를 Python이나 TypeScript로 구축 중이라면 공식 Advisor Tool API가 적합하다. client.beta.messages.create()에 advisor tool을 추가하고, betas=["advisor-tool-2026-03-01"]을 붙이면 기존 코드를 크게 수정하지 않고 붙일 수 있다.

이 시나리오에서는 max_uses 설정으로 비용을 통제하는 것이 중요하다. advisor가 무제한 호출되면 Opus 비용이 예상보다 커질 수 있다. 3회 이상 호출이 예상되는 플로우라면 캐싱(ttl: "5m")을 함께 적용한다.

공식 문서에 따르면 비용 최적화 조합도 참고할 만하다. Sonnet executor에 medium effort를 적용하고 Opus advisor를 붙이면 Sonnet default effort와 유사한 지능을 더 낮은 비용으로 달성할 수 있다. 최대 지능이 필요하다면 executor를 default effort로 유지한다.

시나리오 B — Claude Code에서 바로 써보고 싶은 개발자

코드를 작성하지 않고 Advisor Strategy를 경험해보고 싶다면 두 가지 선택지가 있다.

Claude Code 내장 /advisor 커맨드 — v2.1.117 기준 experimental 상태. 별도 설치 없이 바로 사용 가능하나, 정식 출시 전 기능임을 감안한다.
advisor-opus 플러그인 — deprecated됐지만, 호출 타이밍(plan/advise/review)을 수동으로 제어하고 싶을 때 유용.

Claude Code /advisor — Experimental (v2.1.117, 2026-04-22): Claude Code changelog에서 확인된 상태다. "Advisor Tool (experimental)" 레이블이 붙어 있으며, 이전 버전에서 'Advisor tool result content could not be processed' 버그가 수정된 이력이 있다. GA 이전 기능이므로 운영 환경 도입 시 주의가 필요하다.

executor로 Haiku를 쓰는 경우라면 플러그인의 효과가 가장 크다. advisor-opus README에 따르면 Haiku+Opus 조합에서 "지능 격차가 최대화"되어 Opus 조언의 효과가 극대화된다.

언제 Advisor Strategy를 쓰지 않는가

모든 작업에 advisor를 붙이는 것이 항상 유리한 것은 아니다. 공식 문서는 advisor가 적합하지 않은 케이스를 명시한다.

단순 one-shot Q&A — 계획할 것이 없는 단일 턴 요청에는 advisor 오버헤드가 태스크 복잡도를 초과해 비용만 늘어난다.
pass-through model picker — 사용자가 직접 비용·품질 트레이드오프를 선택하는 구조라면 advisor를 끼워 넣어도 의미가 없다. 사용자가 이미 원하는 모델을 선택한 상황이다.
Opus를 executor로 쓰는 경우 — advisor도 Opus이므로 지능 이점이 없다. advisor-opus 플러그인도 이 경우 자동 호출을 비활성화한다.
모든 턴이 advisor 수준 역량을 필요로 하는 워크로드 — executor와 advisor의 역할 분리보다 처음부터 Opus 단독으로 실행하는 편이 낫다.

7. 베타 제한사항 · 트러블슈팅 Q&A

베타 주의사항

Advisor Tool은 현재 베타 상태다(2026-04-24 기준). GA(정식 출시)되지 않았으므로 프로덕션 도입 시 다음 사항을 고려한다.

베타 헤더(advisor-tool-2026-03-01)는 GA 시 변경될 수 있다.
스트리밍 사용 시: advisor sub-inference는 스트리밍되지 않는다. 공식 문서에 따르면 advisor 실행 중 executor 스트림이 일시 중단되며, 약 30초마다 SSE keepalive가 전송된다. 단, advisor 호출이 짧을 경우 ping이 전혀 없을 수 있다.
모델 페어링은 현재 Opus 4.7(advisor)로 고정된다.
ZDR(Zero Data Retention) 계약이 있는 조직은 advisor tool도 ZDR 적용 대상이다.

추가 제한사항 (v2026-04-24 기준 신규 확인)

공식 문서에서 새로 확인된 제한사항 3가지다.

clear_tool_uses 미완전 지원 (임시): clear_tool_uses는 아직 advisor tool blocks와 완전히 호환되지 않는다. 향후 릴리즈에서 지원 예정이다.
Priority Tier 모델별 적용: Anthropic Priority Tier는 모델별로 적용된다. executor에 Priority Tier가 설정되어 있어도 advisor에는 자동으로 적용되지 않는다. advisor 모델에도 별도로 Priority Tier를 설정해야 한다.
max_tokens executor 전용: top-level max_tokens는 executor output에만 적용된다. advisor 토큰 출력은 별도로 제어되지 않는다.

에러 코드 6종과 대처법

공식 문서에서 확인한 에러 코드와 대처법이다.

에러 코드	원인	대처법
`max_uses_exceeded`	요청당 advisor 호출 한도 초과	`max_uses` 값을 높이거나, 호출 빈도를 줄인다
`too_many_requests`	레이트 제한	재시도 로직(exponential backoff) 적용
`overloaded`	API 서버 용량 초과	일시적 현상, 재시도
`prompt_too_long`	트랜스크립트가 advisor 모델 컨텍스트 초과	히스토리를 줄이거나 대화를 분리
`execution_time_exceeded`	타임아웃	태스크를 더 작은 단위로 분리
`unavailable`	advisor 모델 일시 불가	재시도, 지속 시 Anthropic 지원 문의

6가지 에러 중 실무에서 가장 빈번한 것은 advisor_tool_result 블록 누락으로 인한 invalid_request_error(아래 Q&A에서 별도 다룸)와 max_uses_exceeded이며, 나머지 4종은 일시적 서버 상태에 의한 것이므로 exponential backoff 재시도로 대부분 해결된다.

Q&A

Q. 멀티턴 대화에서 400 에러가 발생한다.

공식 문서에 따르면 advisor_tool_result 블록을 포함한 assistant 응답 전체를 다음 턴의 메시지 히스토리에 추가해야 한다. 이 블록을 빠뜨린 채 요청하거나, tools 목록에서 advisor를 제거한 상태로 히스토리에 advisor_tool_result가 남아있으면 400 invalid_request_error가 발생한다.

Q. beta header를 어떻게 정확히 설정하는가?

Python SDK: betas=["advisor-tool-2026-03-01"]

TypeScript SDK: betas: ["advisor-tool-2026-03-01"]

curl: -H "anthropic-beta: advisor-tool-2026-03-01"

Q. advisor 호출 횟수를 어떻게 추적하는가?

응답의 usage.iterations 배열에서 type: "advisor_message" 항목 수를 세면 된다. top-level usage는 executor 첫 번째 iteration의 input_tokens만 반영하므로 advisor 비용 산출 시에는 반드시 iterations를 분리해서 집계해야 한다.

Q. 스트리밍 연결이 끊기는 것처럼 느껴진다.

공식 문서에 따르면 advisor 실행 중 스트림이 멈추는 것은 정상 동작이다. SSE keepalive는 약 30초마다 전송되나, advisor 호출이 짧은 경우 ping이 전혀 없을 수 있다. advisor 완료 후 advisor_tool_result는 delta 없이 단일 content_block_start 이벤트로 한 번에 도착한다. 클라이언트 타임아웃을 충분히 (30초 이상) 설정한다.

8. 도입 플레이북

Advisor Strategy를 처음 도입한다면 단계적 접근이 현실적이다.

오늘 (탐색)

Claude Code를 쓰고 있다면 내장 /advisor 커맨드로 패턴을 먼저 경험한다. 현재 experimental 상태이므로 프로덕션 적용 전 충분히 테스트하는 것을 권장한다. advisor-opus 플러그인은 /plugin marketplace add shalomeir/advisor-opus 한 줄로 설치하고 /advisor-opus:plan으로 시작해볼 수 있다.

이번 주 (API 통합 검증)

기존 에이전트 워크플로의 복잡한 판단 단계를 특정한다. Python 또는 TypeScript SDK 예시를 참고해 client.beta.messages.create()에 advisor tool을 추가하고, max_uses=3으로 호출 횟수를 제한하며 실험한다. usage.iterations로 실제 advisor/executor 토큰을 분리해 측정한다. 비용 최적화가 목표라면 Sonnet medium effort + Opus advisor 조합도 검토한다.

운영 반영 시 체크리스트

베타 헤더 명시 (advisor-tool-2026-03-01)
<code style="background: #f4f4f4; padding: 2px 6px; border-radius: 4px;

저작자표시 비영리 변경금지 (새창열림)

'AI > Claude' 카테고리의 다른 글

Claude Code 4월 업데이트(v2.1.89~126 업데이트) 정리 (1)	2026.05.06
Claude Opus 4.7 설정 최적화 - 달라진 것, 주의할 것, 지금 바꿀 것 (effort 레벨부터 Extended Thinking 등) (18)	2026.04.26
Claude Code 'ultrareview'란 : 멀티 에이전트 코드 리뷰, 어떻게 작동하나 - 회당 $5~$20 추가 과금은 합리적 일까 (2)	2026.04.24
Claude Code 'Claude Design이란?' 리뷰(1) : Figma 대체재인가, 보완재인가 - 디자인 시스템 설정부터 Claude Code 핸드오프까지 (1)	2026.04.23
Claude Code 신기능 'Ultraplan' 리뷰 - 터미널 멈춤 없는 클라우드 플래닝(로컬 Plan Mode vs 클라우드 플래닝) (1)	2026.04.09

Contents