Arrêter une session de course

L'StopRuntimeSessionopération vous permet de mettre fin immédiatement aux sessions AgentCore d'exécution actives de l'agent pour un nettoyage des ressources et une gestion du cycle de vie des sessions appropriés.

Lorsqu'elle est appelée, cette opération met fin instantanément à la session spécifiée et arrête toutes les réponses de streaming en cours. Cela permet de libérer correctement les ressources du système et d'éviter l'accumulation de sessions orphelines.

StopRuntimeSessionÀ utiliser dans les scénarios suivants :

• User-initiated fin  : lorsque les utilisateurs terminent explicitement leur conversation

• Arrêt de l'application  : nettoyage proactif avant la fermeture de l'application

• Gestion des erreurs  : arrêt forcé des sessions qui ne répondent pas ou qui sont bloquées

• Gestion des quotas  : respectez les limites de session en fermant les sessions non utilisées

• Gestion des délais  : nettoyez les sessions qui dépassent la durée prévue

Conditions préalables

Pour l'utiliser StopRuntimeSession, vous devez :

• Autorisation IAM bedrock-agentcore:StopRuntimeSession

• Un ARN d' AgentCore exécution d'agent valide

• L'ID d'une session active à terminer

Exemple

AWS SDK

1. Vous pouvez utiliser le AWS SDK pour arrêter les sessions AgentCore Runtime par programmation.

   Exemple Python utilisant boto3 pour arrêter une session AgentCore Runtime.

   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. Pour les applications utilisant l'authentification OAuth, effectuez des requêtes HTTPS directes :

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

Format de la réponse

Format de réponse attendu pour des StopRuntimeSession opérations réussies.

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

Gestion des erreurs

Réponses aux erreurs courantes :

Code d'état	Erreur	Description
404	ResourceNotFoundException	Session introuvable ou déjà terminée
403	AccessDeniedException	Autorisations insuffisantes
400	ValidationException	Paramètres non valides
409	RetryableConflictException	Fonctionnement de la session en cours, veuillez réessayer
500	InternalServerException	Erreur de service

Le service revient RetryableConflictException (HTTP 409) lorsque votre StopRuntimeSession appel arrive alors que le service est toujours en cours de provisionnement ou de fermeture de la session. Cette condition est transitoire et peut être réessayée. Réessayez avec un court délai exponentiel au lieu de le traiter comme une défaillance terminale. Les AWS kits SDK réessayent automatiquement cette exception lorsque les nouvelles tentatives par défaut sont activées. Si vous avez désactivé les nouvelles tentatives ou si vous appelez l'API directement sans AWS SDK (par exemple, la requête HTTPS présentée plus haut), réessayez vous-même.

Bonnes pratiques

Gestion du cycle de vie des sessions

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)

Recommandations

• Gérez toujours les exceptions lors de l'arrêt des sessions

• Suivez les sessions actives dans votre application à des fins de nettoyage

• Définissez des délais d'attente pour les demandes d'arrêt afin d'éviter les blocages

• Consigner les terminaisons de session à des fins de débogage et de surveillance

• Utilisez des gestionnaires de sessions pour les applications complexes comportant plusieurs sessions