Provider 정의

Provider 정의 (Provider Definitions)

에이전트 YAML의 providers 섹션으로 나만의 프로바이더 구성을 정의하는 방법을 설명해요. 모델들이 공유해서 참조할 수 있는 재사용 가능한 설정을 만들 수 있어요.

출처: 문서

본문

에이전트 YAML의 providers 섹션은 모델이 참조할 수 있는 이름 있는 프로바이더 구성을 정의해 줘요. 이렇게 쓰면 유용해요:

• 공용 기본값 묶기 — temperature, max_tokens, thinking_budget을 한 번 설정하고 여러 모델이 공유
• 커스텀 엔드포인트 — 자체 호스팅 모델, API 프록시, 게이트웨이 연결
• 자격 증명 중앙화 — 프로바이더를 쓰는 모든 모델에 대해 token_key를 한 번만 정의
• 모든 프로바이더 유형 — OpenAI, Anthropic, Google, Bedrock, 그리고 어떤 OpenAI 호환 API와도 동작

참고 모든 프로바이더 유형과 호환돼요 providers 섹션은 openai, anthropic, google, amazon-bedrock, dmr 등 모든 프로바이더 유형과 기본 제공 alias를 지원해요. provider 필드를 설정하지 않으면 하위 호환을 위해 openai로 기본값이 정해져요.

구성

OpenAI 호환 엔드포인트

providers:
  my_gateway:
    base_url: https://api.example.com/v1
    token_key: MY_API_KEY

models:
  my_model:
    provider: my_gateway
    model: gpt-4o

agents:
  root:
    model: my_model
    instruction: You are a helpful assistant.

공용 기본값을 쓰는 Anthropic

providers:
  my_anthropic:
    provider: anthropic
    token_key: MY_ANTHROPIC_KEY
    max_tokens: 16384
    thinking_budget: 8192

models:
  claude_smart:
    provider: my_anthropic
    model: claude-sonnet-4-5
    # max_tokens: 16384, thinking_budget: 8192 상속

  claude_fast:
    provider: my_anthropic
    model: claude-haiku-4-5
    thinking_budget: 1024  # 프로바이더 기본값 덮어씀

agents:
  root:
    model: claude_smart
    instruction: You are a helpful assistant.

공용 temperature를 쓰는 Google

providers:
  my_google:
    provider: google
    temperature: 0.3

models:
  gemini:
    provider: my_google
    model: gemini-2.5-flash
    # temperature: 0.3 상속

agents:
  root:
    model: gemini
    instruction: You are a helpful assistant.

프로바이더 속성

기본값 상속

프로바이더를 참조하는 모델은 그 기본값을 모두 상속해요. 모델 레벨 설정이 항상 우선해요:

providers:
  my_anthropic:
    provider: anthropic
    token_key: MY_ANTHROPIC_KEY
    max_tokens: 16384
    temperature: 0.7
    thinking_budget: high

models:
  # 프로바이더의 모든 설정을 상속
  claude_default:
    provider: my_anthropic
    model: claude-sonnet-4-5

  # temperature와 thinking_budget을 덮어쓰고 나머지는 상속
  claude_custom:
    provider: my_anthropic
    model: claude-sonnet-4-5
    temperature: 0.2
    thinking_budget: low

compaction_model은 조금 다르게 동작해요. 모델에 병합되는 게 아니라 에이전트별로 해석되며, 에이전트 레벨 compaction_model > 모델 레벨 > 프로바이더 레벨 기본값 순으로 우선해요.

축약 문법 (Shorthand)

프로바이더를 정의하면 provider_name/model 축약 문법을 쓸 수 있어요:

agents:
  root:
    model: my_gateway/gpt-4o-mini  # 프로바이더 기본값 사용
  researcher:
    model: my_anthropic/claude-sonnet-4-5  # anthropic 프로바이더 기본값 사용

API 유형

OpenAI 호환 프로바이더(provider가 openai이거나 미설정일 때)에만 적용돼요:

• openai_chatcompletions — 표준 OpenAI Chat Completions API. 대부분의 OpenAI 호환 엔드포인트와 동작
• openai_responses — OpenAI Responses API. Responses API 형식을 요구하는 최신 모델용

api_type을 설정하지 않으면 Docker Agent가 모델 이름을 보고 자동으로 선택해요. 감지된 기본값을 덮어쓸 때만 명시적으로 설정하면 돼요.

예시

vLLM / Ollama

providers:
  local_llm:
    base_url: http://localhost:8000/v1

agents:
  root:
    model: local_llm/llama-3.1-8b

참고 OpenAI 호환 프로바이더의 추론 토큰 delta.reasoning 아래로 추론을 스트리밍하는 모델(예: OVHcloud AI Endpoints, OpenRouter 또는 자체 호스팅 vLLM/SGLang 배포로 제공되는 Qwen3)은 완전히 지원돼요. Docker Agent는 스트림에서 delta.reasoning_content와 delta.reasoning 필드를 모두 읽어서, 서버가 어떤 필드를 쓰든 생각(thinking) 블록을 TUI에 보여줘요.

API 라우터 (Requesty, LiteLLM)

providers:
  router:
    base_url: https://router.requesty.ai/v1
    token_key: REQUESTY_API_KEY

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

Azure OpenAI

models:
  azure_model:
    provider: azure
    model: gpt-4o
    base_url: https://your-llm.openai.azure.com
    provider_opts:
      api_version: 2024-12-01-preview

Anthropic 팀 설정

providers:
  team_anthropic:
    provider: anthropic
    token_key: TEAM_ANTHROPIC_KEY
    max_tokens: 32768
    thinking_budget: high
    temperature: 0.5

models:
  architect:
    provider: team_anthropic
    model: claude-sonnet-4-5

  reviewer:
    provider: team_anthropic
    model: claude-haiku-4-5
    thinking_budget: low  # 더 빠른 리뷰

agents:
  root:
    model: architect
    sub_agents: [code_reviewer]
  code_reviewer:
    model: reviewer

공용 기본값을 쓰는 멀티 프로바이더

providers:
  fast_openai:
    base_url: https://api.openai.com/v1
    token_key: OPENAI_API_KEY
    temperature: 0.3
    max_tokens: 8192

  smart_anthropic:
    provider: anthropic
    token_key: ANTHROPIC_API_KEY
    max_tokens: 64000
    thinking_budget: high

agents:
  root:
    model: smart_anthropic/claude-sonnet-4-5
    sub_agents: [helper]
  helper:
    model: fast_openai/gpt-4o-mini

전역 프로바이더 (사용자 구성)

에이전트 파일에 정의한 프로바이더는 그 파일에만 적용돼요. 커스텀 프로바이더를 모든 명령(docker agent run, new, models, ...)에서 쓰려면 사용자 구성(~/.config/cagent/config.yaml)의 같은 providers 키 아래에 한 번 정의하면 돼요:

# ~/.config/cagent/config.yaml
providers:
  myprovider:
    base_url: https://llm.corp.example.com/v1
    api_type: openai_chatcompletions
    token_key: MYPROVIDER_API_KEY

가장 쉬운 등록 방법은 대화형 마법사예요:

docker agent setup
# "3. Custom OpenAI-compatible endpoint"를 고른 뒤,
# base URL, API 형식, API 키가 담긴 환경 변수 이름을 입력

등록하면 어디서든 동작해요:

docker agent models --provider myprovider   # 엔드포인트의 모델 목록 보기
docker agent new --model myprovider/mymodel # 이걸로 에이전트 만들기
docker agent run --model myprovider/mymodel # 이걸로 대화하기

전역 프로바이더는 로드되는 모든 에이전트 구성에 병합돼요. 에이전트 파일이 같은 이름의 프로바이더를 정의하면 에이전트 파일이 우선해요. 참고로 자동 모델 선택(model: auto)은 커스텀 프로바이더를 절대 고르지 않으므로, 그 모델은 --model <provider>/<model> 또는 default_model로 명시적으로 참조해야 해요.

동작 방식

프로바이더를 참조하면:

• 프로바이더의 provider 필드가 어떤 API 클라이언트를 쓸지 결정(기본값 openai)
• 프로바이더의 base_url과 token_key가 모델에 적용(모델에 이미 없으면)
• 모든 모델 레벨 기본값(temperature, max_tokens, thinking_budget 등)이 상속(모델 설정이 우선)
• OpenAI 호환 프로바이더의 경우 api_type이 provider_opts.api_type에 저장
• 모델은 해당 API 클라이언트와 함께 사용

base_url이 있는 프로바이더는 그걸 참조하는 모든 모델에 대해 bypass_models_gateway: true를 의미해요. 사용자가 고른 엔드포인트는 설정된 모델 게이트웨이를 통해 라우팅되지 않고, 그런 모델은 프로바이더 자신의 자격 증명(token_key)으로 인증해요.

더 알아보기 (Learn more)

• Docker Model Runner 프로바이더로 로컬에서 모델 실행하기
• Model Providers 개요에서 다른 프로바이더 살펴보기