Automated agent evaluation with Amazon Bedrock AgentCore and GitHub Actions

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Amazon Bedrock AgentCore와 GitHub Actions를 연결해 OAuth로 보호된 에이전트를 배포·평가하고, 평가 점수가 기준에 미달하면 PR 병합을 차단하는 CI/CD 품질 게이트를 구축한다.

📌 핵심 요약

• 참조 구현은 CDK로 Strands 에이전트와 MCP 서버를 각각 AgentCore runtime에 배포하고, GitHub Actions에서 개발 환경의 에이전트를 대표 프롬프트로 호출한 뒤 평가한다. 품질 게이트는 1.0 만점에 0.8 같은 최소 기준을 적용해 성능 저하가 있는 PR의 병합을 차단한다.
• AgentCore Evaluations는 OpenTelemetry 추적을 바탕으로 기본적으로 LLM을 판정자로 사용하며, AWS Lambda를 통한 코드 기반 평가도 지원한다. 온디맨드 평가는 CI/CD 품질 게이트, 온라인 평가는 운영 트래픽 모니터링, 배치 평가는 기준선 측정과 변경 전후 회귀 테스트에 활용된다.
• Evaluate API의 각 evaluate() 호출에는 단일 세션의 sessionSpans만 포함해야 하며, 여러 세션을 섞으면 ValidationException이 발생한다. evaluationReferenceInputs로 expectedResponse, assertions, expectedTrajectory를 선택적으로 제공할 수 있고, 정답 기준이 없는 추적은 해당 기준 없이 평가된다.
• 공유 Cognito 사용자 풀은 CI의 client_credentials 기반 M2M 인증과 대화형 사용자의 authorization_code 인증을 지원한다. Approach C에서는 역할 정보가 없는 M2M 토큰이 역할 검사를 우회해 모든 도구에 접근하고, custom:roles가 포함된 사용자 토큰에는 도구별 역할 제한이 적용된다.
• OAuth 대응 방식에는 저장된 추적을 평가하는 Approach A, 사전 동의한 테스트 사용자의 갱신 토큰을 활용하는 Approach B, M2M 인증을 사용하는 Approach C가 있다. A는 현재 PR 코드의 동작을 직접 평가하지 않고, B는 갱신 토큰 만료에 대응해야 하며, C는 이중 토큰 인증 지원이 필요하고 역할 제한 자체를 시험하지 못한다.

🧩 주요 포인트

1. 시스템 프롬프트·모델·도구 설정 변경을 배포와 평가에 연결 → 에이전트 품질 저하를 운영 반영 전에 PR 단계에서 발견하는 구조가 된다.
2. 온디맨드·온라인·배치 평가가 서로 다른 실행 시점을 담당 → 변경 승인, 운영 품질 관찰, 기준선 비교에 맞춰 평가 방식을 선택할 수 있다.
3. Approach A·B·C의 인증 방식이 평가 범위를 결정 → 현재 PR의 실시간 동작 검증과 사용자 역할 제한 검증을 구분해 접근 방식을 선택해야 한다.

🧠 상세 정리

1. 에이전트 변경을 PR 단계에서 검증하려는 배경

글은 Amazon Bedrock AgentCore runtime에 배포한 에이전트가 OAuth로 보호된 MCP 서버의 도구를 호출하는 상황에서 출발한다. 시스템 프롬프트를 수정하거나 모델을 교체하거나 도구 설정을 바꿀 때마다 응답 품질이 좋아졌는지 나빠졌는지 확인해야 하지만, 수동 테스트만으로는 이런 검증을 지속하기 어렵다는 문제를 제시한다. 제안하는 방식은 GitHub Actions가 개발 환경에 에이전트를 자동 배포하고 대표 평가 프롬프트로 호출한 뒤, AgentCore Evaluate API를 이용해 행동을 평가하는 것이다. 평가 점수가 최소 기준에 미달하면 PR을 실패시켜 병합을 차단하며, 기준의 예로 1.0 만점에 0.8을 든다. 이를 통해 개발자의 변경 이후 사용자 불만이 발생할 때까지 품질 저하를 놓치는 상황을 줄이려는 것이 글의 핵심 목적이다.

2. 런타임·도구·관측·인증을 연결하는 구성 요소

AgentCore runtime은 Python과 다양한 프레임워크로 작성한 에이전트 코드를 호스팅하고, 확장과 세션 격리 및 인프라를 관리하는 플랫폼으로 설명된다. MCP는 외부 도구를 표준 인터페이스로 호출하는 개방형 프로토콜이며, 에이전트는 MCP 서버가 노출한 도구를 발견하고 호출하고 AgentCore runtime은 이 서버도 호스팅할 수 있다. AgentCore Observability는 추적을 수집하고 AgentCore Evaluations는 그 추적을 평가하므로, 구성 요소들은 빌드·배포·관측·평가의 흐름을 이룬다. GitHub Actions의 AWS 접근에는 OIDC 연합을 사용해 장기 자격 증명을 저장하지 않고 AWS IAM 역할을 맡는 방식이 소개된다. GitHub가 발급한 단기 토큰을 AWS가 검증하면 워크플로에 임시 자격 증명이 제공되며, 이는 OAuth로 보호된 에이전트 호출을 위한 Cognito 인증과 별도로 설명되는 인증 경로다.

3. 세 가지 평가 모드와 각 모드의 용도

AgentCore Evaluations는 기본적으로 LLM을 판정자로 사용해 에이전트 행동을 점수화하며, AWS Lambda를 이용한 코드 기반 평가도 선택할 수 있다. 온디맨드 평가는 특정 세션의 span 데이터를 API 호출에 직접 제공하고 평가기를 선택해 점수를 받는 방식으로, 이 글의 CI/CD 품질 게이트를 구동한다. 온라인 평가는 설정 가능한 샘플링 비율로 운영 트래픽을 지속적으로 평가하며, 결과는 추세 관찰을 위한 CloudWatch 대시보드로 전달된다. 배치 평가는 CloudWatch Logs를 대상으로 여러 세션을 하나의 비동기 작업에서 평가하고, 집계 결과와 세션별 결과를 함께 제공한다. 따라서 온디맨드는 변경 시점의 검증, 온라인은 운영 중 관찰, 배치는 기준선 측정과 변경 전후 회귀 테스트라는 서로 다른 단계에 대응한다.

4. 평가기의 선택과 Evaluate API의 입력 제약

평가기는 기본 제공, 사용자 정의, 코드 기반, 서드파티의 네 범주로 나뉘며, 기본 제공 평가에는 Helpfulness, Correctness, GoalSuccessRate, ToolSelectionAccuracy, ToolParameterAccuracy 등이 포함되고 세션·추적·도구 호출 수준에서 작동한다. TrajectoryExactOrderMatch, TrajectoryInOrderMatch, TrajectoryAnyOrderMatch는 실제 도구 호출 순서를 예상 경로와 비교한다. 사용자 정의 평가기는 도메인별 LLM 판정 프롬프트를 사용하고 정답 기준 필드를 자리표시자로 활용할 수 있으며, 코드 기반 평가기는 Lambda에서 정규식 일치·스키마 검증·키워드 존재 같은 결정적 검사를 수행해 점수와 라벨 및 설명을 반환한다. DeepEval과 AutoEval의 서드파티 평가기는 별도 모델이나 구성 없이 ID로 선택할 수 있고, 기본 제공 또는 서드파티 평가기에서 파생한 사용자 정의 평가기는 자체 모델로 실행할 수도 있다. Evaluate API는 sessionSpans를 받아 구조화된 점수를 반환하지만, 각 evaluate() 호출에 여러 세션의 span을 섞으면 ValidationException이 발생한다. 선택 입력인 evaluationReferenceInputs에서는 expectedResponse를 Correctness에, assertions를 GoalSuccessRate에, expectedTrajectory를 경로 평가기에 제공하며, 정답 기준이 없는 추적은 그 기준 없이 평가하므로 필요한 턴에만 기준을 추가할 수 있다.

5. 공유 Cognito 사용자 풀을 사용하는 배포 구조

참조 아키텍처는 공유 Cognito 사용자 풀 뒤에 두 개의 AgentCore runtime을 배치하며, 하나는 Strands 에이전트용이고 다른 하나는 MCP 서버용이다. 같은 사용자 풀이 두 인증 흐름을 지원하지만, CI 파이프라인의 client_credentials 토큰에는 범위 정보만 있고 대화형 사용자의 authorization_code 토큰에는 범위 정보와 custom:roles가 함께 포함된다. 제시된 MCP 접근 정책에서 M2M 토큰은 역할 검사 없이 모든 도구에 접근하고, 사용자 토큰은 역할에 따라 도구 접근이 제한된다. GitHub Actions는 개발 환경에 스택을 배포한 뒤 Cognito에서 JWT를 받아 에이전트 API 호출을 인증하고, 평가 데이터셋으로 에이전트를 실행한다. 이후 Amazon CloudWatch Logs에 생성된 추적을 분석해 정의된 임계값과 전체 점수를 비교하고, 수용 기준 충족 여부에 따라 PR의 통과 또는 차단을 결정한다.

6. 저장된 추적과 테스트 사용자로 OAuth 문제를 처리하는 대안

Approach A는 실시간 MCP 호출과 평가를 분리하는 방식으로, 스테이징 파이프라인이 대표 프롬프트로 에이전트를 실행해 추적을 수집하고 이를 JSON 픽스처로 커밋한 뒤 PR 시점에 저장된 추적을 평가한다. Evaluate API는 살아 있는 에이전트 없이 전달받은 OpenTelemetry span을 평가할 수 있으므로 OAuth 문제를 피하고 높은 결정성을 얻지만, 평가 대상은 현재 PR의 코드가 아니라 스테이징 배포의 행동이다. 저장된 추적 방식의 시작점으로 저장소의 scripts/evaluate_stored_traces.py와 fixtures/가 제시된다. Approach B는 전용 테스트 사용자가 대화형 OAuth 동의를 한 번 완료하고 갱신 토큰을 AWS Secrets Manager에 저장한 뒤, CI가 그 사용자로 에이전트를 호출하는 방식이다. B는 실시간 호출과 역할 검증이 가능하고 모든 MCP 서버에 적용할 수 있지만, 갱신 토큰이 만료되므로 교체 메커니즘이나 주기적인 수동 재동의가 필요하다. 비교표는 A를 빠른 시작에, B를 역할까지 포함한 전체 종단 간 테스트에 적합한 선택으로 설명한다.

7. M2M 인증의 작동 방식과 역할 검증의 한계

이 글이 채택한 Approach C는 MCP 서버가 M2M과 사용자 범위 인증을 모두 지원하도록 구성하고, CI에는 M2M 토큰을 사용하며 대화형 사용자는 일반적인 OAuth 동의 흐름을 거치게 한다. MCP 서버 미들웨어는 토큰 유형을 구분해 범위 정보만 있고 역할 정보는 없는 M2M 토큰의 역할 검사를 우회하며, custom:roles가 있는 사용자 토큰에는 도구별 접근 통제를 적용한다. 글은 M2M 토큰 발급에 최종 사용자에게 노출되지 않는 클라이언트 비밀이 필요하고 CI 파이프라인과 에이전트 런타임만 이 토큰을 얻을 수 있다는 점을 우회의 보안 근거로 제시한다. 다만 역할 검사를 우회하는 설계 때문에 C로는 사용자 역할 제한 자체를 검증할 수 없으며, 그 검증이 필요하면 B를 사용해야 한다. C는 이중 토큰 인증을 지원하는 MCP 서버가 필요하고 내부 도구 에이전트에 적합한 방식으로 소개된다. 글은 우선 A로 품질 게이트를 빠르게 구축하고, 이후 실제 PR의 코드 변경을 종단 간으로 시험하는 C로 확장하는 순서를 권한다.

8. 실행 준비와 세 계층 인증 패턴의 도입

실행 전제는 AgentCore 접근 권한과 CDK 부트스트랩이 준비된 AWS 계정, 설치되어 실행 중인 Docker, Python 3.12 이상, Node.js 20 이상이다. 필요한 Python 패키지로 boto3, requests, bedrock-agentcore-starter-toolkit을 설치하도록 안내한다. bedrock-agentcore-starter-toolkit의 Evaluation 클래스는 CloudWatch 추적 수집과 점수화를 자동 처리하므로, 사용자가 로그 그룹을 직접 조회하거나 원시 Evaluate API를 직접 호출할 필요가 없다고 설명한다. 이어 Approach C의 MCP 서버가 M2M 토큰과 사용자 범위 토큰을 함께 지원하기 위해 세 계층 인증 패턴을 사용한다고 소개하며, CI 평가와 운영 환경의 역할 제한을 함께 유지하는 핵심 패턴으로 제시한다. 첫 계층에서는 AgentCore가 요청이 애플리케이션 코드에 도달하기 전에 JWT의 서명·발급자·대상·만료를 검증한다. 제공된 source_body는 이 첫 계층의 설명 도중에 끝나므로, 나머지 두 계층과 이후 구현 세부 사항은 확인할 수 없다.

🧾 핵심 주장 / 시사점

• 품질 게이트의 실효성은 평가 대상이 현재 PR의 변경을 반영하는지에 달려 있다. Approach A는 평가 실행을 단순하게 만들지만, 현재 코드의 행동을 직접 확인하는 범위까지 제공하지는 않는다.
• M2M 인증으로 실시간 평가가 가능해져도 사용자 역할 제한 검증까지 충족되는 것은 아니다. Approach C의 역할 우회와 Approach B의 사용자 인증은 서로 다른 검증 목적에 대응한다.
• 평가 점수는 평가기와 선택적 정답 기준의 영향을 받는다. Correctness, GoalSuccessRate, 경로 평가기에 어떤 기준을 제공할지와 단일 세션 입력 제약을 함께 고려해야 한다.

✅ 액션 아이템

• GitHub Actions의 PR 품질 게이트에 적용할 최소 평가 점수를 정하고, 1.0 만점에 0.8이라는 예시 기준의 적합성을 검토.
• 현재 PR의 실시간 동작 검증과 사용자 역할 제한 검증의 필요에 따라 Approach A·B·C를 선택.
• Evaluate API 호출을 단일 세션의 sessionSpans로 구성하고, 필요한 평가에 evaluationReferenceInputs를 제공.

❓ 열린 질문

• GitHub Actions 품질 게이트의 최소 평가 점수로 1.0 만점에 0.8을 적용할 것인가, 다른 수용 기준이 필요한가?
• 현재 PR의 실시간 동작 검증과 사용자 역할 제한 검증 중 어떤 범위가 필요하며, Approach A·B·C 가운데 무엇이 적합한가?
• evaluationReferenceInputs의 expectedResponse, assertions, expectedTrajectory 가운데 어떤 정답 기준을 제공할 것인가?