getedgehq/agent-evals

에이전트 평가(eval)

평가(eval)는 하나의 질문에 답합니다: 에이전트가 작업을 올바르게 수행했습니까? 아래의 모든 내용은 이 질문을 더 신뢰성 있고, 더 저렴하게, 더 자주 물을 수 있는 방법입니다.

2026년 Alex Lieberman과 Viv(LangChain)의 평가 마스터클래스를 기반으로 제작되었습니다: youtube.com/watch?v=zLeG-XJtbIE. 구조(easy, hard, god mode)는 그들의 것입니다. 이 스킬의 오류는 우리의 것입니다.

사용자에게 세 가지를 먼저 물어보세요

1. 에이전트가 수행하는 실제 작업은 무엇인가요? 에이전트가 접촉하는 시스템(CRM, 받은 편지함, 저장소, 데이터베이스)을 지정하세요.
2. 현재 회사에서 그 작업을 가장 잘 수행하는 사람은 누구인가요? 그 사람의 판단이 기준 진실(ground truth)입니다.
3. 에이전트가 아직 프로덕션에서 실행 중인가요? 그렇다면 추적(trace)이 어딘가에 저장되어 있나요?

답변에 따라 모드를 선택하세요. 작업과 확인자 없이 god mode로 건너뛰지 마세요.

Easy mode: 작업과 확인자

작업(task) 은 실제 업무의 작고 확인 가능한 조각입니다. 확인자(verifier) 는 해당 작업이 올바르게 수행되었는지 알려줍니다.

1. 실제 동료가 수행하는 작업을 모방한 10~30개의 작업을 작성하세요. 영업 에이전트의 예시:
   • 통화 후 CRM 레코드에 메모 추가
   • 명백한 테이블에 없는 잠재 고객 찾기
   • 회신 이메일 초안 작성(보내지 않고)
2. 각 작업에 대해 확인자를 작성하세요. 다음 순서로 선호합니다:
   • 상태 확인(State check) (스크립트): 필드가 비어 있었다가 작업 후 올바른 값을 가지는지; email_sent 태그가 존재하는지 확인합니다.
   • 체크리스트(Checklist) (모델 또는 사람): 직접 확인할 수 없는 경우, '좋음'을 예/아니오 질문으로 나누세요. "세 문단 이하인가?" "브랜드 톤 규칙을 따르는가?"
3. 모든 판단은 이진(binary)으로 유지하세요. 1~10점 척도를 요청받은 모델은 대부분 7점에 몰리고 애매하게 표현합니다. 예/아니오는 애매할 수 없습니다.
4. 해당 작업의 최고 전문가로부터 서면으로 체크리스트를 받으세요. 에이전트를 실행하고 샘플을 수동으로 검토하세요. 출력이 체크리스트를 통과했지만 여전히 이상하게 느껴진다면 체크리스트가 불완전한 것입니다. 누락된 질문을 추가하세요.

Easy mode의 결과물: 각 작업마다 지시사항과 확인자가 포함된 폴더, 그리고 통과율.

Hard mode: 환경

환경(environment) 은 에이전트가 작업을 수행하는 장소입니다: 파일, 도구, 데이터 및 권한. 절대 프로덕션 데이터에 대해 평가를 실행하지 마세요. 평가에 실패한 에이전트가 실제 CRM도 편집하게 됩니다.

1. 에이전트에게 실제처럼 보이는 복사본을 구축하세요: 동일한 테이블, 동일한 도구, 가짜 레코드. 실행할 때마다 동일한 상태로 재설정되도록 패키징하세요(컨테이너가 일반적인 선택입니다).
2. 하나의 작업 = 지시사항 + 환경 + 확인자. 함께 저장하세요.
3. 가능하다면 자체 러너를 개발하지 마세요. Harbor(github.com/harbor-framework/harbor)는 작업, 환경 및 확인자를 위한 공유 형식과 적응 가능한 많은 게시된 작업을 제공합니다.
4. 환경 자체를 테스트하세요. 첫 번째 환경은 틀릴 것입니다. 여러 다른 에이전트나 모델을 실행하고 이상한 패턴을 찾으세요:
   • 강력한 모델이 약한 모델에게 실패하는 경우
   • 에이전트가 있어서는 안 되는 곳(플레이스홀더 행, 유출된 파일)에서 답을 찾는 경우. 에이전트는 통과하기 위해 지름길을 택할 것입니다. 누출을 제거하세요.
5. 모든 작업을 계열(family)별로 태그하세요 (코딩, 영업, 코드 리뷰). 새 모델이 출시되면, 해당 모델이 강점을 가질 가능성이 있는 계열만 실행하세요.
6. 느낌이 아닌 표로 모델을 선택하세요. 각 후보 모델을 동일한 태그된 작업에서 실행하세요. 통과율, 비용 및 속도를 나란히 기록하세요. 그런 다음 사람이 결정합니다: 이 작업 계열에서 5포인트의 정확도가 3배의 비용을 정당화하는가? 사용자 대면 작업은 일반적으로 최상위 모델을 정당화하지만, 내부 작업은 그렇지 않은 경우가 많습니다.

Hard mode의 결과물: 하나의 명령으로 모든 모델에서 재실행할 수 있는 평가 스위트, 작업 계열별 결과 테이블.

God mode: 개선 루프

루프: 에이전트가 실행되고, 추적(trace)을 생성하고, 실패가 새로운 작업이 되고, 에이전트가 수정되고, 반복됩니다.

1. 추적을 켜세요. 추적은 모든 행동의 로그입니다: 각 도구 호출, 각 메시지, 각 결과. 아무도 에이전트가 무엇을 할지 예측할 수 없습니다. 누구나 에이전트가 무엇을 했는지 판단할 수 있습니다.
2. 추적을 한 곳에 저장하세요. 단일 개발자의 경우, 에이전트 자체의 디스크 로그로 충분합니다. 팀의 경우, 권한이 있는 추적 제품을 사용하세요.
3. 두 번째 에이전트를 추적에 투입하세요. 이 에이전트의 유일한 작업은 패턴을 찾는 것입니다. 좋은 행동과 나쁜 행동에 대한 간략한 브리핑을 제공하세요. 다음을 요청하세요:
   • 실패하거나 반복된 도구 호출
   • 무시되거나 절반만 수행된 지시사항
   • 반복되는 잘못된 경로(항상 잘못된 테이블 검색, 3개 요청 시 1개 회사만 처리)
4. 확인된 각 실패를 평가 스위트의 작업으로 전환하세요. 그래야 조용히 다시 발생하지 않습니다.
5. 에이전트를 수정하세요. 가장 저렴한 레버부터:
   • 하네스(harness): 프롬프트, 도구 설명, 도구 세트, 모델 선택
   • 좁은 작업에 대해 소형 오픈 모델을 미세 조정(스위트가 대형 모델과 일치함을 입증한 후)
6. '좋음'의 기준에 사람을 유지하세요. 에이전트는 수정 제안을 하고 작업 초안을 작성할 수 있습니다. 사람은 여전히 어떤 작업이 비즈니스에 중요한지 결정하고 새로운 작업을 검토합니다. 이를 문서화하는 것이 루프에서 가장 영향력이 큰 부분입니다.

규칙

• 실제 작업이 명명되지 않은 평가는 없습니다. 일반 벤치마크는 에이전트가 작동하는지 알려주지 않습니다.
• 이진 확인자만 사용하세요. 모든 점수를 예/아니오 질문으로 나누세요.
• 절대 평가가 프로덕션 데이터에 접근하지 못하게 하세요.
• 모든 것을 통과하는 스위트는 망가진 스위트입니다. 누출을 확인하세요.
• 통과율을 작업 개수와 함께 보고하세요("21/30"). 절대 백분율만 보고하지 마세요.