Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Sesiones de políticas y propagación de identidades

Con las políticas temporales, puede definir reglas basadas en eventos pasados ocurridos en una sesión, no solo en la solicitud actual. Puede aplicar restricciones como las siguientes:

Una sesión de políticas agrupa varias invocaciones de Gateway en una sola sesión lógica. La sesión es el límite sobre el que se evalúan las reglas de políticas temporales.

Funcionamiento

Pasando el identificador de sesión de la política

Incluya el x-amzn-bedrock-agentcore-policy-session-id encabezado en sus solicitudes al Gateway. Debe generar el ID de sesión y enviarlo en cada solicitud, empezando por la primera. The Gateway no genera un identificador de sesión en su nombre. El valor es una cadena que identifica la sesión y recomendamos un UUIDv4. Envía el mismo ID en todas las solicitudes de la misma sesión.

Si omite el encabezado o envía un valor vacío, la puerta de enlace no establece una sesión. Si el motor de políticas asociado contiene una política temporal, las solicitudes sin un identificador de sesión fallan y se produce un error de validación.

Para conocer el formato aceptado y cómo lo valida la puerta de enlace, consulte Verificación de encabezados e implementaciones que no estén en tiempo de ejecución.

Primera solicitud (crea la sesión):

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"
      }
    }
  }'

Solicitudes posteriores (continuar la sesión):

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"
      }
    }
  }'

Si su política temporal limita cada sesión a una transferencia, se rechazará la segunda solicitud que se muestra en el ejemplo anterior.

Ejemplo de 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 de la sesión

Propagación de identidades en escenarios de saltos múltiples

En las arquitecturas de agencia, una solicitud suele pasar por varias primitivas: AgentCore

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

Para que las políticas temporales funcionen en todos estos saltos, se debe preservar la identidad de la sesión. AgentCoregestiona esto automáticamente mediante la cadena de identidad de carga de trabajo (WIC):

Qué significa esto para usted:

End-to-end flujo:

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         |
 |                 |                   |                   |----------------->|

Consideraciones importantes

Uso del ID de sesión con los SDK

Puede pasar el ID de sesión de la política a cualquier cliente que admita encabezados personalizados en las solicitudes de Gateway. Los siguientes ejemplos muestran cómo incluirlo al usar el SDK de Python de MCP y los agentes de Strands.

Utilice el mismo valor de ID de sesión en todas las llamadas de la misma sesión lógica. Cuando se inicie una conversación nueva, genere un nuevo identificador de sesión.

Cliente MCP (SDK de Python):

Cuando utilices el SDK de Python de MCP con un transporte HTTP que se pueda transmitir, incluye el identificador de sesión en los encabezados de conexión:

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 de Strands:

Cuando utilice agentes de Strands con una AgentCore puerta de enlace como fuente de herramientas, introduzca el identificador de sesión en los encabezados de transporte del cliente MCP. Todas las llamadas a las herramientas que el agente hace durante la sesión corresponden a la misma sesión, y las políticas temporales evalúan el historial 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 de clientes

Los siguientes escenarios ilustran cómo las políticas temporales abordan los desafíos comunes de seguridad y cumplimiento en las aplicaciones de agencia.

Servicios financieros: limitación de la tasa de transferencia

Una aplicación de tecnología financiera permite a los usuarios finales iniciar transferencias bancarias a través de un agente conversacional. Sin una política temporal, un agente comprometido o en bucle podría ejecutar transferencias ilimitadas en una sola sesión. Con un límite de velocidad determinado por sesión, el Gateway impone un número máximo de transferencias por sesión:

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 sesión de usuario usa su propio identificador de sesión. El límite de frecuencia se restablece cuando se inicia una nueva sesión, porque un nuevo identificador de sesión crea un nuevo límite de evaluación.

Atención médica: controles de escalamiento

Un agente sanitario accede a los registros de los pacientes y también puede enviar mensajes a sistemas de notificación externos. Una política temporal establece que, una vez que se ha accedido a los datos del paciente, no se permiten llamadas a la API externas durante el resto de la sesión. Esto evita la filtración de datos incluso si las instrucciones del agente se manipulan a mitad de la sesión:

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

La restricción no está en la herramienta en sí, sino que está permitida en las sesiones en las que nunca send_notification se accede a los datos de los pacientes. La política considera lo que ocurrió al principio de esta sesión en particular.

DevOps — restricciones de secuenciación

Un agente de despliegue debe seguir una secuencia obligatoria: las pruebas deben pasar antes de continuar con el despliegue. Se aplica una política temporal que solo se Deploy puede invocar después de que se RunTests haya llamado en la misma sesión:

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)

Esto garantiza la secuencia de despliegue independientemente de cómo se lo pida al agente o del marco de orquestación que lo controle.

Multi-tenant SaaS: aplicación del presupuesto por usuario

Una plataforma SaaS aloja agentes de IA para varios usuarios finales detrás de una credencial de aplicación compartida (CUSTOM_JWTcon flujos de sub solicitudes por usuario a través On-Behalf-Of de (OBO)). La sesión de cada usuario recibe un identificador de sesión único. Como la puerta de enlace vincula la sesión tanto al identificador de sesión como al principal autenticado, las sesiones de los diferentes usuarios se aíslan automáticamente. Una política temporal impone «un máximo de 100 dólares en llamadas a herramientas por sesión» y se evalúa de forma independiente por usuario, aunque todo el tráfico llegue a través de la misma credencial de aplicación.

Elección del alcance de la sesión: sesiones amplias frente a sesiones reducidas

El identificador de sesión que proporcione determina el límite de evaluación de las políticas temporales. La elección del ámbito correcto afecta tanto a la seguridad como a la usabilidad:

Directrices:

Verificación de encabezados e implementaciones que no están en tiempo de ejecución

Cómo verifica la puerta de enlace el ID de la sesión

Cuando la puerta de enlace recibe el x-amzn-bedrock-agentcore-policy-session-id encabezado, realiza la siguiente validación:

Si llamas al Gateway directamente (sin AgentCore Runtime)

Cuando tu aplicación llama directamente al punto final de Gateway (por ejemplo, un servicio de backend que realiza solicitudes HTTP a la URL de Gateway), tú mismo administras el ID de sesión:

No se necesitan configuraciones, permisos ni llamadas a la API adicionales. El Gateway crea la sesión la primera vez que se usa y la vence después de 24 horas de inactividad.

Si sus solicitudes fluyen a través de Runtime AgentCore

Cuando las llamadas atraviesan la ruta Usuario → Puerta de enlace → Tiempo de ejecución (agente) → Puerta de enlace (llamada a la herramienta), solo tiene que pasar el ID de sesión de la solicitud inicial a la primera puerta de enlace. La plataforma incrusta el identificador de sesión en el token de acceso a la carga de trabajo (WAT) y lo propaga automáticamente a través de todos los saltos descendentes. El código de agente no necesita leer, almacenar ni reenviar el ID de sesión, sino que llega a la puerta de enlace receptora de forma transparente.

Acerca del token de acceso a la carga de trabajo (WAT)

El token de acceso a la carga AWS de trabajo es un token opaco firmado que contiene el contexto de identidad de una solicitud a medida que fluye entre AgentCore los servicios. Cuando la política temporal está activa, el WAT contiene:

El WAT es de corta duración (TTL de 15 minutos), está firmado criptográficamente por el servicio de AgentCore identidad y es opaco para todos los participantes. Las personas que llaman o los intermediarios no pueden falsificarlo, manipularlo ni decodificarlo.

No interactúas directamente con el WAT. Se encuentra en la X-Amz-Bedrock-AgentCore-Identity-WAT cabecera interna, que es gestionada en su totalidad por la plataforma. Esta explicación se proporciona para que comprenda cómo funciona la continuidad de las sesiones en todos los saltos; no es necesario que tome ninguna medida en relación con el WAT.

Para obtener más información sobre la identidad de la carga de trabajo y los tokens de acceso, consulte Obtener el token de acceso a la carga de trabajo y Comprender las identidades de las cargas de trabajo.