Flux d'événements de session

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

Toutes les demandes de l'API Managed Agents nécessitent l'en-tête bêta managed-agents-2026-04-01. Le SDK définit automatiquement l'en-tête bêta.

Types d'événements

Les événements circulent dans deux directions.

Les événements utilisateur sont ce que vous envoyez à l'agent pour démarrer une session et la diriger au fur et à mesure de sa progression.
Les événements de session, les événements d'étendue et les événements d'agent vous sont envoyés pour vous permettre d'observer l'état de votre session et la progression de l'agent.

Les chaînes de type d'événement suivent une convention de nommage {domain}.{action}.

Chaque événement 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 sera traité après la fin du traitement des événements précédents.

Intégration des événements

Scénarios supplémentaires

Gestion des appels d'outils personnalisés

Lorsque l'agent invoque un outil personnalisé :

La session émet un événement agent.custom_tool_use contenant le nom et l'entrée de l'outil.
La session s'interrompt avec un événement session.status_idle contenant stop_reason: requires_action. Les ID d'événement de blocage se trouvent dans le tableau stop_reason.requires_action.event_ids.
Exécutez l'outil dans votre système et envoyez un événement user.custom_tool_result pour chacun, en passant l'ID d'événement dans le paramètre custom_tool_use_id ainsi que le contenu du résultat.
Une fois que tous les événements de blocage sont résolus, la session revient à running.

Confirmation d'outil

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

La session émet un événement agent.tool_use ou agent.mcp_tool_use.
La session s'interrompt avec un événement session.status_idle contenant stop_reason: requires_action. Les ID d'événement bloquants se trouvent dans le tableau stop_reason.requires_action.event_ids.
Envoyez un événement user.tool_confirmation pour chacun, en passant l'ID d'événement dans le paramètre tool_use_id. Définissez result sur "allow" ou "deny". Utilisez deny_message pour expliquer un refus.
Une fois que tous les événements bloquants sont résolus, la session revient à running.

Suivi de l'utilisation

L'objet session inclut un champ usage avec des statistiques de jetons cumulatifs. Récupérez la session après qu'elle soit devenue inactive pour lire les totaux les plus récents, 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 rapporte les jetons d'entrée non mis en cache et output_tokens rapporte le total des jetons de sortie sur tous les appels de 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 invites. Les entrées de cache utilisent un TTL de 5 minutes, donc les tours consécutifs dans cette fenêtre bénéficient des lectures de cache, ce qui réduit le coût par jeton.

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop := event.stop_reason):
            match stop.type:
                case "requires_action":
                    for event_id in stop.event_ids:
                        # Look up the custom tool use event and execute it
                        tool_event = events_by_id[event_id]
                        result = call_tool(tool_event.name, tool_event.input)

                        # Send the result back
                        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

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop := event.stop_reason):
            match stop.type:
                case "requires_action":
                    for event_id in stop.event_ids:
                        # Approve the pending tool call
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.tool_confirmation",
                                    "tool_use_id": event_id,
                                    "result": "allow",
                                },
                            ],
                        )
                case "end_turn":
                    break