Flux d'événements de session

La communication avec les Claude Managed Agents est basée sur des événements. Vous envoyez des événements utilisateur à l'agent et recevez en retour des événements d'agent et de session pour suivre l'état.



Types d'événements

Les événements circulent dans deux directions.

• Les événements utilisateur et les événements système sont ceux que vous envoyez à l'agent : les événements user.* lancent une session et la pilotent au fur et à mesure de sa progression ; system.message met à jour l'invite système de l'agent entre les tours.
• Les événements de session, les événements de span et les événements d'agent vous sont envoyés pour vous donner une visibilité sur l'état de votre session et la progression de l'agent. Les connexions de streaming qui y souscrivent reçoivent également des deltas d'événements.

Les chaînes de type d'événement de session, de span, d'agent, d'utilisateur et de système suivent une convention de nommage {domain}.{action}. Les événements d'aperçu delta réservés au streaming (event_start, event_delta) font exception. Consultez Types d'événements dans la référence pour le catalogue complet.

Chaque événement persisté inclut un horodatage processed_at indiquant quand l'événement a été enregistré côté serveur. Si processed_at est null, cela signifie que l'événement a été mis en file d'attente par le harnais et qu'il est traité une fois que les événements précédents ont fini d'être traités.



Intégration des événements



Deltas d'événements

Par défaut, le texte de réponse de l'agent arrive dans le flux sous forme d'événements agent.message mis en tampon, chacun émis uniquement une fois que la requête au modèle qui l'a produit est terminée. Les deltas d'événements vous permettent d'afficher ce texte de manière incrémentale, comme un aperçu en direct, pendant que le modèle est encore en train de le générer. Un aperçu n'est pas la réponse : les aperçus sont une aide à l'affichage fournie au mieux, et l'événement agent.message mis en tampon reste toujours l'enregistrement faisant autorité. Un client qui ignore les aperçus reçoit tout de même un flux complet et correct.



Souscrire aux aperçus

Les aperçus sont activés sur demande, par connexion de streaming. Ajoutez le paramètre de requête event_deltas[] à GET /v1/sessions/{session_id}/events/stream, en le répétant une fois pour chaque type d'événement que vous souhaitez prévisualiser. Les valeurs acceptées sont agent.message et agent.thinking ; toute autre valeur renvoie une erreur 400. Seul le flux d'événements au niveau de la session prend en charge ce paramètre. Les flux d'événements de threads de session le rejettent.

Lorsqu'un événement prévisualisé commence, le flux émet un event_start contenant le type et l'id de l'événement à venir :

{
  "type": "event_start",
  "event": {
    "type": "agent.message",
    "id": "sevt_01abc..."
  }
}

Pour agent.message, le début est suivi d'événements event_delta contenant du texte incrémental. Chaque delta nomme l'événement qu'il étend dans event_id et le bloc de contenu qu'il étend dans delta.index :

{
  "type": "event_delta",
  "event_id": "sevt_01abc...",
  "delta": {
    "type": "content_delta",
    "index": 0,
    "content": {
      "type": "text",
      "text": "Here is the summary"
    }
  }
}

Lorsqu'un événement agent.thinking est prévisualisé, seul l'event_start est émis. Aucun événement event_delta ne suit, et le contenu arrive dans l'événement agent.thinking mis en tampon comme d'habitude.

Contrairement aux événements persistés, event_start et event_delta n'ont pas d'id ni de processed_at propres. Le seul identifiant qu'ils portent est l'id de l'événement qu'ils prévisualisent.



Accumuler et réconcilier

Les SDK Python, TypeScript et Go incluent un utilitaire d'accumulateur qui indexe l'aperçu par l'id de l'événement et gère la comptabilité de l'index pour vous. Le modèle manuel fonctionne dans tous les langages : dans les autres SDK, appliquez-le aux types d'événements générés.

Dans le modèle manuel, traitez l'aperçu comme un tampon de travail et l'événement mis en tampon comme l'enregistrement de référence. Indexez le tampon par (event_id, index). Réconciliez par requête au modèle : un tour s'ouvre avec un seul événement session.status_running, puis sur un tour qui se termine normalement, chaque requête au modèle produit, dans l'ordre, span.model_request_start, event_start, les événements event_delta, l'agent.message mis en tampon, et enfin span.model_request_end (dans l'onglet Événements de span). Traitez chaque événement au fur et à mesure de son arrivée :

1. Sur event_start, notez l'id annoncé. Les identifiants correspondent toujours : event_start.event.id, chaque event_delta.event_id, et l'id de l'agent.message mis en tampon sont la même valeur.
2. Sur chaque event_delta, ajoutez delta.content.text à l'entrée située à (event_id, delta.index) et affichez le texte en cours. Le premier delta pour un index crée cette entrée.
3. Lorsque l'agent.message mis en tampon arrive, faites-le correspondre par id, supprimez l'aperçu accumulé et affichez le contenu du message à la place.
4. Sur span.model_request_end, fermez tout aperçu qui n'a pas été réconcilié par son événement mis en tampon. Aucun autre delta n'arrivera pour celui-ci. Si le tour génère une erreur ou est interrompu, l'événement mis en tampon peut ne jamais arriver ; span.model_request_end arrive quand même.

# Instantanés d'aperçu, indexés par id d'événement. accumulate_managed_agents_event agrège chaque
# event_start / event_delta en un instantané agent.message ; le
# agent.message mis en tampon le remplace.
previews: dict[str, BetaManagedAgentsAgentMessageEvent] = {}

# Activez les aperçus agent.message sur cette connexion
with client.beta.sessions.events.stream(
    session.id, event_deltas=["agent.message"]
) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Describe the repo in one sentence."}],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "event_start":
                snapshot = accumulate_managed_agents_event(None, event)
                if snapshot is not None:
                    previews[event.event.id] = snapshot
                print(f"event_start             {event.event.type} {event.event.id}")
            case "event_delta":
                preview = accumulate_managed_agents_event(previews.get(event.event_id), event)
                if preview is not None:
                    previews[event.event_id] = preview
                    text = "".join(block.text for block in preview.content)
                    print(f"event_delta             preview: {text!r}")
            case "agent.message":
                # L'événement mis en tampon fait foi : il remplace et ferme l'aperçu
                preview = accumulate_managed_agents_event(previews.pop(event.id, None), event)
                text = "".join(block.text for block in preview.content)
                print(f"agent.message           {event.id} {text!r}")
            case "span.model_request_end":
                # Plus aucun delta n'arrive. Fermez tout aperçu dont
                # l'événement mis en tampon n'est jamais arrivé.
                for event_id in previews:
                    print(f"span.model_request_end  closing preview for {event_id}")
                previews.clear()
            case "session.status_idle":
                break



Limitations

Les aperçus sont optimisés pour la réactivité. Développez en tenant compte de ces contraintes :

• Au mieux : Sous charge, le serveur peut abandonner des deltas pour un événement. Dans ce cas, vous recevez un préfixe contigu du texte, puis plus aucun delta pour cet événement. L'agent.message mis en tampon arrive tout de même complet. Ne traitez jamais un aperçu accumulé comme définitif.
• Pas de relecture à la reconnexion : Les deltas ne sont livrés qu'à la connexion qui y a souscrit, tant qu'elle est ouverte. Si le flux est interrompu, suivez la procédure de reconnexion dans l'onglet Streaming d'événements : rouvrez le flux et listez l'historique des événements. L'historique inclut tous les événements mis en tampon émis pendant que vous étiez déconnecté, y compris l'agent.message que votre aperçu attendait. Il n'existe aucun moyen de redemander les deltas manqués.
• Thread principal, texte uniquement : Les aperçus couvrent le texte de l'assistant sur le thread principal de la session. L'utilisation d'outils, les résultats d'outils, les résultats MCP et l'activité sur d'autres threads de session ne sont jamais prévisualisés.
• agent.thinking avec début uniquement : Un aperçu agent.thinking n'émet que l'event_start comme signal qu'un bloc de réflexion a commencé ; aucun événement event_delta ne le suit.
• Jamais persisté : event_start et event_delta n'existent que sur le flux en direct. Ils n'apparaissent pas dans l'historique des événements de la session (GET /v1/sessions/{session_id}/events).



Scénarios supplémentaires



Gestion des appels d'outils personnalisés

Lorsque l'agent invoque un outil personnalisé :

1. La session émet un événement agent.custom_tool_use contenant le nom de l'outil et l'entrée.
2. La session se met en pause avec un événement session.status_idle contenant stop_reason: requires_action. Les identifiants des événements bloquants se trouvent dans le tableau stop_reason.event_ids.
3. Exécutez l'outil dans votre système et envoyez un événement user.custom_tool_result pour chacun, en passant l'identifiant de l'événement dans le paramètre custom_tool_use_id avec le contenu du résultat.
4. Une fois tous les événements bloquants résolus, la session repasse à l'état running.

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop_reason := event.stop_reason):
            match stop_reason.type:
                case "requires_action":
                    for event_id in stop_reason.event_ids:
                        # Rechercher l'événement d'utilisation d'outil personnalisé et l'exécuter
                        tool_event = events_by_id[event_id]
                        result = call_tool(tool_event.name, tool_event.input)

                        # Renvoyer le résultat
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.custom_tool_result",
                                    "custom_tool_use_id": event_id,
                                    "content": [{"type": "text", "text": result}],
                                },
                            ],
                        )
                case "end_turn":
                    break



Confirmation d'outil

Lorsqu'une politique de permissions exige une confirmation avant l'exécution d'un outil :

1. La session émet un événement agent.tool_use ou agent.mcp_tool_use.
2. La session se met en pause avec un événement session.status_idle contenant stop_reason: requires_action. Les identifiants des événements bloquants se trouvent dans le tableau stop_reason.event_ids.
3. Envoyez un événement user.tool_confirmation pour chacun, en passant l'identifiant de l'événement dans le paramètre tool_use_id. Définissez result sur "allow" ou "deny". Utilisez deny_message pour expliquer un refus.
4. Une fois tous les événements bloquants résolus, la session repasse à l'état running.

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop_reason := event.stop_reason):
            match stop_reason.type:
                case "requires_action":
                    for event_id in stop_reason.event_ids:
                        # Approuver l'appel d'outil en attente
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.tool_confirmation",
                                    "tool_use_id": event_id,
                                    "result": "allow",
                                },
                            ],
                        )
                case "end_turn":
                    break



Reprise d'une session inactive

Les sessions persistent entre les interactions. L'historique de conversation est préservé à moins que la session ne soit explicitement supprimée. Lorsqu'une session devient inactive, son sandbox fait l'objet d'un point de contrôle, préservant l'état complet du sandbox, y compris le système de fichiers, les paquets installés et tous les fichiers créés par l'agent. Cela vous permet de reprendre proprement après une période d'inactivité.

Pour reprendre une session, envoyez-lui un événement user.message comme d'habitude :

# En production, passez l'ID stocké de la session que vous souhaitez reprendre.
ant beta:sessions:events send --session-id "$SESSION_ID" <<'YAML'
events:
  - type: user.message
    content:
      - type: text
        text: Now run the tests against the changes you made earlier.
YAML



Envoi de messages système

Envoyez un événement system.message pour mettre à jour l'invite système de l'agent entre les tours. Contrairement au champ system de la définition de l'agent (qui est fixé à la création de la session), system.message vous permet de modifier l'invite système au fur et à mesure de la progression de la session. Utilisez-le lorsque l'agent a besoin de directives système mises à jour en cours de session : une persona différente, des contraintes révisées, ou du contexte récupéré à l'exécution qui doit façonner le comportement du modèle pour la suite.

ant beta:sessions:events send --session-id "$SESSION_ID" <<'YAML'
events:
  - type: system.message
    content:
      - type: text
        text: "The user's current timezone is America/New_York."
YAML

system.message ne peut pas être envoyé lorsque la session est inactive avec stop_reason: requires_action. content accepte de 1 à 1000 éléments de texte.



Suivi de l'utilisation

L'objet session inclut un champ usage avec des statistiques cumulatives de tokens. Récupérez la session après qu'elle soit devenue inactive pour lire les derniers totaux, et utilisez-les pour suivre les coûts, appliquer des budgets ou surveiller la consommation.

{
  "id": "sesn_01...",
  "status": "idle",
  "usage": {
    "input_tokens": 5000,
    "output_tokens": 3200,
    "cache_creation_input_tokens": 2000,
    "cache_read_input_tokens": 20000
  }
}

input_tokens indique les tokens d'entrée non mis en cache et output_tokens indique le total des tokens de sortie sur l'ensemble des appels au modèle dans la session. Les champs cache_creation_input_tokens et cache_read_input_tokens reflètent l'activité de mise en cache des prompts. Les entrées de cache utilisent un TTL de 5 minutes, de sorte que les tours consécutifs dans cette fenêtre bénéficient de lectures de cache, ce qui réduit le coût par token.



Observabilité dans la Console

La Console fournit une vue chronologique visuelle de vos sessions d'agent. Accédez à la section Claude Managed Agents dans la Console pour voir :

• Liste des sessions : Toutes les sessions avec leur statut, leur heure de création et leur modèle
• Vue de traçage : Une vue chronologique des événements (contenu, horodatages, utilisation de tokens) au sein d'une session. Les vues de traçage ne sont accessibles qu'aux Développeurs et aux Administrateurs.
• Exécution d'outils : Détails de chaque appel d'outil et de son résultat



Conseils de débogage

• Vérifiez les événements de session : Les erreurs de session sont transmises via l'événement session.error
• Examinez les résultats d'outils : Les échecs d'exécution d'outils expliquent souvent un comportement inattendu de l'agent
• Suivez l'utilisation des tokens : Surveillez la consommation de tokens pour optimiser les prompts et réduire les coûts
• Utilisez les invites système : Ajoutez des instructions de journalisation à l'invite système pour que l'agent explique son raisonnement