View a markdown version of this page

Propagação e observabilidade do pacote de configuração - Amazon Bedrock AgentCore
Como os pacotes de configuração se propagamComportamento em alvos de MCPRestriçõesObservabilidade para resolução de regras

Propagação e observabilidade do pacote de configuração

Quando o gateway resolve um pacote de configuração por meio de regras, ele propaga o pacote para serviços downstream por meio de cabeçalhos de bagagem OpenTelemetry (OTel). Isso permite o gerenciamento de configuração de ponta a ponta em toda a arquitetura de gateway e agente.

Como os pacotes de configuração se propagam

O gateway define o ARN e a versão do pacote resolvido na bagagem do OTel usando as seguintes chaves:

Chave de bagagem Description

aws.agentcore.configbundle_arn

O ARN do pacote de configuração resolvido.

aws.agentcore.configbundle_version

A versão do pacote de configuração resolvido.

O fluxo de propagação funciona da seguinte forma:

  1. O gateway avalia as regras e resolve um pacote de configuração.

  2. O gateway define o ARN e a versão do pacote nos cabeçalhos de bagagem OTel na solicitação de saída.

  3. O tempo de execução do agente recebe a solicitação com os cabeçalhos de bagagem. O tempo de execução é controlado por você. Seu código de agente pode ler o ARN e a versão do pacote de configuração da bagagem do OTel, se necessário.

  4. Se o agente invocar um gateway com alvos MCP, o gateway lê o pacote da bagagem do OTel e aplica as substituições da descrição da ferramenta nas respostas. tools/list Para obter detalhes, consulte Comportamento em alvos de MCP.

Comportamento em alvos de MCP

O gateway aplica substituições de pacotes de configuração em destinos MCP somente para o caminho. tools/list Os search_tool caminhos invoke_tool e não oferecem suporte a substituições de pacotes de configuração.

Por exemplo, se um pacote de configuração substituir a descrição da ferramenta de um alvo, a descrição atualizada aparecerá nas tools/list respostas, mas não nas respostas. search_tool

Para aplicar essas substituições, o gateway chama GetConfigurationBundleVersion para ler o conteúdo do pacote. Adicione essa permissão à função de execução do gateway:

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

Essa permissão só é necessária na função de execução do gateway para tools/list operações MCP. O tempo de execução do agente passa pelo pacote sem acessá-lo e não precisa dessa permissão.

Restrições

  • O pacote de configuração deve estar na mesma conta do gateway. Cross-account o acesso ao pacote não é suportado.

  • Os gateways com destinos HTTP não leem pacotes de configuração da bagagem do OTel. Eles resolvem pacotes somente por meio de suas próprias regras. Se você passar um pacote na bagagem OTel para um gateway com destinos HTTP, o gateway o ignorará.

  • Os gateways com alvos MCP leem os pacotes de configuração da bagagem OTel e aplicam substituições somente no caminho. tools/list

Observabilidade para resolução de regras

Quando o gateway resolve regras para uma solicitação, ele emite atributos de intervalo no intervalo do servidor gateway. Você pode usar esses atributos para observar qual versão do pacote de configuração e decisões de roteamento foram aplicadas.

Atributos de substituição do pacote de configuração

Atributo Span Description

aws.agentcore.configbundle_arn

O ARN do pacote de configuração resolvido.

aws.agentcore.configbundle_version

A versão do pacote de configuração resolvido.

Atributos de roteamento de destino

Atributo Span Description

aws.agentcore.gateway.resolved_target_name

O nome do alvo resolvido.

Use esses atributos para verificar se as regras são resolvidas conforme o esperado e para solucionar problemas de comportamento de roteamento.