Aller au contenu
English

Enregistrer les décisions, les approbations et les changements

  • Leçon 20
  • 40 min
  • Module 6 : Pistes d'audit

Où nous en sommes

Dans la dernière leçon, nous avons vu qu'une piste d'audit n'est pas un journal. Elle est complète, conservée pendant des années et lue par d'autres personnes. Mais notre flux de travail n'écrit encore aucun enregistrement d'audit. Nous n'avons pas non plus précisé ce qu'un enregistrement doit contenir. Dans cette leçon, nous fixons les champs d'un événement d'audit et lions chaque événement à sa trace. Nous excluons le texte et les secrets. Nous faisons aussi écrire un événement pour chaque décision et chaque changement. Commençons au comptoir d'une pharmacie.

Leçon 20 sur 28 · Observabilité des agents d'IA : traces, coûts et pistes d'auditEnregistrer les décisions, les approbations et les changements
Aperçu du cours

Ce que vous saurez faire

Donnez à chaque événement d’audit les mêmes champs fixes : qui, quoi, quand, selon quelle autorité, avec quelles preuves et où chercher dans les traces. Faites écrire un événement pour chaque proposition, approbation, refus, écriture, accès aux données, passage de relais et clôture. Excluez le texte et les secrets.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 40 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Le projet dans l’état laissé par la dernière leçon : 97 tests réussissent, et show_spans.py (du module 3) est dans le dossier du projet.
  • Un terminal dans observable-workflow, avec l’environnement virtuel actif.

Testé sur macOS (Apple silicon) avec Python 3.12.13. Les commandes Windows et Linux sont écrites, mais n’ont pas été exécutées.

Certains médicaments sont contrôlés : une pharmacie doit enregistrer chaque médicament qu’elle remet. Elle tient un registre avec des colonnes imprimées. Chaque ligne contient la date, le numéro du patient, le médicament et la quantité. Elle indique aussi le médecin qui l’a prescrit et le pharmacien qui l’a vérifié.

Il n’y a pas de colonne « comment le patient semblait aller ». C’est voulu. Chaque ligne peut être vérifiée à partir d’une ordonnance, et un inspecteur peut compter les lignes. Une ligne sans le nom du médecin est inutile. Une longue note dans la marge présente un risque : elle est privée, et personne ne peut la vérifier.

Le registre fonctionne parce que ses colonnes sont fixes. Chaque pharmacien écrit les mêmes faits aux mêmes endroits.

Le problème : « enregistrer simplement la requête et la réponse »

Section intitulée « Le problème : « enregistrer simplement la requête et la réponse » »

Tomás a un plan simple : « Nous enregistrons chaque requête et chaque réponse comme enregistrement d’audit. Ensuite, nous pouvons tout expliquer. » Regardez ce que cet enregistrement contiendrait pour le double remboursement. La proposition de l’agent pour T-90104 s’explique dans un paragraphe :

Why: The order is 12 business days late, with a $9.95 shipping fee and no prior refunds. W2 allows a
shipping-fee refund for approval by any agent; W3's lost-delivery threshold has not been reached.

Et le brouillon de réponse parle à la cliente de son arrosoir et de ses dates. Utiliser ce texte comme enregistrement d’audit cause trois problèmes :

  • Les faits sont cachés dans les phrases. « Qui a approuvé, avec quelle limite? » ne correspond à aucun champ. Personne ne peut compter les approbations par rôle, ni vérifier que chaque écriture en avait une.
  • Le texte contient les mots du modèle, pas un fait. Le « pourquoi » peut être faux. Un enregistrement d’audit doit dire ce qui s’est passé, pas ce qu’un modèle a écrit à ce sujet.
  • Le texte contient des données personnelles, pendant 7 ans. Une piste qui conserve les mots de la cliente doit être protégée et supprimée comme ses données. Elle n’est alors plus un historique sûr et durable.

Et chaque développeur écrirait un message différent. Dans un an, personne ne saura quels messages représentent une approbation.

La solution est celle de la pharmacie : des colonnes fixes. Un schéma est une liste fixe de champs, chacun ayant un seul sens, que chaque enregistrement doit contenir. Un programme vérifie chaque enregistrement selon ce schéma avant de le stocker.

Le schéma du projet est larkfield.audit/1, dans auditstore/schema.py. Chaque événement d’audit a les mêmes 13 champs de premier niveau et l’un des 7 types suivants :

Type Qui agit À quelle question il répond
data_access l’agent d’IA quelles données de la clientèle l’agent a-t-il lues?
proposal l’agent d’IA qu’a proposé l’agent, selon quelle règle et à partir de quelles preuves?
approval une personne qui l’a autorisé, avec quel rôle et quelle limite, après combien de temps?
refusal une personne, ou les règles qui a dit non, ou qui a tenté d’approuver sans en avoir l’autorisation?
write le flux de travail quel changement a été envoyé, à quelle tentative, avec quelle clé, quel résultat et l’approbation de qui?
handoff l’agent d’IA quand le billet de soutien est-il passé à une personne, et pourquoi (un code)?
run_closed le flux de travail comment le billet s’est-il terminé?

L’acteur est celui qui a agi. Il a un type, person (personne), agent ou system (système), et un identifiant. Une personne est désignée par un identifiant de membre du personnel comme usr-sam, jamais par un nom. Les noms sont dans data/people.json, que la dernière leçon de ce module utilise pour son récit.

Exemple détaillé : l’approbation de Sam, champ par champ

Section intitulée « Exemple détaillé : l’approbation de Sam, champ par champ »

Affichez l’enregistrement 671 de la semaine rejouée au complet :

Fenêtre de terminal
sed -n 671p data/telemetry/week/audit.jsonl | python -m json.tool
{
"event": {
"action": {
"decision": "approved",
"proposal_digest": "f28887b94cb6",
"proposal_event_id": "2f48cd67-4d3a-428e-b4f2-b9ed3f266100",
"wait_s": 55505.4
},
"actor": {
"id": "usr-sam",
"kind": "person",
"role": "agent"
},
"at": "2026-10-15T13:17:12+00:00",
"authority": {
"limit": 100.0,
"needs_role": "agent",
"role": "agent",
"rule": "refund approval limits"
},
"event_id": "b5188674-35aa-4e51-b9f5-71e2d624d19f",
"evidence": [],
"run_id": "R-1014-040",
"schema": "larkfield.audit/1",
"span_id": "cc0db5a2598f6be9",
"subject": {
"customer": "cust:6899a74add4687df"
},
"ticket_id": "T-90104",
"trace_id": "15ba0d9388d1b9e001af373f21c4b955",
"type": "approval"
},
"hash": "ac63a5ff0037f764c1686e17c8916cfdb860973a0c72cac21756ddf8ebe3a171",
"prev": "8dd09d48a0736258704950715fb90485225a3604ec76a3713c8114b2c52e6b77",
"seq": 671
}

Le même enregistrement, regroupé selon la question à laquelle chaque champ répond :

Enregistrement 671 de la semaine rejouée, regroupé par question. Qui : acteur, type personne, identifiant usr-sam, rôle agent. Quand : à 2026-10-15T13:17:12+00:00, en UTC. Quoi : type approval; action avec décision approved, wait_s 55505.4, proposal_event_id 2f48cd67 et proposal_digest f28887b94cb6. Selon quelle autorité : rôle agent, limite 100.0, needs_role agent, règle des limites d'approbation des remboursements. Avec quelles preuves : une liste vide; la proposition les contient. À propos de qui : sujet customer cust:6899a74add4687df, un pseudonyme. Où chercher ensuite : run_id R-1014-040, ticket_id T-90104, trace_id 15ba0d93 et span_id cc0db5a2598f6be9. Le stockage ajoute : seq 671, prev 8dd09d48 et hash ac63a5ff.
Un événement d'audit, l'approbation du double remboursement par Sam (enregistrement 671 de la semaine rejouée), avec ses champs regroupés selon leur question.
Description textuelle du diagramme

Chaque groupe de champs répond à une question. L’acteur indique qui : une personne, usr-sam, avec le rôle agent. L’heure indique quand, en UTC. Le type et l’action indiquent quoi : approuvé, après 55 505 secondes, pour la proposition portant cet identifiant d’événement et cette empreinte. L’autorité indique selon quelle autorité : le rôle agent, sa limite de 100 et la règle. Les preuves sont absentes d’une approbation, parce que la proposition les contient. Le sujet est un pseudonyme. Les identifiants d’exécution, de billet, de trace et de span indiquent où chercher ensuite. Le stockage ajoute le numéro de séquence et deux empreintes de hachage, pour la prochaine leçon.

Certains champs méritent quelques mots de plus :

  • authority contient ce qui autorisait la décision : le rôle de Sam, sa limite, le rôle requis et le nom de la règle. Un auditeur peut vérifier 9,95 ≤ 100 à partir de ce seul enregistrement.
  • proposal_digest est une empreinte de la proposition que Sam a vue, provenant du cours sur les agents. Si la proposition change après l’approbation, le flux de travail refuse d’écrire.
  • proposal_event_id désigne l’événement d’audit de la proposition. L’approbation pointe donc vers la proposition, et chaque écriture pointe vers l’approbation, avec approval_event_id.
  • trace_id et span_id désignent le span (intervalle d’une opération) ouvert au moment où l’événement a été écrit. Pour une approbation, c’est le span approve support-resolution (approuver la résolution du soutien) dans la trace 2. C’est le lien vers les détails, tant que la trace existe.

Voici les six enregistrements de l’exécution et leurs liens :

Les six enregistrements d'audit de l'exécution R-1014-040, avec les 59 enregistrements d'autres exécutions entre 611 et 671. 610 data_access par l'agent : lecture get_order LK-793996, ok; trace 1, span 8027f3b3. 611 proposal par l'agent : remboursement 9,95 RFD-LATE, règle W2, rôle agent requis; trace 1, span 508ef7aa. 671 approval par la personne usr-sam : approuvé, rôle agent, limite 100; son proposal_event_id pointe vers l'enregistrement 611; trace 2, span cc0db5a2. 672 write par le flux de travail : remboursement 9,95, tentative 1, clé se terminant par 5bbb9f8a7e, délai dépassé; son approval_event_id pointe vers l'enregistrement 671; trace 2, span c4e1313c. 673 write : tentative 2, clé se terminant par a7e-retry1, terminé; pointe aussi vers l'enregistrement 671; trace 2, span c3295385. 674 run_closed : résolu, writes_done 1, réponse envoyée; trace 2, span cc0db5a2.
L'exécution R-1014-040 dans la piste d'audit : chaque écriture désigne l'approbation qui l'a autorisée, l'approbation désigne la proposition, et chaque enregistrement désigne son span dans les traces.
Description textuelle du diagramme

Six enregistrements, de la lecture de la commande à la clôture. L’approbation pointe vers la proposition avec proposal_event_id. Les deux écritures pointent vers la même approbation avec approval_event_id : une approbation a autorisé deux appels. Chaque enregistrement désigne aussi une trace et un span. Le lecteur peut donc ouvrir les détails tant que les traces existent.

Relisez les deux écritures. Toutes deux désignent l’enregistrement 671. Une approbation d’un remboursement a mené à deux appels avec deux clés. La piste ne le cache pas : un auditeur le découvre en suivant les liens.

Le schéma refuse deux choses, dans _walk() :

  • Les champs contenant du texte : text, reply, reason, message, prompt, answer, note, body, content et goal.
  • Toute chaîne de plus de 80 caractères. Les identifiants, codes et noms d’outils et de règles sont courts. Une phrase est généralement plus longue.

La requête, la réponse, le brouillon de réponse et le « pourquoi » du modèle n’entrent donc jamais dans la piste. Le nom de la règle, W2, y entre. Les secrets restent aussi exclus : aucune clé d’API et aucun jeton ne constituent un champ. Et la cliente est un pseudonyme, cust:6899a74a…, créé par le stockage à partir de son identifiant. La prochaine leçon montre comment, et pourquoi cela facilite une demande de suppression.

Le projet exclut aussi la note d’approbation du cours sur les agents. Quand Sam saisit --note, la note reste dans l’état sauvegardé de l’exécution, pas dans la piste.

Ajouter des événements d’audit à votre flux de travail

Section intitulée « Ajouter des événements d’audit à votre flux de travail »

Le flux de travail écrit chaque événement d’audit avec une fonction, observe.audit(). Elle remplit les champs communs à chaque événement : l’heure de l’horloge d’exécution, les identifiants d’exécution et de billet, et la cliente. Elle ajoute aussi les identifiants de trace et de span du span ouvert. Le code appelant fournit le reste.

Événement Où le flux de travail l’écrit
data_access observe.py, après un span d’outil de get_order, get_customer_orders ou get_payments
proposal observe.py, à la fin du span d’exécution
approval, refusal live.py, dans _decide(), à l’intérieur du span approve
write observe.py, dans write_done(), une fois par appel
handoff, run_closed live.py, dans close()

audit() envoie l’événement comme événement OpenTelemetry nommé larkfield.audit.<type>, avec l’enregistrement comme corps. Ensuite, une nouvelle classe dans telemetry.py, AuditRouter, prend chaque événement portant ce nom. Elle l’ajoute au stockage d’audit, work/audit/audit.jsonl. Elle n’échantillonne jamais et lève une erreur si le stockage refuse un événement.

  1. Copiez les trois fichiers modifiés du flux de travail et les deux tests :

    Fenêtre de terminal
    S=../nextia-learning-labs/C31/snapshots/end-of-m06
    cp $S/resolver/observe.py $S/resolver/live.py $S/resolver/telemetry.py resolver/
    cp $S/tests/test_approval_traces.py $S/tests/test_audit.py tests/
  2. Ouvrez resolver/observe.py et trouvez def audit(. Lisez comment la fonction remplit trace_id et span_id. Trouvez ensuite les appels à audit( dans observe.py et live.py, puis associez-les au tableau ci-dessus.

  3. Exécutez les tests : python -m pytest -q. La dernière ligne indique 103 passed, 1 skipped, 1 deselected (103 réussis, 1 ignoré, 1 désélectionné). Les nouveaux tests vérifient la chaîne, l’ancrage, le refus du texte, une demande de suppression et une approbation refusée. Ils vérifient aussi que les événements d’audit ne sont jamais échantillonnés.

  4. Supprimez work/. Exécutez ensuite un billet : python -m resolver run T-80008. Il se termine par Reply sent. Ticket: resolved. (réponse envoyée, billet résolu).

  5. Affichez votre piste :

    Fenêtre de terminal
    python -m obs audit show
    1 … data_access agent:support-workflow/agent {"orders": ["LK-581106"], "status": "ok", "tool": "get_order"}
    2 … proposal agent:support-workflow/agent {"actions": [], "design": "agent", "outcome": "reply_only", "rule": "W1"}
    3 … run_closed system:support-workflow/executor {"helpdesk_status": "resolved", "outcome": "resolved", "reply_status": "sent", "writes_done": 0}

    Les heures sont les vôtres, en UTC.

  6. Vérifiez-la : python -m obs audit verify. Le résultat indique The audit trail is intact: 3 records, the chain and the anchor match (head …) (la piste d’audit est intacte : 3 enregistrements, la chaîne et l’ancrage concordent). Votre empreinte de tête diffère.

Trois enregistrements pour une réponse sans changement : la lecture, la décision, la clôture.

Exercice guidé : le double remboursement dans votre propre piste

Section intitulée « Exercice guidé : le double remboursement dans votre propre piste »
  1. Supprimez work/ pour que les numéros d’enregistrement correspondent à ceux ci-dessous.

  2. Rejouez le double remboursement, comme au module 3 :

    Fenêtre de terminal
    python -m resolver run T-90104 --variant agent_structured --model chat-strong
    python -m resolver approve T-90104-agent_structured-chat-strong-1 --as agent --fault request_refund:timeout_after_write --naive-retry

    L’approbation se termine par Reply sent. Ticket: resolved.

  3. Affichez la piste du billet : python -m obs audit show T-90104.

    1 … data_access agent:support-workflow/agent_structured {"orders": ["LK-793996"], "status": "ok", "tool": "get_order"}
    2 … proposal agent:support-workflow/agent_structured {"actions": [{"amount": 9.95, "order_id": "LK-793996", "reason_code": "RFD-LATE", "tool": "request_refund"}], "design": "agent_structured", "outcome": "resolve", "rule": "W2"}
    3 … approval person:usr-sam/agent {"decision": "approved", "proposal_digest": "f28887b94cb6", "proposal_event_id": "55f75b4b-88f5-4ef7-9aee-925ddaf85bd0", "wait_s": 0.0}
    4 … write system:support-workflow/executor {"attempt": 1, "effect": {"amount": 9.95, "order_id": "LK-793996", "reason_code": "RFD-LATE", "tool": "request_refund"}, "idempotency_key": "797fbb5bbb9f8a7e", "operation_id": "797fbb5bbb9f8a7e", "outcome": "timeout", "tool": "request_refund"}
    5 … write system:support-workflow/executor {"attempt": 2, "effect": {"amount": 9.95, "order_id": "LK-793996", "reason_code": "RFD-LATE", "tool": "request_refund"}, "idempotency_key": "797fbb5bbb9f8a7e-retry1", "operation_id": "797fbb5bbb9f8a7e", "outcome": "done", "tool": "request_refund"}
    6 … run_closed system:support-workflow/executor {"helpdesk_status": "resolved", "outcome": "resolved", "reply_status": "sent", "writes_done": 1}

    Ce sont les mêmes six enregistrements que R-1014-040 dans la semaine. L’empreinte de la proposition, f28887b94cb6, est aussi la même : c’est la même proposition. Les identifiants d’événement sont nouveaux.

  4. Trouvez le span de l’approbation dans les traces. Affichez le span approve (approuver), puis le span_id de l’approbation :

    Fenêtre de terminal
    python show_spans.py approve | head -1
    grep '"type":"approval"' work/audit/audit.jsonl | grep -o '"span_id":"[^"]*"'
    approve support-resolution trace 826f3506 span c07282c8 parent none
    "span_id":"c07282c8e932199d"

    L’identifiant de span commence de la même façon : c07282c8. Vos identifiants diffèrent, mais ils doivent correspondre entre eux.

  5. Faites de même pour les écritures : python show_spans.py request_refund, et "type":"write" dans le grep. L’exécution de l’équipe du cours a donné les spans a52157aa et 32df5564. Les deux enregistrements d’écriture désignaient ces mêmes spans.

Chaque enregistrement d’écriture mène à son propre span : celui avec ERROR timeout (erreur de délai dépassé), et celui avec la nouvelle clé.

Un test prouve la première règle. Exécutez-le seul :

Fenêtre de terminal
python -m pytest -q tests/test_audit.py -k sampled -v
======================= 1 passed, 4 deselected in 0.35s ========================

Ouvrez tests/test_audit.py et lisez test_audit_events_are_never_sampled. Il règle l’échantillonneur de traces sur ALWAYS_OFF, donc aucune trace n’est conservée. Ensuite, il exécute un billet. Le fichier de traces n’existe pas, mais le stockage d’audit contient quand même l’accès aux données et la proposition. L’échantillonnage décide du sort des spans, et les événements d’audit ne sont pas des spans.

La semaine rejouée contient 1331 enregistrements d’audit pour 316 exécutions. Les voici par type :

Les 1 331 enregistrements d'audit de la semaine rejouée (316 exécutions), par type, provenant de data/telemetry/week/audit.jsonl. Décisions rejouées, trafic simulé.
Description textuelle du graphique

Sept types. Accès aux données : 347. Clôture : 316, une par exécution. Proposition : 300. Écriture : 156. Approbation : 118. Passage de relais : 94. Refus : 0.

Chaque exécution a un enregistrement de clôture. Seules 300 exécutions sur 316 ont une proposition. Les 16 autres se sont arrêtées avant de pouvoir proposer. Le fournisseur du modèle a refusé 3 appels (le filtre de contenu de T-80002). Les limites de la boucle ont arrêté le modèle local 13 fois : 10 pour trop d’erreurs, 3 pour un appel répété. Chacune a un enregistrement de passage de relais avec le code d’arrêt. Parmi les 156 écritures, 140 sont done (terminées). Les autres sont 10 délais dépassés, 4 appels à un service indisponible et 2 réexpéditions refusées par le service des commandes. Aucune approbation n’a été refusée dans la semaine : personne n’a tenté d’approuver au-delà de sa limite. Votre prochaine tâche en crée une.

Changez une condition : la limite de la personne qui approuve. T-65273 propose un remboursement de 119,00, et un agent peut approuver jusqu’à 100. Faites une prédiction avant l’exécution : quels enregistrements la piste reçoit-elle, et lequel manque?

Fenêtre de terminal
python -m resolver run T-65273
python -m resolver approve T-65273-agent-chat-small-1 --as agent
python -m obs audit show T-65273
Le résultat de l’équipe du cours
Not approved: An agent may not approve this: it needs a team lead (refund approval limits).
7 … data_access agent:support-workflow/agent {"orders": ["LK-507862"], "status": "ok", "tool": "get_order"}
8 … data_access agent:support-workflow/agent {"orders": ["LK-507862"], "status": "ok", "tool": "get_payments"}
9 … proposal agent:support-workflow/agent {"actions": [{"amount": 119.0, "order_id": "LK-507862", "payment_id": "PAY-507862-2", "reason_code": "RFD-DOUBLE", "tool": "request_refund"}], "design": "agent", "outcome": "resolve", "rule": "W7"}
10 … refusal person:usr-sam/agent {"code": "role_below_limit", "decision": "refused_by_rules", "proposal_event_id": "d2d50c4b-ef6c-4b49-b4df-75b275e60d7d"}

Deux lectures cette fois : l’agent a lu la commande et les paiements. Le refus correspond à la tentative de Sam, refusée par les règles : role_below_limit (limite du rôle insuffisante). Affichez l’enregistrement 10 au complet (sed -n 10p work/audit/audit.jsonl | python -m json.tool). Son autorité indique "role": "agent", "limit": 100.0 et "needs_role": "team_lead" (rôle de chef d’équipe requis). Il n’y a ni écriture ni clôture : l’exécution attend encore un chef d’équipe. Un auditeur peut voir que les limites ont fonctionné, et qui a tenté d’approuver.

Erreur courante

Une développeuse met la note d'approbation dans l'événement

Symptôme : Amira veut que la piste conserve la note de Sam. Elle ajoute "note": note à l’action de l’approbation dans live.py, ligne 173. L’approbation de T-90104 échoue alors :

exit status 1
File "…/observable-workflow/auditstore/schema.py", line 31, in _walk
raise AuditEventError(f"{path}.{k}: text fields are not allowed in an audit event")
auditstore.schema.AuditEventError: event.action.note: text fields are not allowed in an audit event

python -m resolver changes indique 0 change(s) in the practice database (0 changement dans la base de données d’exercice). La piste ne contient que la lecture et la proposition. L’équipe du cours a fait ce changement volontairement, puis l’a annulé.

Cause : le schéma refuse le champ note. En mode fichier, AuditRouter ajoute chaque événement immédiatement et laisse l’erreur arrêter le processus. L’événement d’approbation précède les écritures, donc le remboursement n’est jamais envoyé.

Diagnostic : la dernière ligne désigne le champ : event.action.note. Cherchez dans le code l’appel à audit( qui le définit.

Rétablissement : excluez le texte de l’événement. Si la raison compte, enregistrez un code d’une liste fixe, comme "code": "customer_called" (la cliente a appelé). Gardez la note là où les données personnelles sont traitées, avec sa propre durée de conservation. L’arrêt est ici le bon comportement : un remboursement sans enregistrement d’approbation serait pire qu’aucun remboursement.

Le schéma est un filet, pas une preuve. Créez try_text.py dans le dossier du projet. Il vérifie trois événements d’approbation contenant du texte :

"""Three approval events with text in them: which ones does the schema refuse?"""
from auditstore.schema import AuditEventError, check
tries = {
"a note field": {"decision": "approved", "note": "Customer was upset, refund ok"},
"a long code": {"decision": "approved",
"code": "Approved by Sam because the customer phoned twice and was very upset about the delay"},
"a short code": {"decision": "approved", "code": "customer phoned twice, upset"},
}
for name, action in tries.items():
event = {"schema": "larkfield.audit/1", "event_id": "e1", "type": "approval", "at": "2026-10-15T13:17:12+00:00",
"actor": {"kind": "person", "id": "usr-sam", "role": "agent"}, "run_id": "R-1014-040",
"ticket_id": "T-90104", "trace_id": "", "span_id": "", "subject": {"order_id": "LK-793996"},
"action": action, "authority": {}, "evidence": []}
try:
check(event)
print(f"{name}: accepted")
except AuditEventError as e:
print(f"{name}: refused: {e}")

Exécutez-le avec python try_text.py :

a note field: refused: event.action.note: text fields are not allowed in an audit event
a long code: refused: event.action.code: a string of 84 characters looks like text, not an ID
a short code: accepted

Une courte phrase dans un champ au nom autorisé passe : customer phoned twice, upset (la cliente a appelé deux fois, contrariée). La vérification détecte donc les erreurs courantes, et une révision du code détecte le reste. Une liste de codes autorisés par champ en détecterait davantage, au prix de plus d’entretien.

Enregistrez un événement d’audit pour chaque décision et chaque changement que quelqu’un pourrait devoir expliquer. Cela comprend une proposition, une approbation ou un refus, une écriture, une lecture de données client, un passage de relais et la fermeture du billet. N’enregistrez pas chaque appel de modèle ni chaque nouvelle tentative de lecture : les traces les contiennent.

Le coût en temps est faible, mais l’entretien demande du travail. L’équipe du cours a mesuré 2,1 événements d’audit par exécution limitée aux propositions, soit environ 1,5 Ko. Chaque événement était écrit et synchronisé sur disque séparément. Avec toute la télémétrie activée, le code du flux de travail prenait 1,9 ms de plus par exécution. Le modèle, lui, prenait plusieurs secondes. L’entretien concerne le schéma : quand le flux de travail ajoute un nouveau type de décision, modifiez d’abord le schéma et ses tests.

Écrivez chaque événement là où la décision se prend, dans le span (segment de trace) correspondant. Ainsi, trace_id et span_id sont corrects sans travail supplémentaire.

Vérifiez votre compréhension

Tomás veut enregistrer chaque requête et chaque réponse comme enregistrement d'audit. Donnez deux raisons de ne pas le faire. Dites ce que le projet enregistre plutôt pour la proposition de T-90104.

Afficher la réponse

Les faits sont cachés dans des phrases : personne ne peut compter les approbations par rôle ni vérifier que chaque écriture en avait une. Le texte contient les mots du modèle, qui peuvent être faux, et non les faits de ce qui s’est passé. Il contient aussi des données personnelles qui seraient conservées pendant 7 ans. À la place, la proposition forme un seul événement avec des champs fixes. L’acteur est l’agent, avec sa conception et son modèle. L’action indique le résultat resolve, la règle W2 et un remboursement de 9,95 RFD-LATE sur LK-793996. L’autorité est needs_role agent, et la preuve est order:LK-793996. L’événement contient aussi les identifiants d’exécution, de billet, de trace et de span, ainsi qu’un pseudonyme pour le client.

Vérifiez votre compréhension

Prédisez : vous exécutez T-90103 avec --variant agent_structured --model chat-strong. Il propose une réexpédition et une étiquette de retour. Vous l'approuvez comme agent, sans défaillance. Quels enregistrements d'audit la piste reçoit-elle, et quelle approbation chaque écriture indique-t-elle?

Afficher la réponse

Six enregistrements. Un data_access pour get_order. Une proposition avec deux actions, reship_item et create_return_label. Une approbation par usr-sam avec le rôle agent. Deux enregistrements d’écriture, un par action, chacun avec attempt 1, sa propre clé et le résultat done. Un run_closed avec writes_done 2. Les deux écritures indiquent la même approbation dans authority.approval_event_id. L’approbation indique la proposition dans action.proposal_event_id.

Vérifiez votre compréhension

Exercice pratique : dans votre piste du double remboursement, montrez que l'enregistrement d'approbation et le span approve correspondent au même moment de la même exécution. Quels champs et quelles commandes le prouvent?

Afficher la réponse

L’enregistrement d’approbation contient span_id et trace_id. python show_spans.py approve affiche le span approve support-resolution avec ses identifiants. grep ‘“type”:“approval”’ work/audit/audit.jsonl montre le span_id de l’enregistrement. L’exécution de l’équipe du cours a donné le span c07282c8 dans les deux cas. Le run_id de l’enregistrement est identique au larkfield.run.id du span. Les enregistrements d’écriture indiquent les deux spans request_refund de la même façon.

Récapitulatif

  • Chaque événement d’audit contient les mêmes champs : qui, quoi, quand (UTC), sous quelle autorité et avec quelles preuves. Il indique aussi la personne concernée (un pseudonyme) et où chercher (identifiants d’exécution, de billet, de trace et de span).
  • Sept types : accès aux données, proposition, approbation, refus, écriture, passage de relais, fermeture. L’approbation indique la proposition; chaque écriture indique l’approbation.
  • Les champs de texte et les chaînes de plus de 80 caractères sont refusés. Cela détecte les erreurs courantes, mais pas toutes les phrases.
  • Les événements d’audit ne sont pas des spans : un échantillonneur ne peut pas les supprimer. En mode fichier, un événement refusé arrête l’exécution avant toute écriture.

Votre projet maintenant : les fichiers de la dernière leçon, plus les nouveaux observe.py, live.py, telemetry.py et deux tests. Les 103 tests réussissent. Votre flux de travail écrit une piste complète. Mais c’est un fichier texte brut : quiconque peut le modifier peut remplacer 9,95 par 0,95 sans que personne le sache. Ensuite, vous rendrez chaque changement visible et déciderez qui peut lire, écrire et supprimer.

Leçon suivante : La rendre inviolable et contrôlée