View a markdown version of this page

원격 측정 설정 및 전송 - Amazon Bedrock AgentCore
관찰성 설정원격 측정 전송 모드서비스가 스팬에서 읽는 내용참조샘플 에이전트

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

원격 측정 설정 및 전송

에이전트는 Amazon Bedrock AgentCore Evaluations가 각 세션을 재구성하는 데 사용하는 범위를 내보냅니다. AgentCore가 세션, 트레이스 및 범위를 나타내는 방법은 AgentCore의 에이전트 리소스에 대한 관찰성 이해를 참조하세요.

세션을 채점하려면 모델에 프롬프트, 모델 완료, 도구 입력 및 출력과 같은 대화 콘텐츠가 서비스에 필요합니다. 콘텐츠의 위치는 에이전트가 원격 측정을 제공하는 방식에 따라 달라지며,이 페이지에서 설명합니다.

주제

관찰성 설정

에이전트 계측은 평가 서비스가 읽을 수 있는 원격 측정 생성의 한 부분입니다. 에이전트는 원격 측정을 Amazon CloudWatch로 내보낼 수 있도록 관찰성도 활성화되어 있어야 합니다. 다음 단계를 완료합니다.

  1. Amazon CloudWatch 트랜잭션 검색을 활성화합니다. 평가에는 두 전송 모드 모두에서 필요합니다. AgentCore 관찰성 활성화를 참조하세요.

  2. 에이전트를 호스팅하는 위치에 따라 에이전트에 대한 관찰성을 활성화합니다.

  3. 원격 측정의 위치를 알 수 있도록 에이전트가 사용하는 전송 모드를 확인합니다. 2026년 7월 20일 이후에 생성한 에이전트는 기본적으로 통합 원격 측정을 사용하고, 해당 날짜 이전에 생성한 에이전트는 분할 원격 측정을 사용합니다. 통합 원격 측정에는 ADOT 버전 0.18.0 이상(aws-opentelemetry-distro>=0.18.0)이 필요합니다. 이전 버전은 공유 aws/spans 로그 그룹에 범위를 전송합니다.

    AgentCore 런타임의 에이전트의 경우 UNIFIED_TRACES_DESTINATION_ENABLED 환경 변수를 사용하여 모드를 전환합니다. true 통합 원격 측정의 경우 로, 분할 원격 측정false의 경우 로 설정합니다. 환경 변수, IAM 권한 및 각 호스팅 옵션의 전체 절차는 Amazon Bedrock AgentCore 런타임에서 호스팅되는 에이전트의 범위 대상을 참조하세요.

전송 모드를 변경해도 AgentCore가 이미 전송한 원격 측정은 이동하지 않습니다. 이전 스팬은 작성된 로그 그룹에 유지되므로 서비스는 변경 전에 기록한 세션을 계속 평가합니다.

원격 측정 전송 모드

AgentCore는 다음 두 가지 모드 중 하나로 에이전트의 원격 측정을 제공합니다.

  • 통합 원격 측정(권장)은 모든 것을 하나로 묶습니다. 모델 페이로드와 도구 요청 및 응답을 전달하는 속성은 범위 내에 유지되며 에이전트의 모든 원격 측정은 하나의 로그 그룹으로 이동합니다.

  • 분할 원격 측정은 두 가지를 구분합니다. AWS Distro for OpenTelemetry(ADOT)는 해당 속성을 스팬에서 별도의 레코드로 이동하며,이 레코드는 스팬과 다른 로그 그룹으로 이동합니다.

AgentCore Evaluations는 두 모드를 모두 읽습니다. 평가 서비스에서 둘 중 하나를 선택하지 않으며 동일한 평가자가 어느 쪽이든 동일한 결과를 제공합니다. AgentCore 런타임을 사용할 수 있는 모든 AWS 상용 리전에서 사용할 수 있는 통합 원격 측정을 권장합니다.

통합 원격 측정(권장)

통합 원격 측정을 사용하면 에이전트의 모든 원격 측정이 하나의 로그 그룹으로 이동합니다. 스팬은 에이전트의 자체 spans 로그 및 콘솔 출력 옆에 있는 해당 로그 그룹의 로그 스트림으로 이동합니다. 스팬은 모델 페이로드와 도구 요청 및 응답을 전달하는 속성을 유지하므로 서비스는 스팬 자체에서 필요한 모든 것을 읽습니다.

통합 원격 측정: ADOT는 콘텐츠와 함께 각 스팬을 하나의 로그 그룹으로 전송합니다.

스팬을 보유하는 로그 그룹은 에이전트를 호스팅하는 위치에 따라 다릅니다.

  • Amazon Bedrock AgentCore 런타임: 에이전트의 로그 그룹 /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>. AgentCore는 이를 자동으로 설정합니다.

  • AgentCore 런타임 외부에서 호스팅: OTEL_EXPORTER_OTLP_TRACES_HEADERS 환경 변수에서 이름을 지정하는 로그 그룹입니다.

스팬과 로그를 한 곳에 보관하면 평가 이상의 도움이 됩니다. 추적과 로그를 함께 보고, AWS Identity and Access Management(IAM) 정책을 작성하고, 단일 에이전트에 대한 고객 관리형 키 암호화를 설정하고, 하나의 로그 그룹을 구독하여 에이전트가 생성하는 모든 것을 내보낼 수 있습니다.

원격 측정 분할

분할 원격 측정을 사용하면 ADOT는 스팬에서 큰 페이로드를 제거합니다. 각 스팬을 내보낼 때 모델 페이로드와 도구 요청 및 응답을 전달하는 속성을 가져와 별도의 이벤트 레코드로 전송하여 스팬에 메타데이터와 더 작은 속성을 남깁니다. 이벤트 레코드는이 모드에서만 존재하며 OpenTelemetry 이벤트 규칙을 따릅니다.

각 이벤트 레코드는 공유 traceId 및를 통해 해당 범위에 다시 연결되며spanId, 콘텐츠는 body.input.messages 및와 body같은 레코드에 있습니다body.output.messages.

분할 원격 측정: ADOT가 aws/spans로 스팬을 보내고 에이전트 로그 그룹에 이벤트 레코드로 대화 콘텐츠를 보냅니다.

그러면 두 종류의 레코드가 서로 다른 위치로 이동합니다.

  • 스팬은 공유 aws/spans 로그 그룹으로 이동합니다. 트랜잭션 검색을 켜면 CloudWatch가이 로그 그룹을 생성합니다.

  • 이벤트 레코드는 별도의 로그 그룹으로 이동합니다. AgentCore 런타임에서 AgentCore가 설정한 로그 스트림에 있는 에이전트의 otel-rt-logs 로그 그룹입니다. AgentCore 런타임 외부에서는 OTEL_EXPORTER_OTLP_LOGS_HEADERS 환경 변수에서 이름을 지정하는 로그 그룹입니다.

세션을 평가하기 위해 서비스는에서 범위를 읽고 이를 이벤트 레코드aws/spans와 일치시킵니다.

서비스가 스팬에서 읽는 내용

세션의 각 스팬에 대해 서비스는 다음을 수행합니다.

  1. 프레임워크 세트의 속성에 따라 범위 유형을 결정합니다. 스팬은 호출 에이전트 스팬(상위 수준 에이전트 실행), 실행 도구 스팬(단일 도구 호출) 또는 추론 스팬(단일 모델 호출)일 수 있습니다.

  2. 사용자 프롬프트, 에이전트 응답, 도구 입력 및 출력 등 필요한 값을 읽습니다. 예를 들어 사용자 프롬프트는 에이전트 입력의 사용자 역할 메시지에서 가져오고 에이전트 응답은 에이전트 출력의 어시스턴트 역할 메시지에서 가져옵니다.

스팬을 식별하는 속성은 두 전송 모드 모두에서 항상 스팬에 유지됩니다. 대화 콘텐츠만 이동합니다. 해당 콘텐츠가 스팬 내에 있는 경우 계측 라이브러리에 따라 달라집니다. 대부분의 라이브러리는 이를 스팬 속성으로 기록하고 일부는 이를 스팬에 이벤트로 연결합니다. 각 라이브러리에 대해 프레임별 페이지에는 콘텐츠가 있는 위치와 같은 식별 속성이 나열되고 두 모드 모두에 대한 예제 범위가 표시됩니다.

참조

AgentCore 평가는 다음 OpenTelemetry 사양을 기반으로 합니다.

샘플 에이전트

다음 예제에서는 Amazon Bedrock AgentCore 런타임 외부에서 호스팅되는 Strands 에이전트를 계측하는 방법을 보여줍니다. 각 예제에서는 ADOT를 사용하여 원격 측정을 Amazon CloudWatch로 내보냅니다. 평가 API가 아닌 관찰성 설정에 중점을 둡니다. 이 예제에서는 Strands를 사용하지만 LangGraph와 같이 지원되는 다른 프레임워크에는 동일한 호스팅 및 원격 측정 내보내기 패턴이 적용됩니다.