Anthropic

Anthropic

Claude Sonnet 4, Claude Sonnet 4.5, 그리고 다른 Anthropic 모델을 Docker Agent와 함께 사용해요.

출처: 문서

본문

설정 (Setup)

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

워크로드 아이덴티티 페더레이션 (API 키 없음) — Workload Identity Federation (no API key)

장기 API 키 대신 자신의 OIDC 아이덴티티 제공자에서 발급한 단기 토큰으로 인증해요. 페더레이션 규칙(Rule)을 프로비저닝하려면 Anthropic의 Workload Identity Federation 가이드를 참고하고, 그런 다음 Docker Agent를 타입이 있는 auth: 블록으로 구성해요:

providers:
  anthropic-wif:
    provider: anthropic
    auth:
      type: workload_identity_federation
      workload_identity_federation:
        federation_rule_id: fdrl_REPLACE_ME
        organization_id: 00000000-0000-0000-0000-000000000000
        # Optional: only required for target_type=SERVICE_ACCOUNT rules.
        service_account_id: svac_REPLACE_ME
    identity_token:
      # Pick exactly one of: file, env, command, url
      file: /var/run/secrets/anthropic.com/token

models:
  claude:
    provider: anthropic-wif
    model: claude-sonnet-4-5

identity_token 은 네 가지 상호 배타적 소스를 받아요:

url 의 경우 URL과 모든 헤더 값이 런타임 환경에 대해 ${env.VAR} 확장을 지원하며(레거시 ${VAR} 형식도 허용), 이는 GitHub Actions OIDC 토큰 엔드포인트를 YAML에 시크릿을 넣지 않고 연결하게 해줘요:

identity_token:
  url: ${env.ACTIONS_ID_TOKEN_REQUEST_URL}&audience=https://api.anthropic.com
  headers:
    Authorization: bearer ${env.ACTIONS_ID_TOKEN_REQUEST_TOKEN}
  response_field: value

auth: 는 --gateway 와 상호 배타적이에요. 토큰 갱신 실패는 정상 에러 경로를 통해 TUI에 anthropic workload identity federation: failed to refresh identity token from <kind> source (federation_rule=fdrl_…): ... 같은 명확한 메시지로 드러나요.

네 가지 소스의 완전한 워크스루은 examples/anthropic_wif.yaml 에 있어요.

구성 (Configuration)

인라인 (Inline)

agents:
  root:
    model: anthropic/claude-sonnet-4-5

이름 있는 모델 (Named Model)

models:
  claude:
    provider: anthropic
    model: claude-sonnet-4-5
    max_tokens: 64000

사용 가능한 모델 (Available Models)

생각 버짓 (Thinking Budget)

Anthropic은 정수 토큰 버짓 또는 문자열 effort 값을 받아요. thinking_budget 을 설정하지 않으면 thinking은 꺼져 있고, 설정하면 interleaved thinking이 자동으로 활성화돼요.

토큰 버짓 (1024–32768; 모든 extended-thinking Claude 모델에서 동작):

models:
  claude-deep:
    provider: anthropic
    model: claude-sonnet-4-5
    thinking_budget: 16384 # must be < max_tokens

적응형 / effort 기반 (Claude Opus 4.6+, Sonnet 4.6 — 모든 문자열 값은 output_config.effort 를 통해 adaptive thinking으로 보내짐):

models:
  opus-adaptive:
    provider: anthropic
    model: claude-opus-4-6
    thinking_budget: adaptive # model decides effort (defaults to high)

  opus-effort:
    provider: anthropic
    model: claude-opus-4-6
    thinking_budget: high # low | medium | high | xhigh | max (same as adaptive/<effort>)

토큰 기반 thinking을 거부하는 모델(Opus 4.6, 4.7, 4.8, Sonnet 4.6)에서 정수 버짓은 로그 경고와 함께 자동으로 adaptive로 강제 변환돼요. 전체 교차 제공자 참조는 Thinking / Reasoning 가이드 참고.

인터리브 thinking (Interleaved Thinking)

Claude 모델에 thinking 버짓이 구성될 때마다 자동 활성화돼요. 더 통합된 문제 해결을 위해 모델 추론 중 도구 호출을 허용해요:

models:
  claude:
    provider: anthropic
    model: claude-sonnet-4-5
    provider_opts:
      interleaved_thinking: false # disable if needed

작업 버짓 (Task Budget)

task_budget 은 다단계 에이전트 작업 전반에 걸쳐 모델이 쓸 수 있는 총 토큰 수 — 결합된 thinking, 도구 호출, 최종 출력 — 를 상한 짓는 것이에요. output_config.task_budget 로 전달되며, 매 호출에서 max_tokens 를 조이지 않고 오래 실행되는 에이전트가 스스로 노력을 조절하게 하기에 이상적이에요.

Docker Agent는 이 필드가 설정될 때마다 필수 task-budgets-2026-03-13 베타 헤더를 자동으로 붙여요. 어떤 Claude 모델에서든 task_budget 을 구성할 수 있어요 — Docker Agent는 모델 이름으로 게이팅하지 않아요. 작성 시점에 실제로 이 필드를 적용하는 것은 Claude Opus 4.7뿐이에요; 다른 Claude 모델(Sonnet 4.5, Opus 4.5 / 4.6 등)은 그것을 포함한 요청을 거부할 것으로 예상돼요. 현재 지원 모델 목록은 위에 연결된 Anthropic 릴리스 노트를 확인하세요.

models:
  opus:
    provider: anthropic
    model: claude-opus-4-7
    task_budget: 128000 # integer shorthand → { type: tokens, total: 128000 }
    thinking_budget: adaptive

객체 형식(미래 버짓 유형과 호환):

opus:
  provider: anthropic
  model: claude-opus-4-7
  task_budget:
    type: tokens
    total: 128000

전체 스키마는 Model Configuration 페이지 참고.

서버 측 폴백 (Server-Side Fallbacks)

기본 모델이 요청을 거부하면(예: Claude Fable 5의 안전 분류기가 stop reason refusal 로 턴을 끝내는 경우), Anthropic이 단일 왕복에서 백업 모델로 요청을 재시도할 수 있어요. provider_opts 에서 fallbacks 를 우선순위 순서의 모델 ID 목록으로 설정해요:

models:
  fable:
    provider: anthropic
    model: claude-fable-5
    provider_opts:
      fallbacks:
        - claude-opus-4-8
        - claude-sonnet-4-6

Docker Agent는 필수 server-side-fallback-2026-06-01 베타 헤더를 자동으로 붙이고 옵션을 fallbacks: [{"model": "..."}] 로 전달해요. 응답의 model 필드는 실제로 어떤 모델이 요청을 처리했는지 보고해요.

폴백 모델은 기본 모델과 완전히 같은 요청(thinking 구성, task budget, 베타 기능 등)을 받으므로, 같은 요청 형태를 받아들이는 모델만 나열하세요. Bedrock, Vertex AI, Message Batches API에서는 사용할 수 없어요.

Thinking 표시 (Thinking Display)

thinking이 활성화될 때 응답에 thinking 블록을 반환할지 제어해요. 더 새로운 Claude 모델(Opus 4.7+, Fable 5)은 기본적으로 thinking 콘텐츠를 숨겨요(omitted); Docker Agent는 명시적 thinking_display 없이 adaptive/effort 기반 버짓을 쓸 때마다 요약된 thinking을 요청해서 이에 대응하므로, UI에서 추론이 계속 보여요. provider_opts 에서 thinking_display 를 설정해 재정의해요:

models:
  claude-opus-4-7:
    provider: anthropic
    model: claude-opus-4-7
    thinking_budget: adaptive
    provider_opts:
      thinking_display: omitted # "summarized" or "omitted" ("display" on pre-4.6 models only)

유효한 값:

• summarized: thinking 블록이 요약된 thinking 텍스트와 함께 반환돼요 (adaptive/effort 기반 버짓에 대한 Docker Agent 기본값).
• display: thinking 블록이 표시용으로 반환돼요. pre-4.6 토큰 thinking 모델(예: Sonnet 4.5, Haiku 4.5)에서만 받아들여져요; adaptive-thinking 세대 이후의 모델(Opus/Sonnet 4.6+, Sonnet 5, Fable 5)은 거부하며, Docker Agent는 API가 거부할 요청을 보내는 대신 구성 오류로 빠르게 실패해요.
• omitted: thinking 블록이 빈 thinking 필드로 반환돼요; 다중 턴 연속성을 위해 서명은 여전히 반환돼요. 스트리밍할 때 첫 텍스트 토큰까지의 시간을 줄이는 데 유용해요.

참고: thinking_display 는 토큰 수 thinking 버짓과 adaptive/effort 기반 버짓 모두에 적용돼요. 토큰 수 버짓에는 기본값이 적용되지 않아요(API가 이미 기본적으로 summarized). thinking_display 값과 무관하게 전체 thinking 토큰이 청구돼요.

Note 1024 미만이거나 max_tokens 이상인 Anthropic thinking 버짓 값은 무시돼요(경고가 로그됨).

더 알아보기 (Learn more)