View a markdown version of this page

Detener una sesión en ejecución - Amazon Bedrock AgentCore
Requisitos previosFormato de las respuestasGestión de erroresPrácticas recomendadas

Detener una sesión en ejecución

La StopRuntimeSession operación permite finalizar inmediatamente las sesiones activas del agente en tiempo de AgentCore ejecución para una limpieza adecuada de los recursos y una gestión del ciclo de vida de las sesiones adecuadas.

Cuando se invoca, esta operación finaliza instantáneamente la sesión especificada y detiene cualquier respuesta de streaming en curso. Esto permite que los recursos del sistema se liberen correctamente y evita la acumulación de sesiones huérfanas.

Úselo StopRuntimeSession en los siguientes escenarios:

  • User-initiated Final: cuando los usuarios concluyen su conversación de forma explícita

  • Cierre de la aplicación: limpieza proactiva antes del cierre de la aplicación

  • Gestión de errores: forzar la finalización de sesiones que no responden o están estancadas

  • Administración de cuotas: manténgase dentro de los límites de las sesiones cerrando las sesiones no utilizadas

  • Gestión del tiempo de espera: limpie las sesiones que superen la duración prevista

Requisitos previos

Para usarlo StopRuntimeSession, necesitas:

  • Permiso de IAM bedrock-agentcore:StopRuntimeSession

  • Un ARN de tiempo de AgentCore ejecución de agente válido

  • El ID de una sesión activa que se va a finalizar

ejemplo
AWS SDK

  1. Puede usar el AWS SDK para detener las sesiones en AgentCore tiempo de ejecución mediante programación.

    Ejemplo de Python que usa boto3 para detener una sesión en AgentCore tiempo de ejecución.

    import boto3

# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore', region_name='us-west-2')

try:
    # Stop the runtime session
    response = client.stop_runtime_session(
        agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
        runtimeSessionId='your-session-id',
        qualifier='DEFAULT'  # Optional: endpoint name
    )

    print(f"Session terminated successfully")
    print(f"Request ID: {response['ResponseMetadata']['RequestId']}")

except client.exceptions.ResourceNotFoundException:
    print("Session not found or already terminated")
except client.exceptions.AccessDeniedException:
    print("Insufficient permissions to stop session")
except Exception as e:
    print(f"Error stopping session: {str(e)}")
HTTPS request

  1. Para las aplicaciones que utilizan la autenticación OAuth, realiza solicitudes HTTPS directas:

    import requests
import urllib.parse

def stop_session_with_oauth(agent_arn, session_id, bearer_token, qualifier="DEFAULT"):
    # URL encode the agent ARN
    encoded_arn = agent_arn.replace(':', '%3A').replace('/', '%2F')

    # Construct the endpoint URL
    url = f"https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/{encoded_arn}/stopruntimesession?qualifier={qualifier}"

    headers = {
        "Authorization": f"Bearer {bearer_token}",
        "Content-Type": "application/json",
        "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": session_id
    }

    try:
        response = requests.post(url, headers=headers)
        response.raise_for_status()

        print(f"Session {session_id} terminated successfully")
        return response.json()

    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 404:
            print("Session not found or already terminated")
        elif e.response.status_code == 403:
            print("Insufficient permissions or invalid token")
        else:
            print(f"HTTP error: {e.response.status_code}")
        raise
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {str(e)}")
        raise

# Usage
stop_session_with_oauth(
    agent_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent",
    session_id="your-session-id",
    bearer_token="your-oauth-token"
)

Formato de las respuestas

Formato de respuesta esperado para que las operaciones se realicen correctamenteStopRuntimeSession.

{
    "ResponseMetadata": {
        "RequestId": "12345678-1234-1234-1234-123456789012",
        "HTTPStatusCode": 200
    }
}

Gestión de errores

Respuestas de error comunes:

Código de estado Error Description (Descripción)

404

ResourceNotFoundException

No se ha encontrado la sesión o ya ha finalizado

403

AccessDeniedException

Permisos insuficientes

400

ValidationException

Parámetros no válidos

500

InternalServerException

Error de servicio

Prácticas recomendadas

Administración del ciclo de vida de las

class SessionManager:
    def __init__(self, client, agent_arn):
        self.client = client
        self.agent_arn = agent_arn
        self.active_sessions = set()

    def invoke_agent(self, session_id, payload):
        """Invoke agent and track session"""
        try:
            response = self.client.invoke_agent_runtime(
                agentRuntimeArn=self.agent_arn,
                runtimeSessionId=session_id,
                payload=payload
            )
            self.active_sessions.add(session_id)
            return response
        except Exception as e:
            print(f"Failed to invoke agent: {e}")
            raise

    def stop_session(self, session_id):
        """Stop session and remove from tracking"""
        try:
            self.client.stop_runtime_session(
                agentRuntimeArn=self.agent_arn,
                runtimeSessionId=session_id,
                qualifier=endpoint_name
            )
            self.active_sessions.discard(session_id)
            print(f"Session {session_id} stopped")
        except Exception as e:
            print(f"Failed to stop session {session_id}: {e}")

    def cleanup_all_sessions(self):
        """Stop all tracked sessions"""
        for session_id in list(self.active_sessions):
            self.stop_session(session_id)

Recomendaciones

  • Gestione siempre las excepciones al detener las sesiones

  • Realice un seguimiento de las sesiones activas en su aplicación para su limpieza

  • Establezca tiempos de espera para las solicitudes de suspensión para evitar que se bloqueen

  • Registre las terminaciones de las sesiones para la depuración y la supervisión

  • Utilice administradores de sesiones para aplicaciones complejas con varias sesiones