azd CLI를 사용하여 에이전트 평가 실행(미리 보기)

Azure 개발자 CLI(azd) CLI 평가 환경을 사용하여 Microsoft Foundry로 만든 에이전트에 측정된 품질 루프를 추가합니다. 이 문서에서는 평가 자산을 만들고, 프로비전하고, 배포하고, 초기화하고, 첫 번째 평가를 실행하고, 실행을 검사하고, 나중에 실행하기 위해 평가 레시피를 다시 사용하는 호스트 에이전트 수명 주기 azd에 중점을 둡니다.

프롬프트 기반 에이전트는 Foundry 프로젝트에서 에이전트 대상으로 사용할 수 있는 경우에도 평가할 수 있습니다. 호스트 에이전트 배포 단계는 호스트된 에이전트에만 적용됩니다.

이 문서에서는 azd ai agent eval generate 및 azd ai agent eval run을 사용하여 첫 번째 에이전트 평가를 실행하는 방법을 설명합니다.

사전 요구 사항

• Microsoft Foundry에 액세스할 수 있는 Azure 구독입니다.
• Azure 개발자 CLI(azd)입니다. 설치 지침은 Azure 개발자 CLI 설치 참조하세요.
• azd ai agent 확장 프로그램, 버전 0.1.40-preview 이상, 설치됨(azd ext install azure.ai.agents). 확장이 설치되어 있지 않으면 시작 템플릿을 초기화하거나 확장을 실행할 azd ai agent 때 자동으로 설치됩니다. 실행 azd ext list 하여 설치된 버전을 확인하고 업그레이드해야 하는 경우 실행 azd ext upgrade azure.ai.agents 합니다. AI 에이전트 확장에 azd 대한 자세한 내용은 Microsoft Foundry 에이전트 확장을 참조하세요.
• 인증된 azd 세션입니다. 인증 상태를 확인하려면 다음을 실행 azd auth status합니다. 로그인되어 있지 않은 경우 azd auth login을 실행하세요.
• Foundry 리소스의 Foundry User 역할(이전에는 Azure AI User)입니다. 자세한 내용은 Microsoft Foundry의 역할 기반 접근 제어를 참조하세요.
• 호스트된 에이전트의 경우: 기존 Foundry 프로젝트는 필요하지 않습니다. azd ai agent init 및 azd provision 필요한 리소스를 만듭니다.
• 프롬프트 기반 에이전트의 경우: 에이전트가 이미 배포되어 평가 대상으로 사용할 수 있는 기존 Foundry 프로젝트입니다.
• 동일한 Foundry 프로젝트에서 채팅 완료를 지원하는 모델 배포입니다.
• 선택 사항: 스모크 데이터 세트를 생성하지 않으려는 eval generate 경우 대표적인 예제가 포함된 JSONL 평가 데이터 세트입니다.

azd 에이전트 평가 작동 방식

기본 azd CLI 평가 환경은 호스트 에이전트 수명 주기를 위해 설계되었습니다.

azd ai agent init
azd provision
azd deploy
azd ai agent eval generate
azd ai agent eval run
azd ai agent eval update
# Optional, after the agent and eval recipe meet optimization prerequisites:
azd ai agent optimize

평가 흐름에는 다음과 같은 아티팩트 및 명령이 포함됩니다.

azd provision 는 평가 데이터 세트, 계산기, 제품군 또는 최적화 작업을 만들지 않습니다. 평가 설정에는 몇 분 정도 걸리는 생성 작업이 포함될 수 있으므로 명시적이고 다시 시도할 수 있습니다.

호스트된 에이전트의 경우 첫 번째 평가에는 배포되고 호출 가능한 에이전트 대상이 필요합니다. 프롬프트 기반 에이전트의 경우 배포 단계가 적용되지 않습니다. 에이전트는 Foundry 프로젝트에 이미 있어야 하며 평가 대상으로 사용할 수 있어야 합니다.

호스트된 에이전트 만들기 및 배포

호스트 에이전트 프로젝트가 아직 없는 경우 다음을 사용하여 초기화 azd합니다.

azd ai agent init

Foundry 리소스를 프로비전하고 에이전트를 배포합니다.

azd provision
azd deploy

배포가 완료되면 에이전트를 호출할 수 있는지 확인합니다.

azd ai agent show

평가 자산을 초기화하기 전에 호스트된 에이전트를 배포하고 호출할 수 있어야 합니다.

배포가 성공한 후 CLI는 명시적 다음 단계로 평가를 제안합니다.

Set up an evaluation suite to measure quality and impact in one step with `azd ai agent eval generate`

프롬프트 기반 에이전트를 평가하려면 호스트 에이전트 만들기 및 배포 명령을 건너뜁니다. 프롬프트 기반 에이전트가 Foundry 프로젝트에 있고 평가 대상으로 사용할 수 있는지 확인한 후 다음 섹션으로 계속 진행합니다.

평가 자산 초기화

azd 작업 영역 또는 에이전트 프로젝트 폴더에서 실행 eval generate 합니다.

azd ai agent eval generate

플래그가 없으므로 명령은 대화형 마법사를 시작합니다. 마법사는 azd 환경에서 에이전트 대상을 검색한 다음, 서비스에서 유용한 시드 평가 데이터 및 평가기 루브릭을 만들 수 있도록 생성 지침을 요청합니다.

대화형 출력 예제:

? Eval suite name: reservation-agent
? How would you like to provide the agent instruction?: Type inline
? Describe what this agent does and what scenarios to test: This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement.
? Include agent traces for evaluator generation?: No
? Select the model for evaluation and generation: gpt-4o (deployed)
? Max samples (between 15 and 1000): 100
  (–) Running  Evaluator generation  (evaluatorgen-reservation-agent-v3-abc12345)
  (–) Running  Dataset generation  (datagen-abc123456)
  (✓) Done  Evaluator generation  (20 seconds)
  (✓) Done  Dataset generation  (2m 9s)

Eval suite created
  Config:     src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  Evaluator dimensions (4):
    Weight  Dimension
    ──────  ─────────
        10  booking_accuracy
         5  policy_enforcement
         6  cancellation_handling
         5  general_quality

  Portal:
    Dataset:   https://ai.azure.com/.../build/data/datasets/reservation-agent-dev-eval-seed/1.0
    Evaluator: https://ai.azure.com/.../build/evaluations/catalog/reservation-agent-quality/1

  Next steps:
    azd ai agent eval run
      Run the eval suite against your agent.
    azd ai agent eval update
      Edit the generated dataset or evaluator locally, then upload changes.

스크립션된 사용의 경우 생성 입력을 직접 전달합니다.

azd ai agent eval generate \
  --gen-instruction "This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement." \
  --eval-model gpt-4o \
  --max-samples 100

--out-file 는 선택 사항이며 에이전트 프로젝트 루트의 기본값 eval.yaml 입니다. 다른 위치에 구성을 기록하려면 --out-file <path>을(를) 사용합니다.

기존 데이터 세트 및 선택한 계산기를 사용하려면 다음을 수행합니다.

azd ai agent eval generate \
  --dataset ./tests/support-golden.jsonl \
  --gen-instruction "Support quality, policy adherence, and escalation behavior" \
  --max-samples 50 \
  --evaluator builtin.intent_resolution \
  --evaluator support-quality \
  --out-file eval.yaml

./tests/support-golden.jsonl를 자신의 평가 데이터 세트 경로로 바꾸십시오.

값은 --dataset 로컬 파일 또는 등록된 데이터 세트 이름을 가리킬 수 있습니다. 여러 기본 제공 또는 등록된 사용자 지정 평가자를 포함하려면 --evaluator를 반복합니다. 평가자 참조는 다음 형식(<source>.<name>)을 사용합니다:

• builtin.<name> — Foundry 에서 제공하는 기본 제공 계산기를 참조합니다.
• <name> — Foundry 프로젝트에 등록된 사용자 지정 계산기를 참조합니다. 버전 접미사 없이 평가자의 등록된 이름을 사용하세요.

--no-wait로 생성 연기

데이터 세트 또는 계산기 생성이 너무 오래 걸리는 경우 생성 작업을 제출하고 즉시 종료하는 데 사용합니다 --no-wait .

azd ai agent eval generate \
  --gen-instruction "..." \
  --no-wait

보류 중인 작업 ID는 eval.yaml에 기록됩니다. 나중에 실행 azd ai agent eval run하면 평가 실행을 시작하기 전에 해당 작업을 자동으로 다시 시작합니다.

프롬프트 기반 에이전트 대상 사용

프롬프트 기반 에이전트에 대한 평가 자산을 초기화한 경우 동일한 평가 레시피 흐름을 사용할 수 있습니다. 프롬프트 기반 에이전트에는 호스트 에이전트 배포 단계가 필요하지 않습니다.

평가를 실행하기 전에 다음을 확인합니다.

• 프롬프트 기반 에이전트가 Foundry 프로젝트에 있습니다.
• 에이전트를 평가 대상으로 사용할 수 있습니다.
• 프로젝트 엔드포인트 및 에이전트 대상에 액세스할 수 있습니다.
• eval.yaml 는 의도한 프롬프트 기반 에이전트를 선택합니다.

현재 Foundry 프로젝트에서 사용할 수 있는 에이전트를 나열하려면 다음을 실행합니다.

azd ai agent list

그런 다음, 동일한 명령을 사용하여 평가를 실행하고 검사합니다.

azd ai agent eval run --config eval.yaml
azd ai agent eval show

eval.yaml 검토하기

eval generate이 성공한 후, 에이전트 프로젝트 루트에서 eval.yaml을 여세요. 다음은 그 예입니다.

src/reservation-agent/eval.yaml

이 디렉터리에서 eval run를 실행하거나 --config src/reservation-agent/eval.yaml로 경로를 명시적으로 전달하세요. 이 파일은 에이전트 대상, 데이터 세트 참조, 계산기 참조 및 생성 옵션을 식별합니다. 간소화된 도형은 다음과 같습니다.

name: reservation-agent
agent:
  name: reservation-agent
  kind: hosted
  version: "3"
  config: .agent_configs\baseline\metadata.yaml
dataset_reference:
  name: reservation-agent-dev-eval-seed
  version: "1.0"
  local_uri: datasets\reservation-agent-dev-eval-seed
evaluators:
  - builtin.task_adherence
  - name: reservation-agent-quality
    version: "1"
    local_uri: evaluators\reservation-agent-quality\rubric_dimensions.json
options:
  eval_model: gpt-4o
max_samples: 100

• eval.yaml 는 에이전트 프로젝트 루트에 있습니다( 예: src/<agent-name>/eval.yaml).
• 생성된 데이터 세트는 에이전트 폴더 아래에 datasets/ 라이브로, 생성된 계산기 루브릭은 에이전트 폴더 아래에 evaluators/ 있습니다.
• local_uri 경로는 eval.yaml 에이전트 프로젝트 디렉터리를 기준으로 합니다.
• 참조되는 local_uri 로컬 파일은 편집할 수 있습니다. azd ai agent eval update을 실행하여 로컬 변경 내용을 서비스에 새 버전으로 등록하고 eval.yaml의 버전을 올리세요.
• eval run는 eval.yaml에 고정된 등록된 버전을 사용합니다. 로컬 편집을 적용하려면 eval update 전에 eval run를 실행하세요.
• 평가자는 기본 제공 참조(예: builtin.task_adherence)이거나 name, version, local_uri를 사용해 생성된 사용자 지정 평가자일 수 있습니다.
• 버전 필드를 숫자로 보이더라도 문자열로 처리하므로 YAML 파서에서 레시피가 안정적으로 유지됩니다.

평가 실행

에이전트 프로젝트 폴더에서 다음을 실행합니다.

azd ai agent eval run

기본적으로 인수가 없는 eval run는 에이전트 프로젝트 루트에서 eval.yaml를 해석합니다. 구성 경로를 명시적으로 전달할 수도 있습니다.

azd ai agent eval run --config eval.yaml

보류 중인 생성 작업을 eval generate --no-wait 만든 경우 eval run 평가 실행을 시작하기 전에 해당 작업을 다시 시작합니다. 새 데이터 세트 또는 계산기 생성 작업을 처음부터 시작하지 않습니다.

평가 실행 검사

최근 평가 실행 내역을 조회합니다.

azd ai agent eval list

최신 실행 표시:

azd ai agent eval show

플래그 eval show 가 없으므로 기본값은 가장 최근의 평가로 설정되고 해당 실행이 나열됩니다.

특정 실행의 세부 정보를 표시하려면 eval ID를 인수로 전달하고 실행 ID를 함께 --eval-run-id전달합니다. azd ai agent eval list 출력에서 eval ID를 복사하고 azd ai agent eval show <eval-id> 출력에서 run ID를 복사합니다:

azd ai agent eval show <eval-id> --eval-run-id <run-id>

실행 출력을 사용하여 대답합니다.

• 어떤 에이전트 버전이 평가되었는지
• 해결된 데이터 세트 및 평가기 버전입니다.
• 실행이 완료되었는지, 실패했는지 또는 부분적으로 완료되었는지 여부입니다.
• 생성된 메트릭 또는 평가자 점수입니다.
• 토큰 사용량 또는 평가기 로그에 조사가 필요한지 여부입니다.

에이전트를 변경한 후 다시 실행

호스트된 에이전트를 업데이트하고 다시 배포한 후 동일한 평가 레시피를 다시 실행합니다.

azd deploy
azd ai agent eval run --config eval.yaml

프롬프트 기반 에이전트의 경우 Foundry에서 에이전트를 업데이트한 다음 동일한 평가 레시피를 다시 실행합니다.

동일한 eval.yaml 기능을 다시 실행하면 에이전트 변경에서 데이터 세트, 계산기 및 임계값 참조를 안정적으로 유지할 수 있습니다.

평가 자산 업데이트, 재설정 또는 복구

에이전트 평가 흐름은 로컬 평가 레시피로 사용됩니다 eval.yaml . 로컬 데이터 세트 파일 또는 계산기 루브릭을 편집하고 해당 편집을 새 서비스 버전으로 등록하려는 경우에 사용합니다 azd ai agent eval update .

평가 실행에서 사용하는 항목을 업데이트하려면 변경 유형과 일치하는 경로를 선택합니다.

예를 들어 에이전트 폴더에서 evaluators/ 생성된 계산기 루브릭을 편집한 후 다음을 실행합니다.

azd ai agent eval update
azd ai agent eval run --config eval.yaml

업데이트 명령은 등록된 새 데이터 세트 또는 계산기 버전을 만듭니다. 기존 평가 실행은 원래 사용한 버전과 계속 연결됩니다.

이미 있는 eval.yaml 경우 eval generate 이를 감지하고 기존 구성을 출력합니다.

Eval config already exists: src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  To run the evaluation:
    azd ai agent eval run

  To update local edits as new versions:
    azd ai agent eval update

  To overwrite and regenerate:
    azd ai agent eval generate --reset-defaults

로컬 구성을 덮어쓰고 기본 평가 자산을 다시 생성하려면 다음을 실행합니다.

azd ai agent eval generate --reset-defaults

--reset-defaults 로컬 eval.yaml 을 덮어쓰고 기본 평가 자산을 다시 생성합니다. 기존 서비스에 등록된 데이터 세트와 평가기 버전은 삭제되지 않으며, 오직 로컬 레시피만 대체됩니다.

로컬 레시피를 자동으로 변경하는 원격 최신 버전에 의존하지 마세요. 로컬 eval.yaml 은 재현성을 위해 레시피에서 사용하는 데이터 세트, 계산기 또는 제품군 버전을 기록합니다.

선택 사항: 평가 신호에서 최적화 시작

하나 이상의 평가 실행이 성공하면 에이전트 및 레시피가 최적화 필수 구성 요소를 충족하는 경우 에이전트 최적화에 대한 입력으로 사용할 eval.yaml 수 있습니다.

최적화를 시작하기 전에 다음을 확인합니다.

• 에이전트 대상은 최적화할 준비가 완료되었습니다. 호스트된 에이전트의 경우 에이전트가 배포되고 호출할 수 있습니다.
• eval.yaml 는 의도한 에이전트, 데이터 세트, 평가기 버전 및 임계값을 참조합니다.
• 하나 이상의 평가 실행이 성공적으로 완료되었습니다.
• 최적화 프로그램에서 필요한 에이전트 준비가 완료되었습니다. 최적화 프로그램 필수 구성 요소 및 에이전트 준비 요구 사항은 프롬프트 최적화 프로그램에서 에이전트 프롬프트 최적화를 참조하세요.

다음을 실행합니다.

azd ai agent optimize --config eval.yaml

최적화 명령은 에이전트 대상, 데이터 세트, 계산기 및 임계값을 읽습니다 eval.yaml. 최적화 작업을 제출하지만 자동으로 원본 변경 내용을 적용하거나 후보 에이전트를 다시 배포하지는 않습니다. 변경 내용을 적용하기 전에 최적화 프로그램 출력을 검토합니다.

모범 사례

• 에이전트를 평가 대상으로 사용할 수 있는 경우에만 실행 azd ai agent eval generate 합니다. 호스트된 에이전트의 경우 에이전트를 배포하고 호출할 수 있어야 합니다.
• 작은 생성된 데이터 세트 또는 골든 데이터 세트의 작은 하위 집합으로 시작합니다.
• 점수를 신뢰하기 전에 생성된 데이터 세트 및 평가자 검토 아티팩트 확인
• 생성된 데이터 세트 또는 계산기 파일을 편집한 후 평가를 다시 실행하기 전에 편집된 자산을 등록하기 위해 실행 azd ai agent eval update 합니다.
• 팀에서 검토 가능하고 재현 가능한 평가 레시피를 원하는 경우 소스 제어 eval.yaml .
• 팀이 평가 레시피의 일부로 이를 검토하고 편집한다면, 에이전트 폴더에서 datasets/ 및 evaluators/ 아래의 생성된 데이터 세트와 평가자 루브릭을 버전 관리에 포함하는 것을 고려하십시오.
• 비교에서 동일한 eval.yaml 테스트 레시피를 사용하도록 에이전트가 변경된 후 동일한 내용을 다시 실행합니다.
• 유용한 기준 평가 결과가 있고 에이전트가 최적화를 위해 준비된 후에만 사용합니다 azd ai agent optimize --config eval.yaml .

Limitations

• 기본 명령 흐름은 호스트된 에이전트 및 배포 후 평가 루프에 최적화되어 있습니다.
• azd provision 는 평가 자산을 만들지 않습니다.
• eval run는 eval generate --no-wait에서 보류 중인 작업을 다시 시작하는 경우를 제외하고는 새 데이터 세트나 평가자를 생성하지 않습니다.
• 첫 번째 평가 경로에는 전체 제품군 수명 주기, 예약된 평가, 연속 평가, 경고 및 비교 워크플로가 필요하지 않습니다.

관련 콘텐츠

• AI 에이전트 평가
• Microsoft Foundry 에이전트용 인적 평가
• 평가 클러스터 분석
• 프롬프트 최적화 프로그램에서 에이전트 프롬프트 최적화
• Microsoft Foundry에서 AI 에이전트에 대한 추적 설정
• 에이전트 모니터링 대시보드를 사용하여 에이전트 모니터링
• Foundry Agent Service의 호스팅된 에이전트
• 에이전트 개발 수명 주기