Conventions de payload
Chaque span (mesure d'une opération) transporte un raw_payload JSON. Avec le SDK, ces champs sont
posés automatiquement : cette section sert surtout à comprendre ce que le cockpit attend (et est
indispensable en instrumentation OTel manuelle).
Anatomie d'un span run
{"record_type": "run","trace_id": "uuid","span_id": "16 hex","parent_span_id": "16 hex (ou vide)","flow_definition_id": "my_sia","flow_id": "uuid7","name": "step display name","payload": { "flow": { "name": "my_sia_main", "phase": "ANALYSIS", "step": "answer" }, "asset": { "kind": "llm", "role": "analysis", "name": "gpt-4o", "provider": "openai" }, "input": {}, "output": {}}}flow.name — obligatoire
Slug stable identifiant la définition logique du flow. Tous les spans d'une exécution doivent
porter le même flow.name : c'est lui qui permet d'agréger les spans en un flow lisible.
flow = start_flow(client, flow_definition_id="my_sia", name="my_sia_main")Sans flow.name
Le backend filtre le span de l'agrégation : ses enfants deviennent orphelins → cascade illisible dans le Flow Diagram. C'est le check critique flow_name_present.
flow.phase — recommandé
Une des valeurs canoniques. Le Flow Diagram colore les step cards par phase.
| phase | quand |
|---|---|
| PREPROCESS | Préparation des inputs, snapshot d'état, validation |
| ROUTING | Décision de chemin (quel modèle, quel tool) |
| RETRIEVAL | Recherche de contexte (RAG) |
| ANALYSIS | Le cœur du traitement (appel LLM, raisonnement) |
| FINALIZE | Post-traitement, sauvegarde, snapshot final |
| POSTPROCESS | Sidecars : audit, alerting, notification |
flow.step — recommandé
Slug court identifiant l'étape précise (snapshot, decision, llm_response…). Affiché comme
titre de la step card.
Cohérence du flow.name
Un même flow_definition_id doit toujours porter le même flow.name. Si plusieurs services
émettent vers le même SIA, centralisez la constante.
# config.pyFLOW_DEFINITION_ID = "my_sia"FLOW_NAME = "my_sia_main"# service_a.pyfrom .config import FLOW_DEFINITION_ID, FLOW_NAMEflow = start_flow(client, flow_definition_id=FLOW_DEFINITION_ID, name=FLOW_NAME)asset.name — recommandé
Le nom de l'asset invoqué (modèle, tool, API…). Affiché comme label sur les chips des step cards. Sans lui, les chips apparaissent anonymes.
Branches — étapes mutuellement exclusives
Quand un step représente une alternative XOR (le décideur a choisi A vs B), exposez branch : le
Flow Diagram dessinera deux step cards alternatives.
from niaone_sdk.models import Branchstep = start_step(flow, asset=router_asset, flow=Flow(name="my_sia_main", phase=FlowPhase.ROUTING, step="decision", branch=Branch(group="decision_outcome", label="positive", guard="score > 0.5")))