본문으로 건너뛰기

AgentCore 에이전트 평가로 PR 품질 게이트 구축

GitHub Actions가 AgentCore 에이전트를 배포·호출·평가하고 점수 하락 시 PR을 차단합니다.

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

이 글은 Amazon Bedrock AgentCore에 배포한 Strands 에이전트와 OAuth로 보호된 MCP 서버를 GitHub Actions에서 자동 평가하고, 점수가 0.8 아래로 떨어지면 PR을 차단하는 CI/CD 품질 게이트 구현을 안내합니다. CDK가 Cognito 사용자 풀, 에이전트 런타임, MCP 런타임과 IAM 리소스를 배포하고, 파이프라인은 client_credentials 흐름으로 M2M 토큰을 받아 에이전트를 호출한 뒤 CloudWatch의 OpenTelemetry trace를 AgentCore Evaluations에 전달합니다. MCP 서버는 AgentCore의 JWT 검증, Authorization 헤더 전달, FastMCP 미들웨어의 역할 검사라는 세 계층으로 인증을 처리하며, M2M 토큰은 역할 검사를 우회하고 사용자 토큰은 custom:roles에 따라 도구 접근을 제한합니다. GoalSuccessRate, Correctness, ToolSelectionAccuracy, ToolParameterAccuracy를 사용한 예제에서는 나쁜 system prompt가 0.0점과 PR 차단을 만들었고, 수정 후에는 0.9~1.0점으로 통과했지만 평가 지연, ARM64 이미지 요구 사항, LLM-as-a-judge의 점수 변동성과 비용을 함께 고려해야 합니다.

섹션별 상세

01
에이전트의 system prompt, 모델, 도구 설정이 바뀔 때 수동 테스트만으로 품질 저하를 발견하기 어렵기 때문에 CI 단계에서 대표 프롬프트를 실행하고 응답을 채점하는 구조가 필요합니다. 파이프라인은 dev 환경에 에이전트와 MCP 서버를 배포하고, 에이전트를 호출해 trace를 수집한 뒤 임계값과 비교합니다. 전체 점수가 기준 아래로 내려가면 GitHub Actions 작업이 실패해 PR 병합을 막습니다.
02
Amazon Bedrock AgentCore는 에이전트 런타임, 관측, 평가를 연결해 배포부터 품질 판정까지 이어지는 흐름을 구성합니다. On-demand 평가는 단일 세션의 sessionSpans를 직접 받아 즉시 점수를 반환하고, online 평가는 샘플링된 운영 트래픽을 지속적으로 모니터링하며, batch 평가는 CloudWatch Logs의 여러 세션을 비동기 방식으로 집계합니다. 평가자는 Helpfulness와 Correctness 같은 trace 수준 항목부터 ToolSelectionAccuracy와 ToolParameterAccuracy 같은 도구 호출 수준 항목까지 선택할 수 있습니다.
03
에이전트와 MCP 서버는 하나의 Cognito user pool을 공유하지만 CI와 대화형 사용자의 인증 흐름은 분리됩니다. GitHub Actions는 client_credentials로 역할 클레임이 없는 M2M 토큰을 받고, 대화형 사용자는 authorization_code로 custom:roles가 포함된 사용자 토큰을 받습니다. MCP 미들웨어는 M2M 토큰에는 전체 도구 접근을 허용하고 사용자 토큰에는 도구 메타데이터와 역할 클레임을 비교해 권한을 적용합니다.
04
OAuth 보호 MCP 서버를 CI에서 평가하는 방법은 저장된 trace 평가, 사전 승인된 서비스 계정, M2M 인증 세 가지입니다. 저장된 trace 방식은 라이브 호출과 OAuth 문제를 없애지만 현재 PR 코드가 아니라 staging 동작을 평가하고, 서비스 계정 방식은 역할 테스트가 가능하지만 refresh token 회전이 필요합니다. 글의 M2M 방식은 현재 PR의 실제 코드를 end-to-end로 검증하기 좋지만 역할 검사를 의도적으로 우회하므로 역할별 권한 테스트에는 적합하지 않습니다.
05
인증 처리는 AgentCore 플랫폼의 JWT 서명·발급자·audience·만료 검증, 두 런타임의 Authorization 헤더 전달, FastMCP AuthMiddleware의 custom:roles 판정으로 나뉩니다. request_header_allowlist에 Authorization을 등록하면 호출자의 JWT가 에이전트 컨테이너와 MCP 컨테이너까지 전달되고, 미들웨어는 get_http_headers()로 헤더를 읽어 PyJWT로 클레임을 해석합니다. 이 분리는 플랫폼 인증과 애플리케이션 권한 판정을 분리하면서 사용자 호출과 CI 호출에 같은 에이전트 코드를 사용할 수 있게 합니다.
06
CDK 스택은 Cognito domain, M2M 및 사용자용 app client, user-a와 user-b, 두 AgentCore 런타임, JWT authorizer와 IAM 역할을 한 번에 생성합니다. GitHub Actions는 OIDC federation으로 장기 AWS 자격 증명을 저장하지 않고 IAM 역할을 맡은 뒤 CDK 배포, 출력값 추출, 런타임 준비 상태 확인, 평가, 결과 게시와 스택 삭제를 순서대로 실행합니다. 런타임이 READY가 되기 전에 호출하면 424 Failed Dependency가 발생하므로 워크플로는 get_agent_runtime을 폴링하고 MCP 서버를 예열합니다.
07
통합 평가 스크립트는 토큰 발급, AgentCore HTTPS 호출, trace 전파 대기, 평가 실행과 임계값 판정을 하나의 흐름으로 묶습니다. 예제는 2+2, UTC 현재 시각, AAPL 주가, engineering 부서 직원 수를 묻고 네 가지 내장 평가자의 결과를 evals_results/ci_output.json에 저장합니다. 의도적으로 모든 질문에 I cannot help you라고 답하게 만들면 GoalSuccessRate와 Correctness가 0.0으로 떨어져 PR이 차단되고, 정상 prompt로 되돌리면 GoalSuccessRate 1.0, Correctness 0.9, 나머지 두 평가 1.0으로 통과합니다.
08
실행 환경에는 Python 3.12+, Node.js 20+, Docker, CDK 부트스트랩이 필요하고 AgentCore 런타임용 ARM64 컨테이너를 준비해야 합니다. GitHub의 x86_64 runner에서 ARM64 이미지를 만들려면 QEMU와 Docker Buildx를 사용해야 하며, trace 전파에는 30~90초가 걸릴 수 있어 스크립트가 최대 10분 동안 재시도합니다. PR 한 건에서 네 평가자와 다섯 프롬프트를 사용하면 judge 모델 호출이 20회 발생하고 전체 파이프라인은 약 10분이 걸리므로 임계값, 비용, 평가 변동성을 함께 관리해야 합니다.

이미지 분석

GitHub Actions가 CDK 배포, M2M 토큰 발급, 에이전트 호출, 평가 실행을 차례로 거쳐 점수를 임계값과 비교하는 구조입니다.
Diagram

다이어그램은 GitHub Actions가 Amazon Cognito에서 client_credentials 토큰을 받고 Bearer 토큰으로 AgentCore Runtime을 호출하는 흐름을 보여줍니다. 런타임 안에서는 Strands 에이전트가 FastMCP 서버로 토큰을 전달하고, Amazon Bedrock AgentCore Evaluations가 OpenTelemetry trace와 LLM-as-a-judge 결과를 이용해 PR 병합 또는 차단을 결정합니다.

GitHub Actions가 CDK 배포, M2M 토큰 발급, 에이전트 호출, 평가 실행을 차례로 거쳐 점수를 임계값과 비교하는 구조입니다.

OAuth 보호 여부와 역할 기반 도구 접근 테스트 필요성에 따라 세 가지 에이전트 평가 방식을 선택하는 의사결정 트리입니다.
Diagram

OAuth가 없으면 IAM 인증을 사용하는 SDK 호출을 선택하고, OAuth가 있으면 역할 테스트 가능 여부와 CI에서 사용자 로그인을 자동화할 수 있는지에 따라 접근법이 갈립니다. 저장된 trace 방식은 라이브 호출 없이 평가하며, 서비스 계정 방식은 역할별 토큰을 사용하고, M2M 방식은 client_credentials로 서비스 간 인증을 처리하지만 역할 검사를 우회합니다.

OAuth 보호 여부와 역할 기반 도구 접근 테스트 필요성에 따라 세 가지 에이전트 평가 방식을 선택하는 의사결정 트리입니다.

용어 해설

품질 게이트(Quality Gate)
CI/CD 파이프라인에서 테스트 점수가 정해진 기준을 넘을 때만 다음 단계나 코드 병합을 허용하는 장치입니다. 이 글에서는 AgentCore 평가 점수가 예를 들어 1.0점 만점에 0.8 이상이어야 PR 병합을 진행하도록 구성합니다. 에이전트 변경 사항이 운영 환경에 도달하기 전에 성능 저하를 차단하는 역할을 합니다.
LLM 평가자(LLM-as-a-judge)
LLM이 다른 에이전트의 응답이나 도구 호출 결과를 미리 정한 품질 기준에 따라 채점하는 평가 방식입니다. AgentCore Evaluations는 OpenTelemetry trace를 읽고 유용성, 정확성, 목표 달성률 같은 항목을 평가합니다. 같은 입력을 반복 평가할 때 점수가 달라질 수 있어 임계값에 여유를 둬야 합니다.
OAuth 클라이언트 자격 증명 흐름(OAuth client_credentials)
사용자 로그인 없이 서비스나 애플리케이션이 client ID와 client secret으로 액세스 토큰을 발급받는 OAuth 흐름입니다. 이 글에서는 GitHub Actions가 M2M 토큰을 받아 AgentCore 런타임을 호출하는 데 사용합니다. 사용자 역할 정보가 없는 토큰이므로 MCP 서버에서는 역할 검사를 우회하도록 별도 정책을 적용합니다.
OpenTelemetry 트레이스(OpenTelemetry trace)
에이전트 요청 하나가 처리되는 동안 발생한 호출과 도구 실행 흐름을 span들의 연결 구조로 기록한 관측 데이터입니다. AgentCore Evaluations는 단일 세션의 span 데이터를 받아 에이전트 응답과 도구 선택을 채점합니다. 여러 세션의 span을 한 API 호출에 섞으면 ValidationException이 발생합니다.
역할 기반 접근 제어(Role-based access control)
사용자나 호출 주체의 역할에 따라 MCP 도구 사용 권한을 제한하는 방식입니다. 이 구현은 JWT 검증, Authorization 헤더 전달, custom:roles와 도구 메타데이터 비교라는 세 계층으로 권한을 처리합니다. M2M 토큰은 역할 클레임이 없어 모든 도구에 접근하고 사용자 토큰은 요구 역할을 충족해야 합니다.

코드 예제

python
def get_token() -> str:
    """Client-credentials grant"""
    resp = http_requests.post(
        os.environ["TOKEN_ENDPOINT"],
        data={
            "grant_type": "client_credentials",
            "client_id": os.environ["OAUTH_CLIENT_ID"],
            "client_secret": os.environ["OAUTH_CLIENT_SECRET"],
            "scope": os.environ.get("OAUTH_SCOPE", ""),
        },
    )
    resp.raise_for_status()
    return resp.json()["access_token"]

CI 파이프라인이 OAuth client_credentials 흐름으로 M2M 액세스 토큰을 발급받습니다.

python
def invoke_agent(agent_arn, session_id, prompt, region, token):
    """Invoke via HTTPS with Bearer token"""
    escaped_arn = urllib.parse.quote(agent_arn, safe="")
    url = f"https://bedrock-agentcore.{region}.amazonaws.com" \
        f"/runtimes/{escaped_arn}/invocations?qualifier=DEFAULT"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": session_id,
    }
    resp = http_requests.post(url, headers=headers, data=json.dumps({"prompt": prompt}))
    resp.raise_for_status()
    return resp.json()

OAuth로 보호된 AgentCore 런타임을 boto3 대신 Bearer 토큰을 포함한 HTTPS 요청으로 호출합니다.

python
results = Evaluation(region=region).run(
    agent_id=agent_id,
    session_id=session_id,
    evaluators=[
        "Builtin.GoalSuccessRate",
        "Builtin.Correctness",
        "Builtin.ToolSelectionAccuracy",
        "Builtin.ToolParameterAccuracy",
    ],
    output="evals_results/ci_output.json",
)

Starter Toolkit의 Evaluation 클래스로 CloudWatch trace 수집과 네 가지 내장 평가를 한 번에 실행합니다.

python
request_header_configuration=CfnRuntime.RequestHeaderConfigurationProperty(
    request_header_allowlist=["Authorization"]
)

AgentCore 런타임이 호출자의 Authorization 헤더를 에이전트와 MCP 컨테이너까지 전달하도록 설정합니다.

yaml
- name: Run evaluation
  working-directory: scripts
  run: python3 agentcore_eval.py
  env:
    AGENT_RUNTIME_ARN: ${{ steps.cdk.outputs.agent_arn }}
    EVAL_THRESHOLD: "0.8"

GitHub Actions가 통합 평가 스크립트를 실행하고 0.8 임계값으로 PR 통과 여부를 결정합니다.

기술

  • Amazon Bedrock AgentCore Runtime
  • Amazon Bedrock AgentCore Evaluations
  • Amazon Bedrock AgentCore Observability
  • GitHub Actions
  • Amazon Cognito
  • AWS IAM
  • AWS CDK
  • Amazon CloudWatch Logs
  • MCP
  • Strands
  • FastMCP
  • PyJWT
  • bedrock-agentcore-starter-toolkit
  • Docker Buildx
  • QEMU
  • Microsoft Entra ID

활용 사례

  • PR 병합 전 AI 에이전트 품질 회귀 차단
  • OAuth 보호 MCP 도구를 호출하는 CI 에이전트 평가
  • 도구 선택과 도구 파라미터 정확성 검증
  • 저장된 OpenTelemetry trace를 이용한 배포 전 회귀 테스트
  • 운영 에이전트의 online 평가와 추세 모니터링
AI 분석 전체 내용 보기

AI 요약 · 북마크 · 개인 피드 설정 — 무료

출처 · 인용 안내

원문 발행 2026. 09. 09.수집 2026. 09. 09.출처 타입 RSS

인용 시 "요약 출처: AI Trends (aitrends.kr)"를 표기하고, 사실 확인은 원문 보기 기준으로 진행해 주세요. 자세한 기준은 운영 정책을 참고해 주세요.