View a markdown version of this page

구성 번들 전파 및 관찰성 - Amazon Bedrock AgentCore
구성 번들이 전파되는 방법MCP 대상에 대한 동작제약 조건규칙 확인에 대한 관찰성

구성 번들 전파 및 관찰성

게이트웨이는 규칙을 통해 구성 번들을 확인하면 OpenTelemetry(OTel) 헤더를 통해 번들을 다운스트림 서비스로 전파합니다. 이를 통해 게이트웨이 및 에이전트 아키텍처 전반에서 end-to-end 구성 관리가 가능합니다.

구성 번들이 전파되는 방법

게이트웨이는 다음 키를 사용하여 해결된 번들 ARN 및 버전을 OTel 도우미로 설정합니다.

상품 키 설명

aws.agentcore.configbundle_arn

확인된 구성 번들의 ARN입니다.

aws.agentcore.configbundle_version

확인된 구성 번들의 버전입니다.

전파 흐름은 다음과 같이 작동합니다.

  1. 게이트웨이는 규칙을 평가하고 구성 번들을 확인합니다.

  2. 게이트웨이는 발신 요청의 OTel 수수료 헤더에 번들 ARN 및 버전을 설정합니다.

  3. 에이전트 런타임은 헤더가 있는 요청을 수신합니다. 런타임은 사용자가 제어합니다. 에이전트 코드는 필요한 경우 OTel 비용으로 구성 번들 ARN 및 버전을 읽을 수 있습니다.

  4. 에이전트가 MCP 대상으로 게이트웨이를 호출하는 경우 게이트웨이는 OTel 범위에서 번들을 읽고 tools/list 응답에 도구 설명 재정의를 적용합니다. 자세한 내용은 MCP 대상에 대한 동작을 참조하세요.

MCP 대상에 대한 동작

게이트웨이는 tools/list 경로에 대해서만 MCP 대상에 구성 번들 재정의를 적용합니다. invoke_tool 및 search_tool 경로는 구성 번들 재정의를 지원하지 않습니다.

예를 들어 구성 번들이 대상의 도구 설명을 재정의하는 경우 업데이트된 설명은 tools/list 응답에는 표시되지만 search_tool 응답에는 표시되지 않습니다.

이러한 재정의를 적용하기 위해 게이트웨이는를 호출GetConfigurationBundleVersion하여 번들 콘텐츠를 읽습니다. 게이트웨이의 실행 역할에이 권한을 추가합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "bedrock-agentcore:GetConfigurationBundleVersion",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/*"
        }
    ]
}
참고

이 권한은 MCP tools/list 작업을 위한 게이트웨이 실행 역할에만 필요합니다. 에이전트 런타임은 번들에 액세스하지 않고 번들을 전달하며이 권한이 필요하지 않습니다.

제약 조건

  • 구성 번들은 게이트웨이와 동일한 계정에 있어야 합니다. 교차 계정 번들 액세스는 지원되지 않습니다.

  • HTTP 대상이 있는 게이트웨이는 OTel 도우미에서 구성 번들을 읽지 않습니다. 자체 규칙을 통해서만 번들을 확인합니다. HTTP 대상이 있는 게이트웨이에 OTel의 번들을 전달하면 게이트웨이는 해당 번들을 무시합니다.

  • MCP가 있는 게이트웨이는 OTel 비용으로 구성 번들을 읽고 tools/list 경로에만 재정의를 적용합니다.

규칙 확인에 대한 관찰성

게이트웨이는 요청에 대한 규칙을 확인하면 게이트웨이 서버 스팬에서 스팬 속성을 내보냅니다. 이러한 속성을 사용하여 적용된 구성 번들 버전 및 라우팅 결정을 관찰할 수 있습니다.

구성 번들 재정의 속성

Span 속성 설명

aws.agentcore.configbundle_arn

확인된 구성 번들의 ARN입니다.

aws.agentcore.configbundle_version

확인된 구성 번들의 버전입니다.

대상 라우팅 속성

Span 속성 설명

aws.agentcore.gateway.resolved_target_name

확인된 대상의 이름입니다.

이러한 속성을 사용하여 규칙이 예상대로 해결되는지 확인하고 라우팅 동작 문제를 해결합니다.