평가

평가 (Evaluation)

자동 평가를 위해 에이전트 품질을 측정해요 — 도구 호출 정확도, 응답 관련성, 출력 크기 등.

출처: 문서

본문

개요 (Overview)

docker agent eval 명령은 기록된 세션 집합을 상대로 에이전트를 실행하고 결과를 채점해요. 각 평가 세션은 사용자 질문, 기대되는 도구 호출, 응답이 충족해야 하는 기준을 캡처해요. Docker Agent는 질문을 재생하고 에이전트의 행동을 기대와 비교하며 보고서를 만듭니다.

Note 컨테이너 런타임 필요 (Container runtime required) 격리를 위해 평가는 컨테이너 안에서 실행돼요. 각 평가는 선택적 설정 스크립트와 함께 깨끗한 환경을 얻어요. 실행 중인 Docker 호환 컨테이너 CLI/런타임이 필요해요: 기본적으로 Docker Desktop 또는 Docker Engine, 또는 --container-runtime 으로 선택한 Podman 같은 다른 Docker 호환 런타임.

빠른 시작 (Quick Start)

# Run evaluations for an agent
$ docker agent eval agent.yaml

# Specify a custom evals directory
$ docker agent eval agent.yaml ./my-evals

# Run with 8 concurrent evaluations
$ docker agent eval agent.yaml -c 8

# Only run evals matching a pattern
$ docker agent eval agent.yaml --only "auth*"

# Repeat each eval 5 times to compute a baseline
$ docker agent eval agent.yaml --repeat 5

# Repeat a specific eval 5 times
$ docker agent eval agent.yaml --only "auth*" --repeat 5

# Use a Docker-compatible runtime such as Podman
$ docker agent eval agent.yaml --container-runtime podman

평가 디렉터리 구조 (Eval Directory Structure)

기본적으로 Docker Agent는 에이전트 구성 옆의 evals/ 디렉터리에서 평가 세션을 찾아요:

my-agent/
├── agent.yaml
└── evals/
    ├── 41b179a2-....json # Eval session 1
    ├── 5d83e247-....json # Eval session 2
    └── results/ # Output (auto-created)
        ├── adjective-noun-1234.json
        ├── adjective-noun-1234.log
        ├── adjective-noun-1234.db
        └── adjective-noun-1234-sessions.json

평가 세션 형식 (Eval Session Format)

각 평가 파일은 완전한 대화를 캡처하는 JSON 세션입니다. 평가의 핵심 필드는 사용자 메시지, (실제 세션에서 기록된) 기대되는 도구 호출, 선택적 평가 기준이에요:

{
  "id": "41b179a2-ed19-4ae2-a45d-95775aaa90f7",
  "title": "Counting Files in Local Folder",
  "messages": [
    {
      "message": {
        "message": {
          "role": "user",
          "content": "How many files in the local folder?"
        }
      }
    },
    {
      "message": {
        "agent_name": "root",
        "message": {
          "role": "assistant",
          "tool_calls": [
            {
              "id": "call_abc123",
              "type": "function",
              "function": {
                "name": "list_directory",
                "arguments": "{\"path\":\"./\"}"
              }
            }
          ]
        }
      }
    },
    {
      "message": {
        "agent_name": "root",
        "message": {
          "role": "assistant",
          "content": "There are 2 files in the local folder..."
        }
      }
    }
  ],
  "evals": {
    "relevance": [
      "The response mentions exactly 2 files",
      "The response lists README.md and agent.yaml"
    ],
    "size": "S",
    "working_dir": "my-project",
    "setup": "echo 'hello' > test.txt"
  }
}

평가 기준 (Eval Criteria)

각 세션 안의 evals 객체가 무엇이 채점될지 제어해요:

Field Type Description
relevance string[] 에이전트 응답에 대해 참이어야 하는 진술. LLM 심판(judge)이 채점.
size string 기대되는 응답 크기: S, M, L, 또는 XL. 실제 출력 길이와 비교.
working_dir string 컨테이너의 작업 디렉터리로 마운트할 evals/working_dirs/ 아래의 하위 디렉터리.
setup string 에이전트가 실행되기 전에 컨테이너에서 실행할 셸 스크립트 (예: 테스트 파일 생성).

채점 메트릭 (Scoring Metrics)

Docker Agent는 세 가지 차원에서 에이전트를 평가해요:

Metric How It's Measured
Tool Calls (F1) (기록된 세션의) 기대되는 도구 호출 시퀀스와 에이전트가 만든 실제 도구 호출 사이의 F1 점수.
Relevance LLM 심판(--judge-model 로 구성 가능)이 각 관련성 진술이 응답에 의해 충족되는지 평가.
Size 응답 길이가 기대되는 크기 범주(S/M/L/XL)와 일치하는지.

서브 안전 검증과 롤백 (Serve-safety verification and rollback)

MCP HTTP, chat, A2A로 서빙되는 에이전트를 변경할 때, 승인을 요구하는 도구 호출을 시도하고 해석된 안전 정책과 인증 동작을 검증하는 평가를 추가해요. 배포에서 사용한 것과 같은 명시적 --safety 설정으로 평가를 실행해요. 롤아웃을 되돌려야 한다면 영향받는 리스너를 중지하고, 이전 에이전트 구성과 명시적 안전 플래그를 복원한 뒤, 비루프백 리스너가 여전히 인증을 요구함을 확인한 후에만 재시작해요. 인증 없는 네트워크 리스너를 롤백 단축으로 복원하지 마세요.

평가 세션 만들기 (Creating Eval Sessions)

평가 세션을 만드는 가장 쉬운 방법은 실제 대화에서요:

  • 에이전트를 대화형으로 실행: docker agent run agent.yaml
  • 관심 있는 동작을 테스트하는 대화를 나눠요
  • TUI의 /eval 슬래시 명령으로 세션을 평가 파일로 저장
  • 생성된 JSON을 편집해 평가 기준(relevance, size 등) 추가

Tip 도구 호출 채점(기록된 세션에서 자동)으로 시작하고, 가장 관심 있는 응답에 대한 관련성 기준을 추가하세요.

CLI 플래그 (CLI Flags)

$ docker agent eval <agent-file> | <registry-ref> [<eval-dir> | ./evals]
Flag Default Description
-c, --concurrency num CPUs 동시 평가 실행 수
--judge-model anthropic/claude-opus-5 LLM-as-a-judge 관련성 채점용 모델
--output <eval-dir>/results 결과, 로그, 세션 데이터베이스용 디렉터리
--only (all) 이 패턴과 일치하는 파일 이름의 평가만 실행
--base-image (default) 평가 컨테이너용 커스텀 기본 이미지 (Custom Base Images 참고)
--container-runtime docker 평가를 빌드하고 실행하는 컨테이너 런타임 실행 파일 (예: podman)
--keep-containers false 평가 후 컨테이너 유지 (--rm 으로 제거하지 않음)
-e, --env (none) 컨테이너에 전달할 환경 변수 (KEY 또는 KEY=VALUE)
--repeat 1 각 평가를 반복할 횟수 (기준선 계산에 유용)
--baseline (none) 이전에 저장된 실행 JSON과 비교하고 회귀 시 0이 아닌 코드로 종료 (Regression gate 참고)
--regression-tolerance 0 --baseline 이 회귀를 보고하기 전에 집계 품질 비율이 얼마나 떨어질 수 있는지 (0–1)

회귀 게이트 (Regression gate)

--baseline 은 실행을 이전 것과 비교하고 품질이 회귀하면 0이 아닌 것으로 종료하므로, 평가 스위트가 CI를 게이팅할 수 있어요:

$ docker agent eval ./agent.yaml --baseline results/2026-08-01-run.json

기준선은 이전 호출이 쓴 run JSON — <output>/<run-name>.json — 이므로 별도로 만들어야 할 아티팩트가 없어요. 판정을 결정하는 규칙 4개가 있고, CI에 연결하기 전에 알아둘 가치가 있어요:

  • 허용 오차는 집계 비율에만 적용돼요. LLM 심판은 같은 점수를 두 번 반환하지 않으므로, 허용 오차 없이는 게이트가 펄럭여요. --regression-tolerance 0.05 는 집계 비율이 집계 전에 5포인트 떨어지는 것을 허용해요.
  • 통과했던 평가가 지금 실패하면 허용 오차와 무관하게 항상 게이팅돼요. 그 전환이 게이트가 잡기 위해 존재하는 신호이며, 절대 흡수되지 않아요.
  • 비용은 보고되지만 절대 게이팅하지 않아요. 제공자 가격 변경은 품질 회귀가 아니에요.
  • 추가된 실패 평가는 기존 평가가 회귀하지 않았어도 집계 비율로 게이팅돼요. 나빠진 스위트는 그렇게 말해야 해요 — 하지만 알려진 실패 평가를 커밋하려면 허용 오차 상향이나 수정이 필요하다는 뜻이에요.

평가를 실지 않는 기준선이나 아무것도 만들지 않은 실행(--only 패턴이 아무것도 일치하지 않은 것)은 통과로 보고되는 대신 거부돼요: 실패할 수 없는 게이트는 게이트가 없는 것보다 나빠요.

제공자 자격 증명 (Provider Credentials)

평가 컨테이너는 호스트 환경에서 격리돼요. 전용 모델 제공자 API 키(예: ANTHROPIC_API_KEY 또는 OPENAI_API_KEY)는 평가 컨테이너로 자동 전달되므로, 대부분의 제공자 설정은 추가 플래그 없이 동작해요.

Warning GITHUB_TOKEN 과 GH_TOKEN 은 자동으로 전달되지 않아요 GitHub 토큰은 (git, gh, CI, 패키지의) 광범위한 자격 증명이지 전용 모델 API 키가 아니므로, 보안상 이유로 Docker Agent는 그것들을 평가 컨테이너로 전달하지 않아요 — 셸이나 ~/.config/cagent/.env 에 설정되어 있어도 그래요. 에이전트가 github-copilot 제공자를 쓰면 토큰을 이름으로 명시적으로 전달해요:

docker agent eval agent.yaml ./evals -e GITHUB_TOKEN

커스텀 env 파일을 쓰는 경우 두 플래그가 모두 필요해요:

docker agent eval agent.yaml ./evals \
  --env-from-file /path/to/secrets.env \
  -e GITHUB_TOKEN

LLM 심판은 평가 컨테이너 내부가 아니라 호스트에서 실행된다는 점을 참고하세요. 토큰이 전달되지 않으면 심판 검증은 성공할 수 있지만 평가된 모든 에이전트 실행이 인증에 실패해요.

커스텀 기본 이미지 (Custom Base Images)

--base-image 가 설정되면 평가 하네스가 평가 시에 기본 이미지 위에 파생 이미지를 빌드해요. 두 가지가 자동으로 일어나요:

  • docker-agent 바이너리가 주입됨 — 빌드 시 docker/docker-agent:edge 에서 파생 이미지로 복사되므로, 기본 이미지에 포함할 필요가 없어요.
  • entrypoint가 대체됨 — Docker Agent가 기본 이미지의 entrypoint를 자신의 /run.sh 래퍼로 대체해요.

따라서 기본 이미지는 런타임 환경만 제공하면 돼요: 언어 런타임, 설치된 의존성, 테스트 픽스처, 적절한 작업 디렉터리 등. 기본 이미지에 정의된 어떤 ENTRYPOINT 나 CMD 도 무시돼요.

출력 (Output)

실행이 완료된 후 Docker Agent는 다음을 생성해요:

  • 콘솔 요약 — 메트릭 분해가 있는 평가별 통과/실패 상태
  • JSON 결과 — 프로그램 분석을 위한 전체 구조화된 결과
  • SQLite 데이터베이스 — 상세 조사와 디버깅을 위한 완전한 세션
  • Sessions JSON — 분석용으로 내보낸 세션 데이터
  • 로그 파일 — 전체 평가 실행의 디버그 레벨 로그

Tip 실패한 평가 디버깅 (Debugging Failed Evals) --keep-containers 를 사용해 평가 후 컨테이너를 보존해요. 그런 다음 선택한 런타임의 exec 명령(기본 docker exec, --container-runtime podman 이면 podman exec)으로 검사해 평가가 왜 실패했는지 이해할 수 있어요. 세션 데이터베이스(.db 파일)는 각 평가의 전체 대화 기록을 담아요.

$ docker agent eval demo.yaml ./evals

✓ Counting Files in Local Folder
✓ tool calls ✓ relevance 2/2
✓ Checking the Content of README.md File
✓ tool calls ✓ relevance 1/1

✅ Tool Calls: 100.0% avg F1 (2 evals)
✅ Relevance: 3/3 passed (100.0%)

Total Cost: $0.012345
Total Time: 12s

Sessions DB: ./evals/results/happy-panda-1234.db
Sessions JSON: ./evals/results/happy-panda-1234-sessions.json
Log: ./evals/results/happy-panda-1234.log

예제 (Example)

여기 최소한의 평가 설정이 있어요:

# agent.yaml
agents:
  root:
    model: openai/gpt-4o
    description: Test agent
    instruction: You know how to read/write and list files.
    toolsets:
      - type: filesystem

# Create evals from interactive sessions
$ docker agent run agent.yaml
# ... have conversations, then use /eval to save them

# Run the evaluations
$ docker agent eval agent.yaml ./evals

Note 참고 (See also) 대화에서 평가 세션을 만들려면 TUI에서 /eval 을 사용하세요. 모든 docker agent eval 플래그는 CLI Reference 참고. 예제 평가 구성은 GitHub의 examples/eval 에 있어요.

더 알아보기 (Learn more)