AI/Claude

Claude Advisor 전략: Opus를 조언자로 활용해 Sonnet의 지능을 끌어올리기

반응형
Claude Advisor 전략: Opus를 조언자로 활용해 Sonnet의 지능을 끌어올리기

ANTHROPIC ADVISOR STRATEGY

Claude Advisor 전략:
Opus를 조언자로 활용해
Sonnet의 지능을 끌어올리기

비용은 줄이고 성능은 올리는 차세대 AI 에이전트 아키텍처

2026년 4월 12일 · 읽기 약 12분

1. Advisor Tool이란?

2026년 3월, Anthropic이 공식적으로 발표한 Advisor Tool은 AI 에이전트 개발 패러다임을 근본적으로 바꾸는 혁신적인 기능입니다. 핵심 아이디어는 매우 직관적입니다. 빠르고 저렴한 모델이 실행자로서 전체 작업을 수행하되, 중요한 전략적 판단이 필요할 때만 더 똑똑한 모델에게 조언을 구하는 구조입니다. 마치 현실 세계에서 주니어 개발자가 복잡한 설계 결정이 필요할 때 시니어 아키텍트에게 자문을 구하는 것과 정확히 같은 패턴입니다.

전통적인 멀티모델 아키텍처에서는 비싼 모델이 오케스트레이터로 전체를 조율하고, 저렴한 모델들이 하위 작업을 수행했습니다. Advisor Tool은 이 구조를 완전히 뒤집습니다. 저렴한 모델인 Claude Sonnet이나 Haiku가 처음부터 끝까지 작업의 주도권을 가지고, Opus는 필요할 때만 짧은 조언을 제공하고 빠져나갑니다. 이 조언은 보통 400에서 700개의 텍스트 토큰 정도로, 전체 최종 출력을 생성하는 것보다 훨씬 적은 양입니다.

💡 TIP: Advisor Tool은 현재 베타 단계이며, API 요청 시 advisor-tool-2026-03-01 베타 헤더를 포함해야 합니다. 접근 권한이나 피드백은 Anthropic 어카운트 팀에 문의하세요.
Claude Advisor Tool의 전체 아키텍처 흐름도

▲ Claude Advisor Tool의 전체 아키텍처 흐름도

위 다이어그램에서 볼 수 있듯이, 전체 과정은 단일 API 요청 내에서 이루어집니다. 사용자가 복잡한 태스크를 요청하면 Executor인 Sonnet이 먼저 상황을 파악하고, 전략적 판단이 필요하다고 스스로 판단할 때 Advisor인 Opus를 호출합니다. Opus는 전체 대화 히스토리를 보고 전략적 조언을 생성하며, Sonnet은 이 조언을 반영하여 최종 결과를 완성합니다. 클라이언트 측에서 추가 왕복 요청은 전혀 필요 없습니다.

2. 왜 이런 구조가 필요한가

대규모 언어 모델을 실제 프로덕션에 배포할 때 가장 큰 고민은 항상 비용과 성능의 균형입니다. Opus 같은 최상위 모델을 모든 요청에 사용하면 비용이 폭발적으로 증가합니다. 반대로 Haiku 같은 경량 모델만 사용하면 복잡한 태스크에서 품질이 크게 떨어집니다. Advisor Tool은 이 딜레마에 대한 Anthropic의 공식 해답입니다.

실제로 코딩 에이전트나 멀티스텝 리서치 파이프라인 같은 장기 워크로드에서, 대부분의 턴은 기계적인 반복 작업입니다. 파일을 읽고, 코드를 수정하고, 테스트를 실행하는 일들이죠. 이런 작업에 Opus급 지능이 매번 필요한 것은 아닙니다. 하지만 전체 설계 방향을 정하거나, 복잡한 버그의 근본 원인을 파악할 때는 확실히 더 높은 지능이 필요합니다. Advisor Tool은 바로 이 지점을 정확히 공략합니다.

현재 Sonnet으로 복잡한 태스크를 처리하는 경우

Opus를 Advisor로 추가하면 비슷하거나 더 낮은 총 비용으로 품질이 향상됩니다. SWE-bench 기준 2.7%p 향상에 비용은 11.9% 절감되는 놀라운 결과가 나왔습니다.

Haiku로 운영하면서 지능을 높이고 싶은 경우

Opus를 Advisor로 추가하면 Haiku 단독 대비 비용은 올라가지만, Executor를 Sonnet으로 통째로 교체하는 것보다는 훨씬 저렴합니다. BrowseComp에서 Haiku 단독 19.7%가 41.2%로 2배 이상 뛰었습니다.

Advisor가 적합하지 않은 경우

단일 턴 질의응답처럼 계획이 필요 없는 작업, 사용자가 직접 모델을 선택하는 패스스루 구조, 또는 매 턴마다 Advisor급 전체 능력이 필요한 워크로드에는 적합하지 않습니다.

3. 아키텍처 작동 원리

전체 요청 흐름 구조도

sequenceDiagram
    participant U as 👤 사용자
    participant C as 🖥️ 클라이언트
    participant E as ⚡ Executor
(Sonnet 4.6) participant S as 🌐 Anthropic 서버 participant A as 🧠 Advisor
(Opus 4.6) U->>C: 복잡한 태스크 요청 C->>S: POST /v1/messages
tools: [advisor_20260301] S->>E: Executor 추론 시작 Note over E: 탐색적 작업 수행
(파일 읽기, 구조 파악) E->>S: server_tool_use
name: "advisor", input: {} S->>A: 전체 트랜스크립트 전달
(시스템 프롬프트 + 도구 정의 + 전체 대화) Note over A: 전략적 분석
(400~700 토큰 조언 생성) A->>S: advisor_result
"채널 기반 패턴을 사용하세요..." S->>E: advisor_tool_result 전달 Note over E: 조언 반영하여
최종 결과 생성 E->>S: 최종 응답 완성 S->>C: 전체 응답 반환
(text + server_tool_use + advisor_tool_result + text) C->>U: 결과 표시

▲ Advisor Tool 시퀀스 다이어그램 — 단일 API 요청 내에서 모든 과정이 완료됩니다

Executor ↔ Advisor 역할 분리 구조

flowchart TB
    subgraph CLIENT["🖥️ 클라이언트 (사용자 코드)"]
        REQ["API 요청 전송
model: sonnet-4.6
tools: [advisor, web_search, ...]"] RES["응답 수신 & 처리
advisor_tool_result 포함
다음 턴에 그대로 전달"] end subgraph SERVER["🌐 Anthropic 서버 (단일 요청 내)"] direction TB subgraph EXEC["⚡ Executor (Sonnet 4.6)"] E1["도구 호출 & 반복 작업"] E2["코드 작성 & 테스트"] E3["최종 출력 생성"] end subgraph ADV["🧠 Advisor (Opus 4.6)"] A1["전략적 계획 수립"] A2["에러 원인 분석"] A3["방향 전환 제안"] end E1 -->|"전략 판단 필요"| ADV ADV -->|"400~700 토큰 조언"| E2 E2 --> E3 end REQ --> SERVER SERVER --> RES style CLIENT fill:#1e1b4b,stroke:#6d28d9,color:#f1f5f9 style EXEC fill:#0d3320,stroke:#3fb950,color:#f1f5f9 style ADV fill:#2d1b69,stroke:#bc8cff,color:#f1f5f9 style SERVER fill:#0f172a,stroke:#334155,color:#f1f5f9

▲ Executor(실행)와 Advisor(조언) 역할 분리 아키텍처

Advisor Tool의 내부 작동 방식을 정확히 이해하는 것이 핵심입니다. 일반적인 도구 호출과 비슷하게 동작하지만, 서버 사이드에서 완전히 자동화되는 점이 다릅니다. Executor 모델이 tools 배열에 advisor가 포함되어 있으면, 다른 도구와 마찬가지로 스스로 호출 시점을 결정합니다.

첫째, Executor가 server_tool_use 블록을 방출합니다. 이때 name: advisor이고 input은 항상 빈 객체입니다. Executor가 타이밍을 결정하지만, 실제 컨텍스트는 서버가 자동으로 공급합니다. 둘째, Anthropic 서버가 Advisor 모델로 별도의 추론 패스를 실행합니다. 이때 Advisor는 시스템 프롬프트, 모든 도구 정의, 모든 이전 턴, 모든 도구 결과를 볼 수 있습니다. 셋째, Advisor의 응답이 advisor_tool_result 블록으로 Executor에게 반환됩니다. 마지막으로, Executor가 이 조언을 반영하여 나머지 생성을 계속합니다.

⚠ 주의: Advisor는 도구 접근 권한이 없고, 컨텍스트 관리도 하지 않습니다. Thinking 블록은 결과 반환 전에 제거되며, 오직 조언 텍스트만 Executor에게 전달됩니다.

4. 실전 코드: Python SDK

실제로 Advisor Tool을 코드에서 구현하는 방법을 살펴보겠습니다. Python SDK를 사용하면 매우 간결하게 구현할 수 있습니다. 핵심은 betas 파라미터에 베타 헤더를 명시하고, tools 배열에 advisor 도구 정의를 추가하는 것입니다.

Python SDK를 사용한 Advisor Tool 설정 코드

▲ Python SDK를 사용한 Advisor Tool 설정 코드

위 코드에서 확인할 수 있듯이, 3가지 핵심 요소만 추가하면 됩니다. type은 반드시 advisor_20260301이어야 하고, nameadvisor여야 합니다. 그리고 model 필드에 Advisor로 사용할 모델을 지정합니다. 현재는 claude-opus-4-6만 Advisor로 지원됩니다.

import 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-6",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Go로 graceful shutdown이 가능한 동시성 워커 풀 구현해줘",
        }
    ],
)

print(response)

5. 실전 코드: curl API 호출

SDK 없이 직접 HTTP API를 호출하는 방법도 알아두면 유용합니다. 디버깅할 때나, 다른 언어에서 직접 HTTP 클라이언트를 사용할 때 참고할 수 있습니다. 중요한 것은 anthropic-beta 헤더에 advisor-tool-2026-03-01을 반드시 포함해야 한다는 점입니다.

curl을 사용한 Advisor Tool API 직접 호출 예시

▲ curl을 사용한 Advisor Tool API 직접 호출 예시

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: advisor-tool-2026-03-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 4096,
    "tools": [{
      "type": "advisor_20260301",
      "name": "advisor",
      "model": "claude-opus-4-6"
    }],
    "messages": [{"role": "user",
      "content": "복잡한 멀티스텝 코딩 작업을 수행해줘"}]
  }' 

TypeScript, Go, C#, PHP, Ruby 등 다양한 언어의 공식 SDK에서도 동일한 패턴으로 사용 가능합니다. 각 언어별 구현 코드는 Anthropic 공식 문서에서 확인할 수 있습니다.

6. 응답 구조 상세 분석

Advisor Tool을 호출하면 응답 구조가 일반적인 메시지와 다릅니다. Assistant의 content 배열 안에 여러 타입의 블록이 순서대로 들어옵니다. 먼저 일반 텍스트 블록이 오고, 그 뒤에 server_tool_use 블록, advisor_tool_result 블록, 그리고 다시 조언을 반영한 텍스트 블록이 이어집니다.

Advisor Tool 응답 JSON의 실제 구조

▲ Advisor Tool 응답 JSON의 실제 구조

advisor_tool_resultcontent 필드는 두 가지 변형이 있습니다. advisor_result 타입은 text 필드에 사람이 읽을 수 있는 조언이 담깁니다. advisor_redacted_result 타입은 encrypted_content 필드에 암호화된 블롭이 담기며, 다음 턴에서 서버가 복호화하여 Executor의 프롬프트에 평문으로 렌더링합니다. 두 경우 모두 후속 턴에서는 해당 컨텐츠를 그대로 전달해야 합니다.

💡 TIP: server_tool_useinput은 항상 빈 객체입니다. Executor가 input에 무엇을 넣든 Advisor에게는 전달되지 않습니다. 서버가 전체 트랜스크립트에서 자동으로 컨텍스트를 구성합니다.

7. 모델 호환성 매트릭스

Advisor Tool에서 Executor와 Advisor 모델의 조합에는 제약이 있습니다. 핵심 규칙은 Advisor가 Executor보다 같거나 더 높은 능력의 모델이어야 한다는 것입니다. 유효하지 않은 조합을 요청하면 API가 400 invalid_request_error를 반환하며, 지원되지 않는 조합을 명시해줍니다.

Advisor Tool 모델 호환성 매트릭스 — 지원/미지원 조합 한눈에 보기

▲ Advisor Tool 모델 호환성 매트릭스 — 지원/미지원 조합 한눈에 보기

현재 지원되는 유효한 조합은 3가지입니다. Haiku 4.5를 Executor로, Opus 4.6을 Advisor로 사용하는 조합, Sonnet 4.6을 Executor로, Opus 4.6을 Advisor로 사용하는 조합, 그리고 Opus 4.6을 양쪽 모두에 사용하는 조합입니다. Sonnet이 Advisor가 되거나 Haiku가 Advisor가 되는 조합은 지원되지 않습니다. 이는 Advisor가 전략적 우위를 제공해야 하므로 당연한 제약입니다.

8. 벤치마크 성능 비교

Anthropic이 공개한 초기 벤치마크 결과는 매우 인상적입니다. 특히 Sonnet과 Opus 조합의 결과가 놀라운데, 비용은 줄이면서 성능은 올리는 마법 같은 결과를 보여줍니다.

Advisor Tool 벤치마크 성능 비교 — SWE-bench, BrowseComp 기준

▲ Advisor Tool 벤치마크 성능 비교 — SWE-bench, BrowseComp 기준

Sonnet + Opus 조합은 SWE-bench Multilingual에서 Sonnet 단독 대비 2.7%p 향상된 74.8%를 달성했으며, 놀랍게도 태스크당 비용은 11.9% 절감되었습니다. 성능이 올라가면서 비용까지 줄어드는 이유는, Advisor의 전략적 조언 덕분에 Executor가 불필요한 시행착오를 줄여 전체 도구 호출 횟수와 대화 길이가 단축되기 때문입니다.

Haiku + Opus 조합은 BrowseComp에서 Haiku 단독 19.7%에서 41.2%로 2배 이상 성능이 뛰어올랐습니다. Sonnet 단독 대비 85% 저렴한 비용으로 이 성능을 달성한 것입니다. 물론 Sonnet 단독의 49%보다는 낮지만, 비용 대비 성능 비율은 압도적입니다.

⚠ 주의: 벤치마크 결과는 태스크에 따라 다를 수 있습니다. 반드시 자신의 워크로드에서 직접 평가한 후 도입 결정을 내리세요.

9. 멀티턴 대화 구현

실제 에이전트를 구현할 때는 멀티턴 대화가 필수적입니다. Advisor Tool을 멀티턴으로 사용할 때 가장 중요한 규칙은, advisor_tool_result 블록을 포함한 전체 assistant 컨텐츠를 그대로 다음 턴에 전달해야 한다는 것입니다. 이를 생략하거나 수정하면 API가 오류를 반환합니다.

멀티턴 대화에서 advisor_tool_result를 유지하는 코드

▲ 멀티턴 대화에서 advisor_tool_result를 유지하는 코드

# 멀티턴 대화에서 Advisor 활용
messages = [{"role": "user", "content": "Go 워커 풀 구현해줘"}]

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": "max-in-flight 제한 10개 추가해줘"})

response2 = client.beta.messages.create(
    model="claude-sonnet-4-6", max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools, messages=messages,
)
⚠ 주의: 후속 턴에서 advisor tool을 tools 배열에서 제거하면서 메시지 히스토리에 advisor_tool_result 블록이 남아있으면 400 invalid_request_error가 발생합니다. 도구를 제거할 때는 반드시 히스토리에서도 해당 블록을 함께 제거하세요.

10. 비용 구조 이해하기

비용 흐름 구조도

flowchart LR
    subgraph REQ["단일 API 요청"]
        direction TB
        I1["iteration 1
type: message
input: 412 | output: 89"] I2["iteration 2
type: advisor_message
model: opus-4.6
input: 823 | output: 1,612"] I3["iteration 3
type: message
input: 1,348 | output: 442"] I1 --> I2 --> I3 end subgraph BILL["💰 과금 구조"] direction TB S_RATE["⚡ Sonnet 요금
$3/M input · $15/M output"] O_RATE["🧠 Opus 요금
$15/M input · $75/M output"] end I1 -.->|"Sonnet 요금 적용"| S_RATE I2 -.->|"Opus 요금 적용"| O_RATE I3 -.->|"Sonnet 요금 적용"| S_RATE subgraph TOP["📊 usage (최상위)"] TU["input_tokens: 412
output_tokens: 531
⚠ Executor만 집계"] end REQ --> TOP style I1 fill:#0d3320,stroke:#3fb950,color:#f1f5f9 style I2 fill:#2d1b69,stroke:#bc8cff,color:#f1f5f9 style I3 fill:#0d3320,stroke:#3fb950,color:#f1f5f9 style S_RATE fill:#0d3320,stroke:#3fb950,color:#f1f5f9 style O_RATE fill:#2d1b69,stroke:#bc8cff,color:#f1f5f9 style TU fill:#1e293b,stroke:#334155,color:#cbd5e1 style REQ fill:#0f172a,stroke:#334155,color:#f1f5f9 style BILL fill:#0f172a,stroke:#334155,color:#f1f5f9 style TOP fill:#0f172a,stroke:#334155,color:#f1f5f9

▲ Advisor Tool 비용 흐름 — Executor(Sonnet)와 Advisor(Opus)가 각각 다른 요금으로 과금됩니다

Advisor Tool의 비용 구조를 정확히 이해하면 예산 책정과 비용 최적화에 큰 도움이 됩니다. 핵심은 Executor 토큰과 Advisor 토큰이 각각 다른 요금으로 과금된다는 점입니다. 응답의 usage.iterations 배열에서 각 추론 패스별 토큰 사용량을 상세히 확인할 수 있습니다.

Advisor Tool 비용 구조 — iterations 배열 상세

▲ Advisor Tool 비용 구조 — iterations 배열 상세

최상위 usage 필드는 Executor 토큰만 반영합니다. Advisor 토큰은 최상위 합계에 포함되지 않는데, 이는 다른 요금이 적용되기 때문입니다. type: advisor_message인 iteration은 Advisor 모델 요금으로 과금되고, type: message인 iteration은 Executor 모델 요금으로 과금됩니다.

Advisor의 출력은 보통 400에서 700개의 텍스트 토큰이며, 씽킹을 포함하면 총 1,400에서 1,800 토큰 정도입니다. 비용 절감의 핵심은 Advisor가 전체 최종 출력을 생성하지 않는다는 데 있습니다. 짧은 전략적 조언만 제공하고, 실제 긴 출력은 저렴한 Executor 모델이 생성합니다. 최상위 max_tokens는 Executor 출력에만 적용되며, Advisor 토큰을 제한하지 않습니다.

11. 시스템 프롬프트 전략

Advisor Tool은 기본적으로 Executor가 복잡한 태스크 시작 시와 어려움을 만났을 때 호출하도록 내장 설명이 포함되어 있습니다. 하지만 코딩이나 에이전트 태스크에서는 시스템 프롬프트로 호출 타이밍을 더 명확히 지정하면 성능이 크게 올라갑니다. Anthropic의 내부 코딩 평가에서 아래 패턴이 Sonnet 비용 수준에서 가장 높은 지능을 달성했습니다.

코딩 태스크용 Advisor 시스템 프롬프트 설정

▲ 코딩 태스크용 Advisor 시스템 프롬프트 설정

핵심은 두 가지 타이밍입니다. 첫째, 몇 번의 탐색적 읽기 후에 이루어지는 초기 첫 Advisor 호출입니다. 파일 구조를 파악하고 소스를 확인한 직후, 실제 작업을 시작하기 전에 Advisor의 전략적 가이드를 받습니다. 둘째, 어려운 태스크의 경우 파일 작성과 테스트 결과가 나온 후의 최종 확인 Advisor 호출입니다. 이 두 타이밍이 태스크당 약 2~3회의 Advisor 호출로 최적의 비용 대 성능 비율을 만들어냅니다.

Advisor 출력 길이 조절로 비용 추가 절감

Advisor 출력이 가장 큰 비용 요인이므로, 간결성 지시를 시스템 프롬프트 최상단에 추가하면 큰 효과를 볼 수 있습니다. Anthropic 내부 테스트에서 아래 한 줄로 Advisor 총 출력 토큰이 35%에서 45% 감소했으며, 호출 빈도에는 변화가 없었습니다.

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

12. 캐싱과 비용 최적화

Advisor Tool에는 두 가지 독립적인 캐싱 레이어가 있습니다. Executor 측 캐싱advisor_tool_result 블록을 다른 컨텐츠 블록과 마찬가지로 캐시할 수 있습니다. Advisor 측 캐싱은 도구 정의에서 caching 파라미터를 설정하여 활성화합니다.

Advisor 캐싱 설정 코드와 손익분기점 분석

▲ Advisor 캐싱 설정 코드와 손익분기점 분석

캐싱의 손익분기점은 약 3회입니다. 대화당 Advisor 호출이 2회 이하이면 캐시 쓰기 비용이 읽기 절감보다 크므로 캐싱을 끄는 것이 좋습니다. 3회 이상이면 캐싱을 켜는 것이 유리하며, 호출 횟수가 늘어날수록 절감 효과가 커집니다. 한 가지 주의할 점은, 대화 중간에 캐싱을 껐다 켰다 하면 캐시 미스가 발생하므로 처음에 설정하고 끝까지 유지하는 것이 좋습니다.

💡 TIP: Effort 설정과 결합하면 추가 최적화가 가능합니다. Sonnet Executor를 medium effort로, Opus Advisor와 페어링하면 default effort의 Sonnet 단독과 비슷한 지능을 더 낮은 비용으로 달성합니다.

13. 다른 도구와 결합

Advisor Tool은 다른 서버 사이드 도구 및 클라이언트 사이드 도구와 자유롭게 결합할 수 있습니다. 같은 tools 배열에 함께 추가하면 됩니다. Executor는 한 턴 안에서 웹 검색을 하고, Advisor에게 조언을 구하고, 커스텀 도구를 사용할 수 있습니다. Advisor의 전략적 계획이 다음에 어떤 도구를 사용할지 결정하는 데 영향을 미칩니다.

Advisor + Web Search + Custom Tool 결합 사용 코드

▲ Advisor + Web Search + Custom Tool 결합 사용 코드

배치 처리에서도 지원됩니다. 토큰 카운팅에서는 Executor의 첫 번째 iteration 입력 토큰만 반환합니다. 스트리밍 환경에서 Advisor 서브 추론은 스트리밍되지 않습니다. Executor의 스트림이 Advisor 실행 중에 일시 정지되고, 약 30초마다 SSE 핑 킵얼라이브가 전송됩니다. Advisor가 완료되면 결과가 단일 이벤트로 한꺼번에 도착하고, Executor 출력이 재개됩니다.

14. 에러 처리 전략

Advisor 호출이 실패하더라도 전체 요청이 실패하지 않습니다. 에러는 advisor_tool_result 블록 안에 advisor_tool_result_error 타입으로 전달되며, Executor는 이 에러를 인지하고 조언 없이 자체적으로 계속 진행합니다. 이 설계 덕분에 Advisor 서비스의 일시적 장애가 전체 워크플로우를 중단시키지 않습니다.

Advisor 에러 코드 종류와 처리 방법

▲ Advisor 에러 코드 종류와 처리 방법

주요 에러 코드는 6가지입니다. max_uses_exceeded는 요청당 한도에 도달했을 때 발생하며, 같은 요청 내 후속 Advisor 호출에서 계속 이 에러가 반환됩니다. too_many_requests는 Advisor 모델의 레이트 리밋에 걸렸을 때이고, overloaded는 서버 용량 한계에 도달했을 때입니다. prompt_too_long은 트랜스크립트가 Advisor 모델의 컨텍스트 윈도우를 초과했을 때, execution_time_exceeded는 타임아웃 발생 시, unavailable은 기타 모든 실패 시에 반환됩니다.

⚠ 주의: Advisor 레이트 리밋은 해당 모델의 직접 호출과 같은 버킷을 공유합니다. Advisor에서의 레이트 리밋은 tool_result 안의 too_many_requests로 나타나지만, Executor의 레이트 리밋은 전체 요청이 HTTP 429로 실패합니다.

15. 실전 팁과 주의사항

대화 레벨 비용 제어

Advisor Tool에는 대화 레벨의 호출 횟수 제한이 내장되어 있지 않습니다. max_uses는 단일 요청 내의 제한이지 대화 전체의 제한이 아닙니다. 대화 전체의 Advisor 호출 횟수를 관리하려면 클라이언트 측에서 직접 카운팅해야 합니다. 한도에 도달하면 tools 배열에서 advisor를 제거하고, 동시에 메시지 히스토리에서 모든 advisor_tool_result 블록도 함께 제거하세요.

조언에 대한 태도

Anthropic이 권장하는 시스템 프롬프트에는 조언을 다루는 방법에 대한 흥미로운 지침이 있습니다. 조언에 진지한 비중을 두되, 맹목적으로 따르지는 말라는 것입니다. 특정 단계를 따랐는데 실제 테스트에서 실패하거나, 1차 소스 근거가 조언과 모순되면 적응하라고 합니다. 또한 이미 수집한 데이터와 Advisor의 조언이 충돌하면, 조용히 전환하지 말고 한 번 더 Advisor를 호출하여 충돌을 해소하라고 권장합니다. 이런 조율 호출이 잘못된 방향에 투자하는 것보다 훨씬 저렴하기 때문입니다.

현재 제한사항

Advisor 출력 스트리밍 미지원Advisor 서브 추론 중에는 스트림이 멈추며, 완료 후 한꺼번에 전달됩니다.
대화 레벨 호출 제한 없음클라이언트 측에서 직접 추적하고 제한해야 합니다.
max_tokens가 Advisor에 적용되지 않음Executor 출력만 제한하며, Advisor 토큰은 별도입니다.
Priority Tier 별도 적용Executor의 Priority Tier가 Advisor에 자동 확장되지 않으므로, Advisor 모델에도 별도로 Priority Tier가 필요합니다.

현업 사용자 평가

Eve Legal의 ML 엔지니어는 Advisor 전략이 5배 낮은 비용으로 프론티어 수준의 품질을 달성한다고 평가했습니다. Bolt의 CEO는 단순한 작업에는 오버헤드 없이, 복잡한 작업에서만 동적으로 지능이 스케일링되는 점을 높이 평가했습니다. Genspark의 CTO는 자체 계획 도구보다 에이전트 턴 수, 도구 호출 횟수, 전체 점수에서 Advisor Tool이 더 우수하다고 밝혔습니다.

📚 참고 자료 출처

본 포스트는 아래 출처의 정보를 기반으로 작성되었습니다.
Anthropic 공식 문서 — Advisor Tool (코드 예제, API 스펙, 파라미터 정보)
GeekNews (긱뉴스) — Claude Advisor Tool 소개 (벤치마크 데이터, 사용자 평가 인용)
AI타임스 — Anthropic의 Advisor 전략 (성능 메트릭, 비용 분석 데이터)

자주 묻는 질문 (FAQ)

Q1. Advisor Tool을 사용하면 항상 비용이 절감되나요?+

반드시 그렇지는 않습니다. Advisor의 전략적 조언이 전체 도구 호출 횟수와 대화 길이를 줄여 총 비용이 절감되는 구조이므로, 단순한 단일 턴 작업에서는 오히려 Advisor 호출 비용만 추가됩니다. 코딩 에이전트나 멀티스텝 리서치처럼 장기 워크로드에서 가장 큰 효과를 봅니다. Sonnet+Opus 조합에서 SWE-bench 기준 태스크당 비용이 11.9% 절감된 것은 코딩 벤치마크 기준이며, 자신의 워크로드에서 직접 측정하는 것을 권장합니다.

Q2. Sonnet을 Advisor로, Haiku를 Executor로 사용할 수 있나요?+

아닙니다. 현재 지원되는 Advisor 모델은 Claude Opus 4.6만 가능합니다. Advisor는 반드시 Executor보다 같거나 더 높은 능력의 모델이어야 하며, 현재 유효한 Executor는 Haiku 4.5, Sonnet 4.6, Opus 4.6 세 가지이고, Advisor는 Opus 4.6만 가능합니다. 유효하지 않은 조합을 요청하면 400 에러가 반환됩니다.

Q3. Advisor가 호출되는 시점은 어떻게 결정되나요?+

Executor 모델이 스스로 판단합니다. 다른 도구와 마찬가지로, tools 배열에 advisor가 정의되어 있으면 Executor가 필요하다고 판단할 때 자동으로 호출합니다. 시스템 프롬프트로 호출 타이밍을 가이드할 수 있습니다. 예를 들어 실질적 작업 전에 호출하라, 태스크 완료 직전에 호출하라, 막혔을 때 호출하라는 지침을 추가하면 일관된 타이밍을 유도할 수 있습니다.

Q4. Advisor Tool을 Claude Code나 Claude Desktop에서도 쓸 수 있나요?+

Advisor Tool은 현재 Claude API(Anthropic)에서 베타로 제공됩니다. Claude Code에서는 이미 Advisor Opus 구현이 플러그인 형태로 제공되고 있습니다. Claude Desktop이나 claude.ai 웹 인터페이스에서는 직접 사용자가 Advisor Tool을 설정하는 것이 아니라, API를 통해 에이전트 애플리케이션을 구축할 때 활용하는 도구입니다.

Q5. Advisor의 thinking 블록을 볼 수 있나요?+

볼 수 없습니다. Advisor의 thinking 블록은 결과가 Executor에게 반환되기 전에 서버 측에서 제거됩니다. Executor에게는 오직 최종 조언 텍스트만 전달됩니다. 이는 비용을 절감하고 Executor의 컨텍스트 윈도우를 효율적으로 사용하기 위한 설계 결정입니다. Advisor 토큰 사용량은 usage.iterations 배열에서 advisor_message 타입으로 확인할 수 있습니다.

결론: Advisor 패턴이 가져올 변화

Claude Advisor Tool은 단순한 API 기능 추가가 아니라, AI 에이전트 아키텍처의 패러다임 전환을 의미합니다. 비싼 모델이 모든 것을 처리하는 시대에서, 전략과 실행을 분리하여 비용은 최적화하고 성능은 극대화하는 시대로 넘어가고 있습니다. 특히 코딩 에이전트, 리서치 파이프라인, 복잡한 도구 사용 시나리오에서 Sonnet과 Opus의 Advisor 조합은 프로덕션 도입을 진지하게 고려할 만한 강력한 선택지입니다.

반응형

Categories