View a markdown version of this page

Fixação da sessão para regras ponderadas - Amazon Bedrock AgentCore
Como funciona a aderência da sessãoConfigurar a aderência da sessão para destinos de passagemComportamentos importantes

Fixação da sessão para regras ponderadas

Ao usar regras ponderadas para A/B testes ou implantações canárias, você quer que cada sessão receba uma experiência consistente em várias solicitações. Sem a aderência da sessão, uma sessão pode receber pacotes de configuração diferentes ou ser roteada para destinos diferentes em cada solicitação. O roteamento para um destino diferente significa um novo tempo de execução do agente sem o contexto de solicitações anteriores, o que prejudica a experiência do usuário.

Para resolver isso, o gateway suporta a aderência da sessão. Quando você inclui uma ID de sessão em suas solicitações, o gateway armazena a decisão de roteamento da primeira solicitação e a reutiliza para todas as solicitações subsequentes na mesma sessão.

Como funciona a aderência da sessão

O gateway identifica uma sessão extraindo uma ID de sessão de cada solicitação. O fluxo de aderência funciona da seguinte forma:

  1. Na primeira solicitação com um ID de sessão, o gateway seleciona uma variante com base nos pesos configurados e armazena a decisão.

  2. Solicitações subsequentes com o mesmo ID de sessão reutilizam a decisão armazenada sem reavaliar os pesos.

  3. As solicitações sem um ID de sessão são avaliadas de forma independente, sem fidelidade.

A forma como o gateway determina o ID da sessão depende do tipo de destino:

  • AgentCore Destinos de tempo de execução — O gateway usa o X-Amzn-Bedrock-AgentCore-Runtime-Session-Id cabeçalho. O valor do cabeçalho deve ter no mínimo 33 caracteres. Você não precisa enviar esse cabeçalho na primeira solicitação. Se o cabeçalho estiver ausente, o tempo de execução do agente gera automaticamente uma ID de sessão e o gateway usa essa ID de sessão gerada automaticamente para garantir a adesão às solicitações subsequentes, caso você a inclua.

  • Destinos de passagem HTTP — Por padrão, o gateway usa o X-Amzn-Bedrock-AgentCore-Runtime-Session-Id cabeçalho. Você também pode configurar um identificador de sessão personalizado e um tempo limite no destino, para que os clientes de passagem que usam seu próprio cabeçalho de sessão não precisem adotar o cabeçalho da sessão em tempo de execução. Para obter mais informações, consulte Configurar a aderência da sessão para destinos de passagem.

Configurar a aderência da sessão para destinos de passagem

Para destinos de passagem HTTP, você pode definir um opcional stickinessConfiguration na configuração de destino para controlar como o gateway identifica as sessões e quanto tempo dura a afinidade da sessão. Isso é útil quando seus clientes já enviam seu próprio cabeçalho de sessão e você não quer exigir que eles também enviem o cabeçalho de sessão de tempo de execução padrão.

O stickinessConfiguration objeto contém:

  • identificador (obrigatório) — Uma expressão que informa ao gateway onde encontrar o ID da sessão na solicitação. Atualmente, o gateway pode resolver o ID da sessão somente a partir de um cabeçalho de solicitação. Você pode especificar o cabeçalho em qualquer um dos seguintes formulários:

    • Um nome de cabeçalho HTTP simples, comox-session-id. O gateway lê o ID da sessão desse cabeçalho da solicitação.

    • Uma expressão de caminho de contexto do formulário$.AMZN_AC_GW_CONTEXT.headers.{header-name}, como$.AMZN_AC_GW_CONTEXT.headers.x-session-id.

      Somente a headers fonte é suportada atualmente. Outras fontes (por exemplo, uma declaração do JWT) não estão disponíveis no momento.

  • timeout (opcional) — O tempo limite de afinidade da sessão, em segundos, de 1 a 86400 (24 horas). Após esse período de inatividade, a afinidade da sessão expira. A janela é reiniciada em cada solicitação (janela deslizante).

Quando um destino tem umstickinessConfiguration, o gateway resolve o ID da sessão do configuradoidentifier.

O exemplo a seguir cria um destino de passagem com um stickinessConfiguration que extrai o ID da sessão de um x-session-id cabeçalho personalizado e expira a afinidade da sessão após 8 horas (28800 segundos):

aws bedrock-agentcore-control create-gateway-target --cli-input-json '{
    "gatewayIdentifier": "GATEWAY_ID",
    "name": "my-passthrough-target",
    "targetConfiguration": {
        "http": {
            "passthrough": {
                "endpoint": "https://my-service.example.com",
                "protocolType": "CUSTOM",
                "stickinessConfiguration": {
                    "identifier": "$.AMZN_AC_GW_CONTEXT.headers.x-session-id",
                    "timeout": 28800
                }
            }
        }
    },
    "credentialProviderConfigurations": [
        {"credentialProviderType": "GATEWAY_IAM_ROLE"}
    ]
}'

Para obter mais informações sobre destinos de passagem, consulte Destinos de passagem HTTP.

Comportamentos importantes

As decisões armazenadas têm precedência sobre as mudanças nas regras. Se você atualizar uma regra, as sessões existentes continuarão com a decisão original. Isso garante a consistência da sessão. Para aplicar novas regras a uma sessão, inicie uma nova sessão com uma nova ID de sessão.

As sessões expiram após um período de inatividade. A janela de expiração é redefinida em cada solicitação (janela deslizante). Para metas AgentCore de tempo de execução, as sessões expiram após 15 dias de inatividade. Para destinos de passagem HTTP, a janela de expiração é a timeout que você definiu na meta stickinessConfiguration (1 a 86400 segundos); se você não definir um tempo limite, o padrão será aplicado. Depois que uma sessão expirar, use uma nova ID de sessão para novas sessões para evitar um comportamento inesperado de roteamento. Recomendamos que você não reutilize IDs de sessão expirados.

O estado da sessão é definido por alvo. Alvos diferentes mantêm um estado de sessão independente.

Compatível com destinos de passagem de tempo de AgentCore execução e HTTP. A aderência da sessão não é suportada para alvos de MCP.