As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Sessões de políticas e propagação de identidade

Com políticas temporais, você pode definir regras com base em eventos passados que ocorreram em uma sessão, não apenas na solicitação atual. Você pode impor restrições como:

Uma sessão de política agrupa várias invocações do Gateway em uma única sessão lógica. A sessão é o limite sobre o qual as regras de política temporal são avaliadas.

Como funciona

Passando o ID da sessão de política

Inclua o x-amzn-bedrock-agentcore-policy-session-id cabeçalho em suas solicitações para o Gateway. Você deve gerar o ID da sessão e enviá-lo em cada solicitação, começando com sua primeira solicitação. O Gateway não gera um ID de sessão em seu nome. O valor é uma string que identifica a sessão e recomendamos um UUIDv4. Envie o mesmo ID com todas as solicitações na mesma sessão.

Se você omitir o cabeçalho ou enviar um valor vazio, o Gateway não estabelecerá uma sessão. Se o mecanismo de política associado contiver uma política temporal, as solicitações sem um ID de sessão falharão com um erro de validação.

Para saber o formato aceito e como o Gateway o valida, consulte Verificação de cabeçalho e implantações sem tempo de execução.

Primeira solicitação (cria a sessão):

curl -X POST \
  https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-amzn-bedrock-agentcore-policy-session-id: 12345678-1234-1234-1234-123456789012" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "PaymentTool___transfer_funds",
      "arguments": {
        "amount": 500,
        "recipient": "account-789"
      }
    }
  }'

Solicitações subsequentes (continue a sessão):

curl -X POST \
  https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-amzn-bedrock-agentcore-policy-session-id: 12345678-1234-1234-1234-123456789012" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "PaymentTool___transfer_funds",
      "arguments": {
        "amount": 600,
        "recipient": "account-456"
      }
    }
  }'

Se sua política temporal limitar cada sessão a 1 transferência, a segunda solicitação mostrada no exemplo anterior seria negada.

Exemplo do Python:

import requests
import uuid

GATEWAY_URL = "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

# Generate or reuse a session ID for the conversation
session_id = str(uuid.uuid4())  # for example, "12345678-1234-1234-1234-123456789012"

def call_tool(tool_name, arguments, session_id):
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "x-amzn-bedrock-agentcore-policy-session-id": session_id
    }

    payload = {
        "jsonrpc": "2.0",
        "id": "request-1",
        "method": "tools/call",
        "params": {
            "name": tool_name,
            "arguments": arguments
        }
    }

    response = requests.post(GATEWAY_URL, headers=headers, json=payload)
    return response.json()


# First call - allowed
result1 = call_tool(
    "PaymentTool___transfer_funds",
    {"amount": 500, "recipient": "account-789"},
    session_id
)
print(result1)  # Success

# Second call in same session - may be denied by temporal policy
result2 = call_tool(
    "PaymentTool___transfer_funds",
    {"amount": 600, "recipient": "account-456"},
    session_id
)
print(result2)  # Denied if rate-limit policy applies

Ciclo de vida da sessão

Propagação de identidade em cenários multi-hop

Em arquiteturas de agentes, uma solicitação geralmente flui por várias AgentCore primitivas:

User -> Gateway1 -> Runtime (agent) -> Gateway1 (tool call) -> Target

Para que as políticas temporais funcionem nesses saltos, a identidade da sessão deve ser preservada. AgentCorelida com isso automaticamente usando a Cadeia de Identidade da Carga de Trabalho (WIC):

O que isso significa para você:

End-to-end fluxo:

User            Gateway1            Runtime            Gateway1            Target
 |  POST /mcp      |                   |                   |                  |
 |  + session-id X |                   |                   |                  |
 |  + Authorization|                   |                   |                  |
 |---------------->|                   |                   |                  |
 |                 | mint WAT1         |                   |                  |
 |                 | (sid=X, cpn=user) |                   |                  |
 |                 |  forward + WAT1   |                   |                  |
 |                 |------------------>|                   |                  |
 |                 |                   |exchange WAT1->WAT2|                  |
 |                 |                   | (sid=X preserved) |                  |
 |                 |                   | tool call + WAT2  |                  |
 |                 |                   |------------------>|                  |
 |                 |                   |                   | evaluate temporal|
 |                 |                   |                   | policy, session X|
 |                 |                   |                   |  forward         |
 |                 |                   |                   |----------------->|

Considerações importantes

Usando o ID da sessão com os SDKs

Você pode passar o ID da sessão de política por meio de qualquer cliente que ofereça suporte a cabeçalhos personalizados em solicitações do Gateway. Os exemplos a seguir mostram como incluí-lo ao usar o SDK MCP Python e os Strands Agents.

Use o mesmo valor de ID de sessão em todas as chamadas na mesma sessão lógica. Quando uma nova conversa começar, gere um novo ID de sessão.

Cliente MCP (SDK do Python):

Ao usar o SDK MCP Python com um transporte HTTP transmitido, inclua o ID da sessão nos cabeçalhos da conexão:

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
import asyncio

SESSION_ID = "12345678-1234-1234-1234-123456789012"

async def call_with_session(gateway_url, token, tool_name, arguments):
    headers = {
        "Authorization": f"Bearer {token}",
        "x-amzn-bedrock-agentcore-policy-session-id": SESSION_ID
    }

    async with streamablehttp_client(url=gateway_url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(name=tool_name, arguments=arguments)
            return result

result = asyncio.run(call_with_session(
    "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
    "YOUR_TOKEN",
    "PaymentTool___transfer_funds",
    {"amount": 500, "recipient": "account-789"}
))

Agentes Strands:

Ao usar Strands Agents com um AgentCore Gateway como fonte da ferramenta, passe o ID da sessão nos cabeçalhos de transporte do cliente MCP. Todas as chamadas de ferramentas que o agente faz durante a sessão têm a mesma sessão, e as políticas temporais avaliam o histórico completo.

from strands.tools.mcp.mcp_client import MCPClient
from mcp.client.streamable_http import streamablehttp_client

SESSION_ID = "12345678-1234-1234-1234-123456789012"

def create_transport(mcp_url, access_token):
    return streamablehttp_client(
        mcp_url,
        headers={
            "Authorization": f"Bearer {access_token}",
            "x-amzn-bedrock-agentcore-policy-session-id": SESSION_ID
        }
    )

mcp_client = MCPClient(lambda: create_transport(gateway_url, token))
with mcp_client:
    result = mcp_client.call_tool_sync(
        tool_use_id="tool-1",
        name="PaymentTool___transfer_funds",
        arguments={"amount": 500, "recipient": "account-789"}
    )

Real-world casos de uso do cliente

Os cenários a seguir ilustram como as políticas temporais abordam os desafios comuns de segurança e conformidade em aplicativos agentes.

Serviços financeiros — limitação da taxa de transferência

Um aplicativo fintech permite que os usuários finais iniciem transferências bancárias por meio de um agente conversacional. Sem a política temporal, um agente comprometido ou em loop poderia executar transferências ilimitadas em uma única sessão. Com um limite de taxa com escopo de sessão, o Gateway impõe um número máximo de transferências por sessão:

User: "Transfer $500 to Alice"      -> Allowed (1 of 3)
User: "Transfer $200 to Bob"        -> Allowed (2 of 3)
User: "Transfer $1000 to Charlie"   -> Allowed (3 of 3)
User: "Transfer $50 to Dave"        -> DENIED by temporal policy

Cada sessão de usuário usa seu próprio ID de sessão. O limite de taxa é redefinido quando uma nova sessão começa, porque um novo ID de sessão cria um novo limite de avaliação.

Saúde — controles de escalonamento

Um agente de saúde acessa os registros dos pacientes e também pode enviar mensagens para sistemas de notificação externos. Uma política temporal impõe que, uma vez acessados os dados do paciente, nenhuma chamada de API externa seja permitida pelo restante da sessão. Isso evita a exfiltração de dados, mesmo que as solicitações do agente sejam manipuladas no meio da sessão:

Agent: calls PatientRecords___read_chart      -> Allowed
Agent: calls ExternalAPI___send_notification  -> DENIED (sensitive data was accessed in this session)

A restrição não está na ferramenta em si — send_notification é permitida em sessões que nunca acessam dados do paciente. A política considera o que aconteceu anteriormente nesta sessão específica.

DevOps — restrições de sequenciamento

Um agente de implantação deve seguir uma sequência obrigatória: os testes devem ser aprovados antes que a implantação prossiga. Uma política temporal impõe que só Deploy pode ser chamada depois de ter RunTests sido chamada na mesma sessão:

Agent: calls Deploy___to_production   -> DENIED (RunTests not yet called in this session)
Agent: calls RunTests___execute       -> Allowed
Agent: calls Deploy___to_production   -> Allowed (RunTests was called earlier in this session)

Isso garante a sequência de implantação, independentemente de como o agente é solicitado ou de qual estrutura de orquestração o controla.

Multi-tenant SaaS — fiscalização do orçamento por usuário

Uma plataforma SaaS hospeda agentes de IA para vários usuários finais por trás de uma credencial de aplicativo compartilhada (CUSTOM_JWTcom sub reivindicações por usuário por meio de fluxos (OBO On-Behalf-Of )). A sessão de cada usuário recebe um ID de sessão exclusivo. Como o Gateway vincula a sessão ao ID da sessão e ao principal autenticado, as sessões de diferentes usuários são automaticamente isoladas. Uma política temporal impõe “no máximo 100 USD em chamadas de ferramentas por sessão” — avaliada de forma independente por usuário, mesmo que todo o tráfego chegue pela mesma credencial de aplicativo.

Escolhendo o escopo da sessão: sessões amplas versus estreitas

O ID da sessão que você fornece determina o limite de avaliação para políticas temporais. Escolher o escopo certo afeta tanto a segurança quanto a usabilidade:

Orientação:

Verificação de cabeçalho e implantações sem tempo de execução

Como o Gateway verifica o ID da sessão

Quando o Gateway recebe o x-amzn-bedrock-agentcore-policy-session-id cabeçalho, ele executa a seguinte validação:

Se você chamar o Gateway diretamente (sem AgentCore Runtime)

Quando seu aplicativo chama diretamente o endpoint do Gateway — por exemplo, um serviço de back-end fazendo solicitações HTTP para a URL do Gateway — você mesmo gerencia o ID da sessão:

Nenhuma configuração, permissão ou chamadas de API adicionais são necessárias. O Gateway cria a sessão na primeira utilização e a expira após 24 horas de inatividade.

Se suas solicitações fluírem pelo AgentCore Runtime

Quando as chamadas percorrem o caminho Usuário → Gateway → Runtime (agente) → Gateway (chamada de ferramenta), você só precisa passar o ID da sessão na solicitação inicial para o primeiro Gateway. A plataforma incorpora o ID da sessão dentro do Workload Access Token (WAT) e o propaga automaticamente por todos os saltos downstream. Seu código de agente não precisa ler, armazenar ou encaminhar o ID da sessão — ele chega ao Gateway receptor de forma transparente.

Sobre o Workload Access Token (WAT)

O Workload Access Token é um token opaco AWS assinado que carrega o contexto de identidade de uma solicitação à medida que ela flui entre os serviços. AgentCore Quando a política temporal está ativa, o WAT contém:

O WAT tem vida curta (TTL de 15 minutos), é assinado criptograficamente pelo serviço de AgentCore identidade e é opaco para todos os participantes. Ele não pode ser falsificado, adulterado ou decodificado por chamadores ou intermediários.

Você não interage diretamente com o WAT. Ele é transportado no X-Amz-Bedrock-AgentCore-Identity-WAT cabeçalho interno, que é gerenciado inteiramente pela plataforma. Essa explicação é fornecida para que você entenda como a continuidade da sessão funciona entre saltos — você não precisa realizar nenhuma ação em relação ao WAT.

Para obter mais detalhes sobre a identidade da carga de trabalho e os tokens de acesso, consulte Obter token de acesso à carga de trabalho e Entendendo as identidades da carga de trabalho.