Réviser un plan d’agent & écrire des règles Nexa

◆ Ingénieur IA

Après l’ouverture d’une session, l’agent génère un plan d’exécution révisable avant application. Le plan est une liste ordonnée d’étapes (steps), chacune modifiable, réordonnable ou supprimable.

Endpoints de l’agent

Endpoint	Rôle
POST /api/v1/agent/sessions	Crée une session (userRequest, projectId, scope).
POST .../sessions/{id}/plan	Génère un plan à partir de la demande et des règles Nexa.
PATCH .../plan/steps/{step_id}	Modifie un step existant.
POST .../plan/steps	Ajoute un step (avec position).
DELETE .../plan/steps/{step_id}	Supprime un step.
POST .../plan/steps/reorder	Réordonne les steps (drag-and-drop).
POST .../plan/regenerate	Régénère le plan avec feedback, steps conservés.
POST .../plan/validate	Valide la cohérence (warnings, errors, suggestions).

Structure d’un plan

Un plan contient une liste de steps ; chaque step porte un identifiant, un titre, une description, une position et un type d’action. La validation humaine du plan (gate Plan Approved) est obligatoire avant la génération de code et l’application.

Écrire une règle Nexa

Les règles Nexa orientent la génération de l’agent. Elles sont stockées en Markdown versionné dans docs/nexa_rules/, avec un frontmatter YAML (rule_id et métadonnées). L’agent les charge au moment de la génération du plan, ce qui rend son comportement gouvernable et auditable.

---
rule_id: "NXR-012"
scope: dashboard
severity: blocking
---
Toute requête SQL d'une subbox doit utiliser le placeholder <project_id>
et ne jamais contenir de point-virgule final.

Génération de code

À l’état Coded, l’agent produit des patches de code via l’API code_generator. Ces patches passent ensuite par la review automatique (linters, tests, règles Nexa) à l’état Reviewed, avant application (Applied : création du job + déclenchement de nexa__pipeline).