AI 에이전트를 위한 하네스 설계: 작동 방식을 설명하는 실제 링크

실제 하네스 링크: 실행한 후 출력합니다.

코드 검토 에이전트를 구축한다고 가정해 보겠습니다. 핵심 작업은 LLM을 사용하여 PR 차이를 분석한 다음 통과 또는 실패 결론을 생성하는 것입니다. 테스트할 때마다 문자 그대로 편집기를 열고 PR을 생성하고 GitHub 웹훅을 기다리고 싶지는 않습니다. 하네스가 필요합니다.

AI 에이전트를 위한 하네스 설계의 핵심 아이디어는 에이전트의 실행 프로세스를 외부 세계와 격리하고 제어 가능한 입력 및 어설션을 사용하여 동작을 검증하는 것입니다. 이 링크는 모의 입력 → 에이전트 실행 → 어설션 출력의 세 단계로 구분됩니다.

1단계: 실제 외부 호출 대신 모의 입력

가장 흔한 실수는 에이전트를 실제 API에 직접 연결하는 것입니다. Harness는 외부 응답을 미리 녹음하거나 위장하여 이를 수행합니다. 예를 들어 코드 검토 에이전트의 경우 GitHub의 PR 데이터, 차이점 콘텐츠, 심지어 LLM 반환까지 모의해야 합니다.

쉬운 실패: 모의 데이터가 너무 깨끗합니다. 실제 환경의 PR 댓글에는 @멘션, 빈 줄, 잘못된 문자가 포함될 수 있습니다. 하네스가 잘 포맷된 샘플만 사용한다면 에이전트는 생산 과정에서 다양한 사고를 겪게 됩니다. 올바른 접근 방식은 일반 diff, 주석이 많은 diff, 일부 파일이 삭제된 diff 등 최소한 3가지 변형을 포함하는 것입니다.

2단계: 에이전트가 하네스에서 실행되고 전체 로그를 수집하도록 합니다.

터미널의 인쇄 출력만 보지 마십시오. 하네스는 에이전트 사고 체인의 모든 단계, 모든 도구 호출 및 최종 결정을 포착해야 합니다. 예를 들어 에이전트는 내부적으로 두 개의 도구 analyze_diff 및 check_style를 호출할 수 있으며 Harness는 각 도구의 입력, 출력 및 시간 소비를 기록해야 합니다.

실행 가능한 접근 방식: 에이전트 코드에 구조화된 로그를 삽입하고 각 단계의 컨텍스트를 JSON 형식으로 출력합니다. 테스트할 때 Harness는 최종 결과를 주장하고 중간 단계가 합리적인지 확인할 수 있습니다. 예를 들어 analyze_diff의 반환에 함수 서명 변경 사항이 포함되어 있는지 확인합니다.

3단계: 단순한 "성공/실패"가 아닌 출력 주장

단순히 에이전트의 최종 출력이 통과인지 실패인지 확인하는 것만으로는 충분하지 않습니다. 하네스를 사용하면 출력의 구조, 내용 및 톤까지 검사할 수 있습니다. 예를 들어 코드 검토 에이전트의 경우 다음을 어설션할 수 있습니다.

• 출력에는 approved: true/false 필드가 포함되어야 합니다.
• diff에 보안 취약점이 있는 경우 주석에 "vulnerability"라는 단어가 포함되어야 합니다.
• 차이점이 문서에만 관련된 경우 상담원은 검토를 건너뛰어야 합니다.

쉬운 실패: 어설션이 너무 구체적으로 작성되어 하네스와 에이전트 간의 강한 결합이 발생합니다. 에이전트의 출력 형식이 조정되면 하네스가 완전히 다운됩니다. 하드 코딩된 필드 경로 대신 스키마(예: Pydantic 또는 JSON 스키마)를 사용하여 인터페이스 계층에서 어설션을 정의하는 것이 좋습니다.

실제 시나리오: GitHub PR에서 로컬 하네스까지

내 동료 중 한 명이 Harness를 사용하여 코드 검토 에이전트를 테스트했습니다. 그는 에이전트의 승인이 사실이고 댓글에 "LGTM"이 나타날 것으로 기대하면서 SQL 주입 수정이 포함된 PR diff를 조롱했습니다. 첫 번째 실행에서 에이전트는 승인했지만 출력은 "Looks good to me"였으며 사례 사례가 일치하지 않아 Harness 어설션이 실패했습니다. 그는 에이전트가 항상 "LGTM"을 사용하도록 요구하는 프롬프트를 수정했습니다.

이 작은 예는 Harness가 기능적 정확성을 확인할 수 있을 뿐만 아니라 동작의 일관성도 확인할 수 있음을 보여줍니다. Harnees에 이러한 경계가 설정되지 않은 경우 에이전트는 온라인 상태가 된 후 사용자를 다른 표현으로 혼동시킬 수 있습니다.

쉬운 실패와 오해

• 오해: 하네스는 테스트 프레임워크입니다. 실제로 Harness는 단순한 어설션 도구라기보다는 제어 가능하고 반복 가능한 런타임 환경에 더 가깝습니다. 모의, 로깅, 어설션은 물론 에이전트 수명 주기까지 관리합니다.
• 함정: 모의 데이터에 극단적인 경우가 누락되었습니다. 실제 LLM은 매우 긴 텍스트나 빈 내용을 반환할 수 있으며, 조롱 시 이러한 값을 덮어써야 합니다.
• 함정: 타이밍 종속성 무시. 일부 에이전트는 단계 사이의 시간 간격에 의존하므로 하네스가 가속되면 동작이 변경될 수 있습니다. 필요한 경우 가상 시계를 하네스에 도입할 수 있습니다.

지금 착륙하고 싶다면 첫 번째 단계는 무엇입니까?

1. 단일 도구, 단일 작업 에이전트(예: 날씨를 쿼리하는 에이전트)와 같은 간단한 에이전트를 선택합니다.
2. Python을 사용하여 set_mock_response, run, assert_output 세 가지 메서드를 포함하는 Harness 클래스를 작성합니다.
3. 3개의 서로 다른 실제 사용자 쿼리를 기록하고 해당 모의 입력을 수동으로 구성합니다.
4. Harness를 실행하고 Agent 출력이 예상한 것과 같은지 확인합니다.
5. 의도적으로 오류를 도입하고(예: 모의 항목에 필요한 필드가 누락됨) Harness가 오류를 포착할 수 있는지 관찰합니다.

이 5단계를 완료하면 재사용 가능한 하네스 베이스라인 세트를 갖게 됩니다. 그런 다음 어설션 세분성을 확장하고 로그 수집 등을 도입할 수 있습니다.

체계적인 학습을 이어가려면 어디로 가야 할까요?

위 단계를 이미 연습했다면 다음 단계인 Harness를 CI/CD 파이프라인에 통합하는 방법, 다중 에이전트 협업 시나리오를 위해 Harness를 설계하는 방법, Harness를 관찰 도구(예: Langfuse)와 결합하는 방법을 배워야 합니다. 고품질의 원본 유료 기사와 AI 고급 프로그래밍 과정이 이러한 내용을 다루며 일반 개발자에서 에이전트 엔지니어로 체계적으로 변화하는 데 도움이 됩니다.