플레이버

플레이버 (Flavors)

이름 있는 변형(variants)을 담은 에이전트 파일 하나를, 런타임에서 YAML 패치로 활성화해요.

출처: 문서

본문

개요 (Overview)

플레이버는 에이전트 파일 자체 안의 최상위 flavors 섹션 아래에 선언된 이름 있는 YAML 패치예요. 플레이버를 활성화하면 구성이 파싱되기 전에 문서의 나머지 위에 그 패치가 적용돼요. 그래서 한 파일이 여러 변형을 담을 수 있어요 — 로컬 실행용 저렴한 모델, CI용 추가 도구, 디버깅용 더 장황한 지침 — 전체 구성을 복제하지 않고요.

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

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

flavors:
  cheap:
    models:
      claude:
        model: claude-3-5-haiku-latest

반복 가능한 --flavor 플래그로 플레이버를 활성화해요:

$ docker agent run agent.yaml --flavor cheap

이 플래그는 에이전트를 실행하는 모든 명령 — run, chat, eval, serve api, serve a2a, serve mcp — 에서 동작하고, 순서가 중요해요: 패치는 플레이버가 요청된 순서로 적용되며, 각각 이전 결과 위에 놓여요.

$ docker agent run agent.yaml --flavor cheap --flavor verbose

파일이 정의하지 않은 플레이버는 무시돼요(디버그 로그 포함), 그래서 에이전트 플릿 전체에 같은 플레이버 집합을 활성화할 수 있고 각 파일은 자신이 선언한 이름에만 반응해요. OCI나 URL 참조에서 로드된 외부 하위 에이전트도 같은 활성화된 플레이버를 받아요.

병합 의미론 (Merge Semantics)

패치는 JSON Merge Patch 의미론을 따르며, 배열에 대한 두 가지 확장이 있어요:

Patch value Effect
Object 기존 객체에 재귀적으로 병합.
Scalar or array 기존 값을 대체.
null 키 삭제.
+ 로 끝나는 키 항목을 기존 배열에 추가.
- 로 끝나는 키 배열 또는 객체에서 일치하는 항목 제거.

병합과 대체 (Merging and replacing)

객체 패치는 자신이 이름 짓는 키에만 닿아요 — 형제는 유지돼요:

flavors:
  verbose:
    agents:
      root:
        instruction: Explain your reasoning in detail. # model, tools, ... unchanged

키 삭제 (Deleting a key)

null 로 설정해요:

flavors:
  no-limit:
    models:
      claude:
        max_tokens: null

배열에 추가 (Appending to an array)

평범한 배열은 전체를 대체해요. 항목을 추가하려면 키에 + 를 붙여요:

agents:
  root:
    toolsets:
      - type: think

flavors:
  with-shell:
    agents:
      root:
        toolsets+:
          - type: shell

--flavor with-shell 로 root 에이전트는 think 와 shell 둘 다 갖게 돼요.

항목 제거 (Removing entries)

키에 - 를 붙여요. 패치 값의 각 항목이 무엇을 제거할지 선택해요:

  • 배열에서: 스칼라(일반 값)는 같은 요소를 제거하고; 객체는 부분 일치하는 모든 요소를 제거해요(매처의 모든 키가 일치하는 값으로 존재해야 함).
  • 객체에서: 항목은 버릴 키 이름들이에요.
flavors:
  slim:
    agents:
      root:
        toolsets-:
          - type: shell # drop every shell toolset, however configured
        sub_agents-:
          - checker # drop by value
        models-:
          - spare # drop the named model definition

Note + 와 - 접미사는 플레이버 패치 안에서 예약되어 있어요: 패치는 두 문자 중 하나로 끝나는 리터럴 키를 설정할 수 없어요. 기본 문서는 영향을 받지 않아요.

결과 검사 (Inspecting the Result)

docker agent debug config 는 런타임이 보는 대로 구성(플레이버 적용됨)을 정확히 출력해요:

$ docker agent debug config agent.yaml --flavor cheap --flavor with-shell

HCL

플레이버는 HCL 구성에서도 라벨 블록으로 동작해요. append/remove 연산자는 객체 표현식 안에 따옴표가 붙은 속성 이름이 필요해요:

flavors "with-shell" {
  agents = {
    root = {
      "toolsets+" = [{ type = "shell" }]
    }
  }
}

참고 (Notes)

  • 플레이버는 구성 스키마 버전 13 이상이 필요해요; 이전 버전은 최상위 version 필드를 올리라는 힌트와 함께 flavors 키를 거부해요.
  • 패치는 검증 전에 적용되므로, 플레이버가 적용된 구성은 손으로 쓴 것과 정확히 똑같이 검증돼요.
  • docker agent push 는 flavors 섹션을 포함한 원시 문서를 게시하므로, 푸시된 에이전트의 소비자도 그 플레이버를 활성화할 수 있어요.

더 알아보기 (Learn more)