Flux d'événements de session

La communication avec les agents gérés Claude 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 sont ce que vous envoyez à l'agent pour démarrer une session et la piloter au fur et à mesure de sa progression.
• Les événements de session, les événements de span et les événements d'agent vous sont envoyés pour la visibilité sur l'état de votre session et la progression de l'agent.

Les chaînes de type d'événement suivent la 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.

Consultez la référence API des événements de session pour le schéma complet de chaque type d'événement.

Intégration des événements

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 et l'entrée de l'outil.
2. La session se met en pause avec un événement session.status_idle contenant stop_reason: requires_action. Les identifiants d'événements bloquants se trouvent dans le tableau stop_reason.requires_action.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 d'é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 revient à l'état running.

Confirmation d'outil

Lorsqu'une politique de permission 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 d'événements bloquants se trouvent dans le tableau stop_reason.requires_action.event_ids.
3. Envoyez un événement user.tool_confirmation pour chacun, en passant l'identifiant d'é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.

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 passée à l'état inactif 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 pour 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 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 des lectures de cache, ce qui réduit le coût par token.