Agentic AI 기반 플랫폼 – Part3 : AgentCore Policy, Evaluation, Observability로 기업 운영 체계 구축하기

들어가며

이전 글(Part 2)에서는 Amazon Bedrock AgentCore의 Runtime, Gateway, Identity를 활용하여 MCP Registry를 구현하는 방법을 다루었습니다. 다양한 형태의 MCP를 등록하고, AgentCore Gateway를 통해 단일 엔드포인트로 통합하는 아키텍처를 소개했습니다. MCP Registry를 통해 Agent가 Tool을 호출할 수 있는 환경은 갖추었지만, 기업 환경에서 실제 운영하기 위해서는 추가적인 질문에 답해야 합니다.

• “이 사용자가 이 Tool을 호출할 권한이 있는가?” → Policy
• “Agent가 Tool을 적절하게 사용하고 있는가?” → Evaluation
• “호출 과정에서 무슨 일이 벌어지고 있는가?” → Observability

이번 글에서는 Amazon Bedrock AgentCore의 Policy, Evaluation, Observability를 활용하여 기업 수준의 운영 체계를 구축하는 방법을 다룹니다. Policy로 Tool 호출 권한을 제어하고, Evaluation으로 Agent 응답 품질을 평가하며, Observability로 전체 워크플로우를 추적합니다. 이 세 축이 결합되면 AI Agent 플랫폼의 보안, 품질, 가시성이 완성됩니다.

아키텍처 개요

AgentCore는 Agent의 기업 운영을 위해 세 가지 서비스를 제공합니다. 각각 요청의 다른 시점에서 동작합니다.

이 글에서는 각 서비스를 설명한 후, 마지막에 세 서비스를 결합하여 기업 운영 체계를 구성하는 방법을 종합합니다.

Policy: Cedar 기반의 결정적 접근 제어

AgentCore Policy란?

AI Agent는 사용자의 질문에 따라 어떤 Tool을 호출할지 자율적으로 판단합니다. 이 유연성은 강력하지만, Agent가 의도하지 않게 비즈니스 규칙을 위반하거나 권한 밖의 Tool을 호출할 수 있다는 보안 과제를 수반합니다.

AgentCore Policy는 이 문제를 코드 외부에서, 결정적으로 해결합니다. AWS의 오픈소스 정책 언어인 Cedar를 사용하여, Gateway를 통과하는 모든 Tool 호출을 자동으로 가로채고 평가합니다. Agent의 코드와 무관하게 일관된 정책이 적용되므로, Agent 구현이 어떻게 바뀌어도 보안 경계는 유지됩니다.

[그림 1. Policy Engine 생성 콘솔 화면 – Cedar 정책을 등록하고 Gateway에 연결하는 설정 화면]

Cedar 정책의 구조

Cedar 정책은 누가(Principal), 무엇을(Action), 어디에(Resource), 어떤 조건(Condition)에서 접근을 허용하거나 거부하는지를 선언적으로 정의합니다.

permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"DocumentTarget___search_documents",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/document-gateway"
)
when {
  principal.hasTag("employee_id")
};

이 정책은 “OAuth 토큰 클레임에 employee_id 태그가 있는 사용자만 DocumentTarget 이라는 타겟의 search_documents Tool을 호출할 수 있다”라는 규칙을 표현합니다. Cedar의 평가 모델은 forbid-overrides-permit 방식으로, 기본적으로 모든 요청을 거부(Default Deny)하고, 명시적인 permit 정책이 있어야만 허용합니다. forbid 정책은 항상 permit보다 우선합니다.

인가 흐름

AgentCore Gateway가 MCP Tool 호출 요청을 받으면, 다음 정보를 조합하여 Cedar 인가 요청을 구성합니다.

1단계: JWT 토큰에서 사용자 정보 추출

{
  "sub": "user-123",
  "custom:employee_id": "EMP-67890",
  "cognito:username": "honggildong",
  "department": "engineering"
}

2단계: MCP 요청에서 Tool 호출 정보 추출

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "DocumentTarget___search_documents",
    "arguments": { "query": "프로젝트 설계 문서" }
  }
}

3단계: Cedar 인가 요청 구성 및 평가

Policy Engine이 모든 정책을 평가하여 ALLOW 또는 DENY를 결정합니다. 이 평가는 Agent 코드 외부에서 이루어지므로, Agent가 우회할 수 없습니다.

기업 환경에서의 활용 패턴

Cedar 정책은 다양한 기업 보안 요건을 표현할 수 있습니다.

부서 기반 접근 제한

-- HR 부서만 인사 정보 조회 Tool 호출 가능
permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"DocumentTarget___get_employee_info",
  resource == AgentCore::Gateway::"arn:aws:..."
)
when {
  principal.hasTag("department") &&
  principal.getTag("department") == "hr"
};

역할 기반 접근 제어 (RBAC)

-- 매니저 이상만 기밀 문서 검색 가능
permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"DocumentTarget___search_confidential_documents",
  resource == AgentCore::Gateway::"arn:aws:..."
)
when {
  principal.hasTag("role") &&
  ["manager", "director"].contains(principal.getTag("role"))
};

긴급 차단 (Emergency Shutdown)

-- 보안 사고 대응: 문서 검색 Tool 긴급 비활성화
forbid(
  principal,
  action == AgentCore::Action::"DocumentTarget___search_documents",
  resource == AgentCore::Gateway::"arn:aws:..."
);

자연어 정책 작성

Cedar 문법에 익숙하지 않은 경우, 자연어로 정책을 작성하면 AgentCore가 이를 Cedar로 변환하고 검증합니다.

[그림 2. Policy Engine 생성 콘솔 화면 – 자연어로 Cedar 정책을 등록하는 설정 화면]

정책 적용 모드

정책을 실제 적용하기 전에 LOG_ONLY 모드로 테스트할 수 있습니다.

# Policy Engine을 Gateway에 연결
gateway_client.update_gateway_policy_engine(
    gateway_identifier=gateway_id,
    policy_engine_arn=policy_engine_arn,
    mode="LOG_ONLY"  # 먼저 로그 모드로 테스트
)

CloudWatch에서 정책 결정 로그를 분석하여 의도하지 않은 거부가 없는지 확인한 후, ENFORCE 모드로 전환합니다. 참고로, 적용 모드 설정은 현재 콘솔 UI에서는 제공되지 않으며 API(update_gateway_policy_engine)로만 변경할 수 있습니다.

Lambda Interceptor와의 역할 분담

Policy Engine은 JWT 토큰의 클레임을 기반으로 Tool 호출 권한을 제어합니다. 부서, 직급, 스코프 등 필요한 정보가 JWT 클레임에 포함되어 있다면, Cedar 정책만으로도 세밀한 접근 제어가 가능합니다. 예를 들어, principal.getTag("department") == "hr" 조건으로 HR 부서만 인사 정보 Tool을 호출하도록 제한할 수 있습니다.

그러나 실제 기업 환경에서는 Policy Engine만으로 해결할 수 없는 두 가지 상황이 있습니다.

• 첫째, 필요한 정보가 JWT 클레임에 없는 경우입니다.
  • JWT Access Token에는 client_id만 포함되어 있고, employee_id는 ID Token을 별도로 디코딩해야 얻을 수 있거나, 부서 정보는 외부 DB를 조회해야 하는 경우가 이에 해당합니다. Policy Engine은 JWT 클레임을 자동으로 태그에 매핑하지만, 토큰에 없는 정보를 외부에서 가져오는 것은 할 수 없습니다.
• 둘째, Tool 호출이 허용된 이후에도 사용자별로 다르게 처리해야 하는 경우입니다.
  • 예를 들어, 같은 search_documents Tool이라도 Tool 내의 로직에 따라 사용자의 부서별로 접근 가능한 문서 범위가 달라질 수 있습니다. Policy Engine은 Tool 호출 자체를 허용하거나 거부할 수 있지만, 허용된 요청의 내용을 변환하거나 사용자 정보를 주입하는 것은 할 수 없습니다.

이때 Lambda Interceptor를 사용할 수 있습니다. Interceptor는 AgentCore Gateway가 Tool 요청을 Target으로 전달하기 전에 실행되는 Lambda 함수로, 클라이언트 header를 읽고 JWT 디코딩이나 외부 시스템 조회를 통해 추가 정보를 확보한 후, 이를 요청의 header와 body에 주입합니다. 이렇게 주입된 정보를 통해 Target이 사용자별 처리를 수행할 수 있습니다.

정리하면, Policy Engine은 “이 요청을 허용할 것인가”를 선언적으로 판단하고, Interceptor는 “허용된 요청에 어떤 정보를 더해서 전달할 것인가”를 코드로 처리합니다. 둘은 보완적인 관계입니다.

이를 위해 Gateway는 클라이언트의 요청 header를 Target까지 전달하는 Header Propagation 기능을 제공합니다. 그러나 클라이언트의 원본 header에 필요한 정보가 모두 포함되어 있지 않을 수 있습니다. 예를 들어, JWT Access Token에는 client_id만 있고 employee_id는 ID Token을 별도로 디코딩해야 얻을 수 있거나, 부서 정보는 외부 DB를 조회해야 하는 경우입니다.

이때 Lambda Interceptor를 사용할 수 있습니다. Interceptor는 클라이언트 header를 읽고, JWT 디코딩이나 외부 시스템 조회를 통해 추가 정보를 확보한 후, 이를 요청의 header와 body에 주입하여 Target이 사용자별 처리를 수행할 수 있게 합니다. Policy Engine과 Interceptor는 모두 접근 제어가 가능하지만 접근 방식이 다르며, 둘은 보완적인 관계입니다.

예를 들어, “인증된 사용자만 search_documents Tool을 호출할 수 있다”라는 동일한 요건을 두 방식으로 구현할 수 있습니다. Policy Engine은 principal.hasTag("employee_id") 한 줄로 선언적으로 표현하고, Interceptor는 JWT를 디코딩하여 employee_id 존재 여부를 코드로 확인합니다. 단순한 Tool 단위 접근 제어는 Policy가 적합하고, Interceptor는 여기에 더해 외부 DB 조회로 부서 정보를 확보하거나, 사용자 정보를 요청에 주입하여 Target이 사용자별 처리를 수행하게 하는 등 유연한 처리가 가능합니다.

AgentCore Gateway의 header 처리 설정

다만, 클라이언트로부터 전달된 Header를 AgentCore Gateway에서 처리 및 전파하는 방법은 크게 두가지가 있습니다.

• Header Propagation(metadataConfigurationt 설정): 지정한 header를 Target까지 직접 전달합니다. Interceptor를 거치지 않는 단순 전달 방식입니다.
• Interceptor Lambda (passRequestHeaders 설정): 클라이언트의 원본 header를 Interceptor Lambda에 전달합니다. Interceptor가 이 header를 읽고 처리한 결과를 Target으로 보내는 구조입니다.

흐름은 다음과 같습니다.

[그림 3. Header propagation flow]

클라이언트 요청이 AgentCore Gateway에 도달하면,

1. 먼저 JWT 인증(Step 1)을 거쳐 클레임이 tags로 매핑되고,
2. Policy Engine(Step 2)이 이 tags와 원본 Tool 파라미터만을 기반으로 ALLOW/DENY를 결정합니다.
3. ALLOW된 요청은 Interceptor Lambda(Step 3)로 전달되어 header 가공, body 주입, JWT 디코딩 등의 처리를 거친 후,
4. Interceptor가 반환한 headers/body와 Target에 설정된 metadataConfiguration allowlist header가 합쳐져
5. 최종적으로 Target(API Gateway, Lambda, MCP Server 등)에 전달됩니다.

참고) Interceptor가 주입한 header명과 Client가 직접 전송한 header명이 충돌 시 Interceptor 에서 주입되는 값이 우선됩니다. 또한 Interceptor에서 주입된 커스텀 header는 Authorization header가 아닌 경우 metadataConfiguration의 allowlist에 명시되어 있어야 합니다.

먼저, 콘솔에서 Header Propagation을 설정하는 방법은 다음과 같습니다.

metadataConfiguration
아래와 같은 metadataConfiguration 설정 화면에서 Target 설정에서 전달할 header를 추가하여 allowlist로 지정합니다.

[그림 4. metadataconfiguration 설정 콘솔 화면]

혹은 코드를 통해 Gateway 생성/수정 시 아래와 같이 설정할 수 있습니다. (아래 예제는 생성 예제입니다.)

import boto3

# Initialize the client
client = boto3.client('bedrock-agentcore', region_name='us-west-2')

# Create target with header propagation
response = client.create_gateway_target(
    gatewayId='gateway-123',
    name='mcp-target-with-headers',
    description='MCP target with header propagation',
    targetConfiguration={
        'mcp': {
            'mcpServer': {
                'endpoint': 'https://example.com/mcp'
            }
        }
    },
    metadataConfiguration={
        'allowedRequestHeaders': ['x-correlation-id', 'x-tenant-id'],
        'allowedResponseHeaders': ['x-rate-limit-remaining'],
        'allowedQueryParameters': ['version']
    }
)

passRequestHeaders
AgentCore Gateway 의 설정에서, Request Interceptor Lambda ARN에서의 passRequestHeaders를 true로 설정합니다. 이때 Gateway 실행 역할에 Interceptor Lambda lambda:InvokeFunction 권한이 필요합니다.

[그림 5. request interceptor lambda 설정 콘솔 화면]

AgentCore Gateway의 단순 Header Propagation의 한계

그러나 metadataConfiguration으로 설정한 단순 header 전파가 아닌 Interceptor Lambda로 주입한 header는 AgentCore Runtime 타겟과 Lambda 타겟으로 전달되지 않는 한계가 있습니다. 자세히 살펴보면, header는 타겟 유형에 따라 전달 방식이 다릅니다. API Gateway 타겟은 HTTP header로 직접 전달되고, Lambda 타겟은 ClientContext를 통해 전달되며, Runtime 타겟은 2단계 프록시 구조로 인해 전달되지 않습니다.

Runtime 타겟에서 header가 전달되지 않는 이유는 2단계 프록시 구조 때문입니다. AgentCore Gateway → AgentCore Runtime Invocation API → 내부 프록시 → MCP Server 컨테이너 흐름에서, AgentCore 플랫폼이 새로운 HTTP 요청을 생성하여 컨테이너에 전달하므로 원래 header가 사라집니다.

이러한 한계를 극복하기 위해, Interceptor Lambda 응답의 transformedGatewayRequest에서 body를 주입할 수 있습니다. header와 달리 Body Injection(arguments 주입)은 모든 타겟 유형에서 일관되게 동작합니다.

코드를 통해 살펴보겠습니다. Interceptor Lambda가 Gateway로부터 받는 이벤트는 다음 구조를 가집니다. passRequestHeaders: true로 설정하면 클라이언트의 원본 header(Authorization, X-Id-Token 등)가 headers 필드에 포함됩니다.

{
  "mcp": {
    "gatewayRequest": {
      "headers": {
        "Authorization": "Bearer eyJraWQi...",
        "X-Id-Token": "eyJraWQi..."
      },
      "body": {
        "jsonrpc": "2.0",
        "method": "tools/call",
        "params": {
          "name": "HRTarget___get_employee_info",
          "arguments": { "query": "내 인사 정보" }
        }
      }
    }
  }
}

다음은 이 이벤트를 처리하는 Interceptor Lambda의 핵심 로직입니다. JWT 토큰에서 사용자 정보를 추출하고, 인증되지 않은 사용자의 Tool 호출을 차단하거나, 인증된 사용자의 정보를 header와 body에 주입합니다.

"""AgentCore Gateway Interceptor Lambda"""
import json, base64, logging

logger = logging.getLogger()
logger.setLevel(logging.INFO)

# 인증 필수 Tool 목록
AUTHENTICATED_ONLY_TOOLS = {'search_documents', 'get_employee_info'}

def decode_jwt_payload(token):
    try:
        parts = token.split('.')
        if len(parts) != 3: return None
        payload_b64 = parts[1]
        payload_b64 += '=' * (4 - len(payload_b64) % 4)
        return json.loads(base64.urlsafe_b64decode(payload_b64))
    except Exception as e:
        return {"decode_error": str(e)}

def extract_user_info(headers):
    auth = headers.get('authorization', headers.get('Authorization', ''))
    if auth.startswith('Bearer '):
        payload = decode_jwt_payload(auth[7:])
        if payload:
            return {
                "employee_id": payload.get('custom:employee_id', payload.get('sub', '')),
                "username": payload.get('cognito:username', payload.get('username', '')),
                "email": payload.get('email', ''),
                "sub": payload.get('sub', ''),
            }
    return None

def lambda_handler(event, context):
    mcp = event.get('mcp', {})
    gateway_request = mcp.get('gatewayRequest', {})
    headers = gateway_request.get('headers', {})
    body = gateway_request.get('body', {})

    if isinstance(body, str):
        try: body = json.loads(body)
        except: body = {}

    user_info = extract_user_info(headers)

    if body.get('method') == 'tools/call' and 'params' in body:
        # Tool 이름 추출 (prefix 제거)
        tool_name = body.get('params', {}).get('name', '')
        if '___' in tool_name:
            tool_name = tool_name.split('___', 1)[1]

        # 접근 제어: 인증되지 않은 사용자의 Tool 호출 차단
        if tool_name in AUTHENTICATED_ONLY_TOOLS and not user_info:
            raise Exception(f"Unauthorized: {tool_name} requires authentication")

        # 사용자 정보 주입
        args = body.get('params', {}).get('arguments', {})
        if user_info:
            args['_employee_id'] = user_info.get('employee_id', '')
            args['_username'] = user_info.get('username', '')
            args['_auth_method'] = 'cognito_jwt'
        body['params']['arguments'] = args

    return {
        "interceptorOutputVersion": "1.0",
        "mcp": {
            "transformedGatewayRequest": {
                "headers": {
                    "X-Employee-Id": user_info.get('employee_id', '') if user_info else '',
                    "X-Auth-Method": 'cognito_jwt' if user_info else 'none',
                },
                "body": body
            }
        }
    }

이 Interceptor는 두 가지 역할을 수행합니다. AUTHENTICATED_ONLY_TOOLS에 포함된 Tool에 대해 인증되지 않은 요청이 들어오면 예외를 발생시켜 호출을 차단하고, 인증된 요청에 대해서는 사용자 정보를 주입하여 Target으로 전달합니다. 앞서 본 Cedar 정책의 principal.hasTag("employee_id") 조건과 동일한 접근 제어를 코드로 구현한 것입니다.

인증된 사용자의 요청이 통과하면, Interceptor는 다음과 같은 응답을 반환합니다.

{
  "interceptorOutputVersion": "1.0",
  "mcp": {
    "transformedGatewayRequest": {
      "headers": {
        "X-Employee-Id": "EMP-67890",
        "X-Auth-Method": "cognito_jwt"
      },
      "body": {
        "jsonrpc": "2.0",
        "method": "tools/call",
        "params": {
          "name": "DocumentTarget___search_documents",
          "arguments": {
            "query": "프로젝트 설계 문서",
            "_employee_id": "EMP-67890",
            "_auth_method": "cognito_jwt",
            "_username": "honggildong"
          }
        }
      }
    }
  }
}

headers에 주입한 값은 API Gateway 타겟에서만 Target까지 전달되고, body에 주입한 값은 모든 타겟 유형에서 전달됩니다.

Evaluation: Agent 응답의 품질 평가

AgentCore Evaluation이란?

Policy가 “이 Tool을 호출해도 되는가”를 사전에 판단한다면, Evaluation은 “Agent가 Tool을 잘 사용했는가”를 사후에 평가합니다.
AgentCore Evaluation은 Agent의 세션, 트레이스, Tool 호출을 대상으로 자동화된 품질 평가를 수행합니다. Observability가 수집한 트레이스 데이터를 기반으로 동작하며, 빌트인 평가자, 커스텀 평가자, 온라인 연속 평가를 지원합니다.

평가 레벨과 빌트인 평가자

AgentCore는 13개의 빌트인 평가자를 제공하며, 평가 대상의 범위에 따라 세 가지 레벨로 구분됩니다.

이와 같은 빌트인 평가자들은 사례별로 아래와 같이 조합하여 평가할 수 있습니다.

• 고객 서비스 Agent: Helpfulness + GoalSuccessRate + Harmfulness
• RAG 기반 Agent: Correctness + Faithfulness + ContextRelevance
• Tool 중심 Agent: ToolSelectionAccuracy + ToolParameterCorrectness + Correctness

Tool 레벨 평가자는 누락된 Tool 호출을 감지할 수 없습니다. Builtin.ToolSelectionAccuracy는 Agent가 수행한 각 Tool 호출이 적절한지 판단하지만, Agent가 Tool을 아예 호출하지 않으면 평가할 Tool 호출이 0개이므로 통과 점수를 반환합니다. (GitHub)
이 한계를 보완하려면 Trace 레벨 커스텀 평가자를 만들어서 “Tool을 호출해야 할 상황에서 호출하지 않은 경우”를 감지해야 합니다.

온디맨드 평가

특정 세션에 대해 즉시 평가를 실행할 수 있습니다.

# 단일 평가자로 평가
agentcore eval run --evaluator "Builtin.Helpfulness"

# 복수 평가자 동시 평가
agentcore eval run \
  --evaluator "Builtin.Helpfulness" \
  --evaluator "Builtin.GoalSuccessRate" \
  --evaluator "Builtin.Correctness"

평가 결과는 점수(0~1), 라벨, 설명을 포함합니다.

Evaluator: Builtin.Helpfulness
Score: 0.83
Label: Very Helpful
Explanation: The assistant's response effectively addresses the user's request
             by providing comprehensive analysis...

온라인 연속 평가 (Continuous Monitoring)

프로덕션 환경에서는 모든 Agent 세션을 자동으로 샘플링하여 지속적으로 평가하는 온라인 평가를 설정할 수 있습니다.

agentcore eval online create \
  --name production_eval_config \
  --sampling-rate 5.0 \
  --evaluator "Builtin.GoalSuccessRate" \
  --evaluator "Builtin.Helpfulness" \
  --description "프로덕션 Agent 품질 모니터링"

온라인 평가 결과는 CloudWatch의 GenAI Observability → Bedrock AgentCore → Evaluations 탭에서 확인할 수 있으며, 시간에 따른 품질 추이를 모니터링할 수 있습니다.

커스텀 평가자: LLM-as-a-Judge

빌트인 평가자로 충분하지 않은 경우, 도메인 특화 커스텀 평가자를 만들 수 있습니다. LLM을 평가자(Judge)로 활용하여, 기업 고유의 품질 기준을 적용합니다.

{
  "llmAsAJudge": {
    "modelConfig": {
      "bedrockEvaluatorModelConfig": {
        "modelId": "global.anthropic.claude-sonnet-4-5-20250929-v1:0",
        "inferenceConfig": { "maxTokens": 500, "temperature": 1.0 }
      }
    },
    "ratingScale": {
      "numerical": [
        { "value": 0.0, "label": "부적절", "definition": "보안 정책을 위반하거나 부정확한 정보 제공" },
        { "value": 0.5, "label": "보통", "definition": "기본적인 답변이나 개선 여지 있음" },
        { "value": 1.0, "label": "우수", "definition": "정확하고 정책을 준수하는 완전한 답변" }
      ]
    },
    "instructions": "이 Agent 응답이 기업 보안 정책을 준수하는지, 민감 정보를 적절히 처리했는지 평가하세요. Context: {context}. Target: {assistant_turn}"
  }
}

agentcore eval evaluator create \
  --name "security_compliance_evaluator" \
  --config evaluator-config.json \
  --level TRACE \
  --description "기업 보안 정책 준수 여부 평가"

Evaluation과 Policy의 상호보완

두 서비스의 역할은 명확히 구분됩니다.

예를 들어, Policy가 “환불 500달러 미만”이라는 규칙을 적용하더라도, 499달러 환불을 반복 처리하는 패턴은 Policy로는 잡을 수 없습니다. Evaluation의 연속 모니터링이 이러한 이상 패턴을 탐지하고, Policy 규칙을 정교화하는 피드백 루프를 형성합니다.

Observability: Agent 워크플로우의 실시간 추적

AgentCore Observability란?

AI Agent의 동작은 본질적으로 비결정적입니다. 같은 질문에 대해서도 LLM의 판단에 따라 서로 다른 Tool을 호출하고, 다른 순서로 실행할 수 있습니다. 이러한 환경에서 “무슨 일이 일어나고 있는지”를 파악하는 것은 디버깅, 성능 최적화, 감사(audit) 모두에 필수적입니다.

AgentCore Observability는 OpenTelemetry 표준 기반의 분산 추적, 메트릭 수집, 로그 관리를 제공합니다. AgentCore Runtime에 호스팅된 Agent뿐 아니라, EC2나 ECS 등 자체 인프라에서 실행되는 Agent도 동일한 방식으로 모니터링할 수 있습니다.

제공 기능

Runtime 호스팅 Agent의 Observability 설정

AgentCore Runtime에 배포된 Agent는 자동 계측이 적용됩니다. aws-opentelemetry-distro를 의존성에 추가하고, ENTRYPOINT를 opentelemetry-instrument로 감싸면 됩니다.

의존성 (pyproject.toml):

dependencies = [
    "aws-opentelemetry-distro>=0.10.1",
    # ... 기타 의존성
]

Dockerfile:

ENV AGENT_OBSERVABILITY_ENABLED=true \
    OTEL_PYTHON_DISTRO=aws_distro \
    OTEL_PYTHON_CONFIGURATOR=aws_configurator \
    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    OTEL_TRACES_EXPORTER=otlp

ENTRYPOINT ["opentelemetry-instrument", "python", "-m", "my_agent"]

이것만으로 HTTP 요청, LLM 호출, Tool 실행, 데이터베이스 접근 등이 자동으로 트레이싱됩니다.

비 Runtime 호스팅 Agent의 Observability 설정

자체 인프라(EC2, ECS, Lambda 등)에서 Agent를 실행하는 경우에도 동일한 Observability를 적용할 수 있습니다. 추가로 로그 그룹과 메트릭 네임스페이스를 환경변수로 지정합니다.

export AGENT_OBSERVABILITY_ENABLED=true
export OTEL_PYTHON_DISTRO=aws_distro
export OTEL_PYTHON_CONFIGURATOR=aws_configurator
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=/my/agent/logs,x-aws-log-stream=main,x-aws-metric-namespace=MyAgentMetrics
export OTEL_RESOURCE_ATTRIBUTES=service.name=my-agent

# 자동 계측으로 Agent 실행
opentelemetry-instrument python agent.py

CloudWatch GenAI Observability 대시보드

수집된 트레이스와 메트릭은 CloudWatch GenAI Observability 대시보드에서 통합 조회됩니다.

특히 Traces View에서는 하나의 사용자 요청이 어떤 경로로 처리되었는지 — LLM이 어떤 Tool을 선택했고, 각 Tool 호출에 얼마나 걸렸으며, 어디서 오류가 발생했는지를 시각적으로 확인할 수 있습니다.

[그림 6. AgentCore Observability log tracing 화면]

CloudWatch Transaction Search 활성화

트레이스 데이터를 CloudWatch에서 조회하려면 Transaction Search를 최초 1회 활성화해야 합니다.

CLI 방식:

# 로그 리소스 정책 생성
aws logs put-resource-policy --policy-name MyResourcePolicy --policy-document '{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "TransactionSearchXRayAccess",
    "Effect": "Allow",
    "Principal": { "Service": "xray.amazonaws.com" },
    "Action": "logs:PutLogEvents",
    "Resource": [
      "arn:aws:logs:{region}:{account-id}:log-group:aws/spans:*",
      "arn:aws:logs:{region}:{account-id}:log-group:/aws/application-signals/data:*"
    ]
  }]
}'

# 트레이스 목적지를 CloudWatch Logs로 설정
aws xray update-trace-segment-destination --destination CloudWatchLogs

콘솔 방식:

1. CloudWatch → Settings → X-Ray traces → Transaction Search → Edit
2. “Enable Transaction Search” 선택
3. 저장 (활성화까지 약 10분 소요)

로그 확인 위치

Evaluation과의 연계

Observability가 수집한 트레이스 데이터는 Evaluation의 입력 데이터로 직접 사용됩니다. Evaluation은 Observability 없이는 동작할 수 없습니다.

Observability (트레이스 수집) → Evaluation (품질 평가) → CloudWatch (결과 대시보드)

agentcore eval run 명령은 내부적으로 해당 세션의 트레이스 스팬을 조회하여 평가 대상을 구성합니다. 따라서 Evaluation을 사용하려면 먼저 Observability가 활성화되어 있어야 하며, 세션 데이터가 CloudWatch에 적재된 이후(약 2~5분 지연) 평가가 가능합니다.

세 서비스의 결합: 기업 운영 체계 완성

전체 흐름

세 서비스가 결합된 기업 환경의 End-to-End 흐름입니다.

[그림 7. AgentCore end-to-end flow]

마치며

AgentCore의 Policy, Evaluation, Observability를 활용하여 기업 운영 체계를 구축하면서 얻은 핵심 인사이트를 정리합니다.

1. Policy, Evaluation, Observability는 결합할 때 시너지가 극대화됩니다.
   Policy는 사전 제어, Observability는 실시간 추적, Evaluation은 사후 평가를 각각 담당합니다. Observability가 수집한 트레이스가 Evaluation의 입력이 되고, Evaluation의 결과가 Policy 정책 개선의 근거가 되는 피드백 루프가 형성됩니다.
2. Policy Engine과 Lambda Interceptor는 보완적으로 접근 제어를 수행합니다.
   Policy Engine은 Cedar 선언문으로 정책을 관리하여, Agent 코드와 분리된 보안 경계를 제공합니다. 정책 결정 로그가 자동 기록되어 감사에 유리하며, LOG_ONLY 모드로 안전하게 테스트한 후 ENFORCE로 전환할 수 있습니다. Lambda Interceptor는 코드 기반으로 접근 제어와 요청 변환을 모두 처리할 수 있어, 외부 시스템 연동이나 사용자 정보 주입 같은 유연한 처리가 가능합니다.
3. Lambda 타겟은 경량 Tool 구현에 유리합니다.
   Lambda 타겟은 MCP SDK 없이 단순한 JSON 입출력만으로 Tool을 구현할 수 있으며, GATEWAY_IAM_ROLE 인증으로 OAuth 설정 없이 Gateway와 연동됩니다. Interceptor가 주입한 사용자 정보(_employee_id)를 활용하면 Target 레벨에서도 사용자별 데이터 접근 제어가 가능합니다.
4. Evaluation의 온라인 연속 평가는 “Agent 품질 드리프트”를 탐지합니다.
   LLM 기반 Agent는 모델 업데이트, 프롬프트 변경, 새로운 Tool 추가 등에 의해 시간이 지남에 따라 품질이 변할 수 있습니다. 프로덕션 트래픽의 일부를 지속적으로 샘플링하여 평가하면, 이러한 품질 변화를 조기에 감지하고 대응할 수 있습니다.

이 글은 시리즈의 마지막, 3편입니다. Part 1에서는 AI-DLC 방법론을, Part 2에서는 MCP Registry 구현을 다루었습니다.

주요 링크 모음

• Amazon Bedrock AgentCore 공식 문서
• AgentCore Policy 개요
• Cedar 정책 언어
• AgentCore Policy Integration 예시
• Amazon Bedrock AgentCore Observability로 프로덕션 수준의 AI 에이전트 구축하기
• Apply fine-grained access control with Bedrock AgentCore Gateway interceptors
• AgentCore Gateway Header Propagation 샘플 코드
• Part 1: AI-DLC 방법론과 유용한 도구들
• Part 2: AgentCore로 MCP Registry 구현하기