에이전트

에이전트 (Agents)

에이전트는 Docker Agent의 핵심 구성 요소예요. 각 에이전트는 모델, 지침, 도구, 그리고 선택적인 하위 에이전트를 가진 AI 기반 개체(entity)랍니다.

출처: 문서

본문

에이전트란 무엇인가? (What is an Agent?)

Docker Agent의 에이전트는 다음으로 정의돼요:

  • Model — 그것을 구동하는 AI 모델 (예: Claude, GPT-5, Gemini). Models 참고.
  • Description — 에이전트가 무엇을 하는지에 대한 간략한 요약 (다른 에이전트가 위임 시 사용)
  • Instruction — 에이전트의 행동과 성격을 정의하는 시스템 프롬프트
  • Tools — 파일시스템 접근, 셸 명령, 외부 API 같은 기능
  • Sub-agents — 작업을 위임할 수 있는 다른 에이전트들
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Expert software developer
    instruction: |
      You are an expert developer. Write clean, efficient code
      and explain your reasoning step by step.
    toolsets:
      - type: filesystem
      - type: shell
      - type: think

루트 에이전트 (The Root Agent)

모든 Docker Agent 구성에는 루트 에이전트가 있어요 — 사용자 메시지를 받는 진입점이에요. 단일 에이전트 설정에서는 이것이 유일한 에이전트예요. 다중 에이전트 설정에서는 루트 에이전트가 조정자(coordinator) 역할을 하며 특화된 하위 에이전트들에게 작업을 위임해요.

Note 명명 (Naming) YAML에서 처음 정의된 에이전트(또는 root 라는 이름의 것)가 기본 루트 에이전트예요. docker agent run config.yaml -a agent_name 을 사용해 어떤 에이전트로 시작할지 지정할 수도 있어요.

에이전트 속성 (Agent Properties)

Property Type Required Description
model string ✓ 모델 참조 (openai/gpt-5 같은 인라인 또는 이름 있는 모델)
description string ✓ 에이전트가 하는 일 — 다른 에이전트가 위임 시 사용
instruction string ✓ 행동을 정의하는 시스템 프롬프트
toolsets array ✗ 도구 구성 목록
sub_agents array ✗ 이 에이전트가 위임할 수 있는 에이전트들의 이름
fallback object ✗ 복원력을 위한 폴백 모델 구성
add_date boolean ✗ 컨텍스트에 현재 날짜 포함
add_environment_info boolean ✗ 컨텍스트에 OS, 작업 디렉터리, git 정보 포함
max_iterations int ✗ 최대 도구 호출 루프 수 (기본값: 무제한)
commands object ✗ /command 로 호출 가능한 이름 있는 프롬프트
skills boolean | list ✗ 스킬 발견과 로딩 활성화. true = ["local"]; 리스트 값은 "local" 과 원격 스킬 서버 URL을 결합할 수 있음

모델 폴백 (Model Fallbacks)

에이전트는 기본 모델을 사용할 수 없을 때 대체 모델로 자동 페일오버할 수 있어요:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    fallback:
      models:
        - openai/gpt-5
        - google/gemini-3.5-flash
      retries: 2 # retries per model for 5xx errors
      cooldown: 1m # stick with fallback after 429

이름 있는 명령 (Named Commands)

명령으로 호출할 수 있는 재사용 가능한 프롬프트를 정의해요:

agents:
  root:
    model: openai/gpt-5
    instruction: You are a helpful assistant.
    commands:
      df: "Check how much free space I have on my disk"
      greet: "Say hello to ${env.USER}"

# Run a named command
$ docker agent run agent.yaml /df
$ docker agent run agent.yaml /greet

명령은 JavaScript 템플릿 리터럴 구문을 사용한 환경 변수 보간을 지원해요. 정의되지 않은 변수는 빈 문자열로 확장돼요.

기본 에이전트 (Default Agent)

구성 인자 없이 docker agent run 을 실행하면 현재 디렉터리의 docker-agent.yaml, docker-agent.yml, 또는 docker-agent.hcl 을 사용해요(있을 때). 그렇지 않으면 별도 구성 없이 빠른 작업을 위한 유능한 내장 기본 에이전트를 사용해요.

# Use the project config or built-in default agent
$ docker agent run

# Override the default with an alias
$ docker agent alias add default /path/to/my-agent.yaml
$ docker agent run # now runs your custom agent

Tip 참고 (See also) 재사용 가능한 작업별 지침은 Skills 참고. 다중 에이전트 패턴은 Multi-Agent 참고. 전체 구성 참조는 Agent Config 참고.

더 알아보기 (Learn more)