Phase 14: Agent Engineering

Ports de vérification

L'agent ne peut pas marquer son propre travail comme fait. Une passerelle de vérification lit le contrat de portée, le journal de rétroaction, le rapport de règles et le diff, et répond à une seule question: cette tâche est-elle réellement terminée?

Type: Build

Languages: Python (stdlib)

Prerequisites: Phase 14 · 33 (Rules), Phase 14 · 36 (Scope), Phase 14 · 37 (Feedback)

Time: ~55 minutes

Objectifs d'apprentissage

  • Définir une passerelle de vérification comme une fonction déterministe sur les artefacts de bureau.
  • Combinez le rapport de règles, le rapport de portée, les dossiers de rétroaction et la différence en un seul verdict.
  • Émettez un verification_report.jsonL'agent de l'examen et l'informateur peuvent lire.
  • Refuser de faire avancer une tâche sur toute défaillance de gravité de bloc, sans exception.

Le problème

Les agents déclarent trop facilement le succès.

  • " Ça a l'air bien. " Le modèle a lu sa propre différence et a décidé qu'elle était correcte.
  • "Les tests ont passé". Il a dit en toute confiance.
  • "Acceptation satisfaite". Les critères d'acceptation sont interprétés assez lourdement pour signifier "tout ce qui ressemble à ce qui a été fait".

La solution de la table de travail est une seule passerelle de vérification qui lit les objets que l'agent a déjà produits et fait l'appel. La passerelle est déterministe. La passerelle est en contrôle de version. La passerelle est câblée dans CI. L'agent ne peut pas la corrompre.

Le concept

flowchart TD
  Diff[Diff] --> Gate[verify_agent.py]
  Scope[scope_report.json] --> Gate
  Rules[rule_report.json] --> Gate
  Feedback[feedback_record.jsonl] --> Gate
  Gate --> Verdict[verification_report.json]
  Verdict --> Pass{passed?}
  Pass -- yes --> Review[Reviewer Agent]
  Pass -- no --> Refuse[refuse done + surface to human]

Ce que vérifie la porte

CheckSource artifactSeverity
All acceptance commands ranfeedback_record.jsonlblock
All acceptance commands exited zerofeedback_record.jsonlblock
Scope check has no forbidden writesscope_report.jsonblock
Scope check has no off-scope writesscope_report.jsonblock or warn
All block-severity rules passrule_report.jsonblock
No null exit codes in feedbackfeedback_record.jsonlblock
Touched files match scope.allowed_filesbothwarn

Une .warnla conclusion annotera le verdict; a blocktrouver des obstacles passed: true- Je suis désolé .

Déterministique, non probabiliste

La porte doit produire le même verdict pour le même artefact mis à jour à chaque fois. Aucun juge LLM. Les juges LLM appartiennent au côté de l'examen (phase 14 · 39) où l'objectif est une évaluation qualitative, pas le statut.

Un rapport, un chemin

La porte en émet une .verification_report.jsonpar tâche, écrit sous outputs/verification/<task_id>.jsonLa CI consomme le même chemin, plusieurs portes avec des chemins différents forge la source de la vérité.

Renier sans exception

Les résultats de la gravité des blocs ne peuvent être annulés par l'agent.override_reasonet une overridden_byL'annulation est un changement signé, pas une décision de l'agent.

Faites-le

code/main.pyles implémentations:

  • Un chargement pour chaque produit, tous enduits localement pour que la leçon soit autonome.
  • Une .verify(task_id, artifacts) -> VerdictReportfonction pure.
  • Une imprimante qui affiche les résultats par vérification et le résultat final.
  • Une démo avec trois scénarios de tâches: passer clair, creep scope, absence d'acceptation.
  • Je vais le faire.
python3 code/main.py

Résultat: trois rapports de verdict, chacun enregistré à côté du script.

Modèles de production dans la nature

Quatre modèles élèvent la porte d'un "autre travail de laine" à "le bord décisif".

Defense-in-depth, not single gate.Chaque couche est déterministe, de sorte qu'une défaillance dans une couche est prise par la suivante. Le manuel de jeu de mars 2026 de microservices.io est explicite: le crochet pré-commit est non-passageable parce que, contrairement à une compétence côté modèle, il ne dépend pas de l'agent suivant les instructions.

Defense by deterministic check, model-judge only for nuance.L'appariement de la norme hybride 2026 d'Anthropic: récompenses vérifiables (tests d'unités, vérifications de schéma, codes de sortie) répondent " le code a-t-il résolu le problème ? " Les rubriques du LLM répondent " le code est-il lisible, sécurisé, en style ? " La passerelle exécute la première classe; le réviseur (phase 14 · 39) exécute la seconde. Le mélange des deux effondre le signal.

Signed override log, not Slack threads.Chaque dépassement émet une ligne dans outputs/verification/overrides.jsonlavec: timestamp, code de recherche, raison, utilisateur signé, engagement HEAD actuel. Le temps d'exécution refuse toute annulation qui manque de signature; la piste d'audit est git-tracked. C'est la ligne entre une politique d'annulation et un théâtre d'annulation.

Coverage floor as a first-class check.Une .coverage_report.jsonIl est alimenté par uncoverage_floor(par défaut 80%) vérification. La passerelle échoue si la couverture mesurée tombe en dessous du sol ou en dessous du sol de la fusion précédente de plus de 1 point de pourcentage.

--strict mode promotes warns to blocks.Pour les branches de libération, les relations publiques de blocage des navires ou le tri après incident, --strictLe drapeau est opt-in par branche, pas le défaut mondial, parce que strict-on-tout corrodant le flux quotidien.

Utilisez-le

Modèles de production:

  • CI step.Une .verify_agentLe travail de l'agent s'enfuit contre les objets finaux.passed: true- Je suis désolé .
  • Pre-handoff hook.L'agent appelle la porte avant de générer le document.
  • Manual triage.Les opérateurs lisent le rapport quand un agent prétend réussir et un humain le soupçonne.

La porte est le bord décisif du flux de la table de travail.

La faire partir

outputs/skill-verification-gate.mdles câbles de la passerelle dans un projet spécifique: quelles commandes d'acceptation le nourrissent, quelles règles sont sévères, quelles écritures hors champ sont tolérées, comment le journal d'audit de suppression est stocké.

Exercices

  1. Ajouter un coverage_floorvérification: la commande d'essai doit produire un rapport de couverture d'au moins 80%. Détermine quel artefact porte le sol.
  2. Soutenir un--strictmode qui favorise chaque warnà block- documenter les cas où le mode strict est le bon par défaut.
  3. Faites en sorte que la passerelle produise un résumé Markdown en plus de JSON. Défendre quels champs appartiennent au résumé.
  4. Ajouter un time_since_last_human_touchvérification: tout fichier modifié dans les 60 secondes suivant une pression de touche humaine est exempté de drapeaux hors champ d'application.
  5. Il faut utiliser un agent réel différent de votre produit.

Les termes clés

TermWhat people sayWhat it actually means
Verification gate"The check that stops things"Deterministic function over workbench artifacts producing a pass/fail verdict
Block severity"Hard fail"A finding that prevents passed: true and requires a signed override
Override log"Why we let it through"Signed entries with reason and user id, audited by review
Acceptance command"The proof"A shell command whose zero exit is what done means
One report path"Source of truth"outputs/verification/<task_id>.json, consumed by CI and humans alike

Pour en savoir plus

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.