Utiliser l'Isolation de Contexte

Utilisez cette compétence quand une application exécute des requêtes concurrentes, des pools de workers, des tâches asynchrones, des goroutines, ou plusieurs agents dans le même processus. Traitez la propriété de la scope-stack comme faisant partie de la limite de requête.

Règle Fondamentale

Chaque requête, agent ou workflow indépendant a besoin de sa propre scope stack. Ne partagez pas une stack mutable unique entre des travaux concurrents non liés, sauf si vous voulez une ancestralité partagée et des middlewares de scope-local partagés.

Modèle de Scope Intégré

• Une scope racine est toujours présente, et les scopes empilés forment un arbre parent-enfant en dessous.
• La hiérarchie des scopes détermine la parentalité des événements, les limites de durée de vie, et la visibilité pour les middlewares et abonnés de scope-local.
• Les types de scope standard incluent Agent, Function, Tool, Llm, Retriever, Embedder, Reranker, Guardrail, Evaluator, Custom, et Unknown.
• Les événements de début et fin de scope peuvent porter des payloads sémantiques input et output quand le scope représente une requête, une tâche, ou une limite de résultat significative.
• Les enregistrements de scope-local disparaissent quand la scope propriétaire se ferme ; utilisez-les pour les comportements qui ne doivent pas survivre à une requête ou une exécution d'agent.
• Les mark events sont utiles pour les tentatives, les points de contrôle, les interruptions, et les transitions d'état importantes qui ne sont pas des spans complets.

Valeurs par défaut par langage

• Python : fiez-vous au comportement task-local via get_scope_stack() et contextvars, ou propagez explicitement quand le travail quitte le contexte d'exécution actuel
• Rust core : utilisez des assistants de runtime comme create_scope_stack(), current_scope_stack(), et set_thread_scope_stack(...) quand une intégration a besoin d'une propriété de stack explicite
• Go : utilisez NewScopeStack() et ScopeStack.Run(...) pour une utilisation goroutine-safe
• Node.js : créez et définissez explicitement une scope stack pour le chemin d'exécution actuel avec createScopeStack() et setThreadScopeStack(...)

Défaillances courantes

• Les événements de différentes requêtes apparaissent sous un seul UUID racine
• Les middlewares de scope-local fuient entre les requêtes
• Le travail du worker-thread s'exécute sans la scope active attendue
• Les intégrations activent NeMo Relay sans une stack explicitement initialisée
• Dépendre d'une stack thread-local après avoir traversé des tâches asynchrones, des goroutines, ou des limites de workers JS

Compétences liées

• nemo-relay-instrument-calls
• nemo-relay-plugin-observability
• nemo-relay-debug-runtime-integration