Registre

L'écran Registre vous permet de lister les agents du tenant, d'enregistrer un agent par manifeste, d'ouvrir un agent pour démarrer une exécution et lire ses exécutions, ses versions et son manifeste, puis de le suspendre, le reprendre, l'arrêter définitivement, le modifier ou le supprimer. Chemin dans le portail : /agents/registry (page de détail : /agents/registry/<agent-id>) ; le titre de la page est Registre des agents. Les développeurs et les responsables d'application enregistrent et modifient les agents, les administrateurs du tenant et les responsables sécurité pilotent leur cycle de vie. L'écran est dessiné par portal/src/screens/agents.tsx.

Ce que montre l'écran

La page de liste compte deux blocs :

Tableau Agents, lu par GET /v1/agents (50 lignes par appel, les lignes suivantes se chargent quand vous avancez de page). Colonnes : Nom, Version, Propriétaire, Risque, Statut, Mis à jour.
Filtre Statut (Actif, Suspendu, Arrêté, ou tous) et bouton Filtrer.
Sans agent : Aucun agent enregistré, avec l'aide Appliquez un manifeste Agent ci-dessous pour enregistrer un agent.
Un clic sur une ligne, ou le menu de ligne Voir le détail, ouvre la page de détail de l'agent.
Panneau Appliquer un manifeste : un éditeur prérempli avec un exemple de manifeste Agent (portal/src/samples/agent-manifest.json), les boutons Rétablir l'exemple et Appliquer, et une zone de résultat. Cette zone affiche Manifeste appliqué avec la réponse de l'API, la liste des erreurs de validation renvoyées par l'API, ou Impossible de lire le document quand le texte n'est ni du YAML ni du JSON.

La page de détail affiche :

Retour, le nom de l'agent, son badge de statut et sa version courante (fiche lue par GET /v1/agents/{agent_id}).
Les boutons Démarrer une exécution, Suspendre (ou Reprendre quand l'agent est suspendu) et Arrêter définitivement. Démarrer une exécution est désactivé quand l'agent est suspendu ou arrêté ; Suspendre et Arrêter définitivement sont désactivés quand il est arrêté.
Trois onglets :
- Exécutions : les exécutions de cet agent, mêmes colonnes et actions que l'écran Exécutions (GET /v1/runs avec agent=<agent-id>).
- Versions : colonnes Version, Statut, Créé par, Créé (GET /v1/agents/{agent_id}/versions) ; Aucune version enregistrée quand la liste est vide.
- Manifeste : le manifeste exporté de l'agent en JSON (GET /v1/manifests/{kind}/{name} avec le type Agent).

Actions

Bouton ou action	Ce qu'il fait	Appel d'API	Rôles
Actualiser (icône)	Recharge la liste.	`GET /v1/agents`	Tout membre du tenant
Filtrer	Applique le filtre Statut.	`GET /v1/agents` avec `status`	Tout membre du tenant
Clic sur une ligne ou menu Voir le détail	Ouvre la page de détail.	`GET /v1/agents/{agent_id}`	Relation `viewer` sur l'agent
Menu Suspendre (agent ni suspendu ni arrêté)	Suspend l'agent tout de suite : ses exécutions actives sont suspendues et les nouvelles sont refusées.	`POST /v1/agents/{agent_id}/suspend`	`tenant_admin`, `security_officer`
Menu Reprendre (agent suspendu)	Ouvre une approbation de promotion ; l'agent redevient actif, et les exécutions qu'il avait suspendues reprennent, seulement quand une autre personne l'approuve.	`POST /v1/agents/{agent_id}/resume`	`tenant_admin`, `security_officer`
Menu Modifier	Formulaire Description, Propriétaire, Risque (minimal, limited, high), Étiquettes (JSON), envoyé par Modifier.	`PATCH /v1/agents/{agent_id}`	`tenant_admin`, `developer`, `application_owner` et relation `editor`
Menu Supprimer	Ouvre Confirmer une action destructive (ressources dépendantes impactées, risques, permissions requises) ; saisissez le nom de l'agent, puis Confirmer.	`GET /v1/lineage/graph`, puis `DELETE /v1/agents/{agent_id}`	`tenant_admin` et relation `owner`
Rétablir l'exemple	Remet l'exemple de manifeste dans l'éditeur.	Aucun	Tout le monde
Appliquer	Valide le manifeste contre son contrat, le contrôle par la politique et l'enregistre dans le registre des agents.	`POST /v1/manifests/apply`	`tenant_admin`, `developer`
Retour (détail)	Revient à la liste.	Aucun	Tout le monde
Démarrer une exécution (détail)	Ouvre un panneau latéral : Objectif (obligatoire), Entrée (JSON), Identifiant de session, Coût max (EUR) ; le bouton Démarrer une exécution l'envoie avec une nouvelle `Idempotency-Key`. En cas de réussite, le message Exécution démarrée s'affiche et la page de l'exécution s'ouvre.	`POST /v1/agents/{agent_id}/runs`	`tenant_admin`, `developer`, `agent`, portée `agents:run` et relation `can_invoke`
Suspendre / Reprendre (détail)	Comme les actions de ligne.	`POST /v1/agents/{agent_id}/suspend` / `POST /v1/agents/{agent_id}/resume`	`tenant_admin`, `security_officer`
Arrêter définitivement (détail)	Demande Arrêter définitivement cet agent ? Les exécutions en cours sont stoppées et l'agent ne pourra pas être repris., puis annule toutes les exécutions actives et marque l'agent arrêté pour toujours.	`POST /v1/agents/{agent_id}/kill`	`tenant_admin`, `security_officer`
Onglets Exécutions, Versions, Manifeste	Affichent les exécutions, les versions et le manifeste exporté.	`GET /v1/runs`, `GET /v1/agents/{agent_id}/versions`, `GET /v1/manifests/{kind}/{name}`	Tout membre du tenant (relation `viewer` pour les versions)
Réessayer (état d'erreur)	Relance la lecture qui a échoué.	Même appel	Mêmes rôles

Le formulaire Démarrer une exécution envoie ce corps (construit par portal/src/lib/request-bodies.ts) ; session_id et budgets ne partent que s'ils sont remplis :

{
  "task": {"objective": "Check the supplier invoices received today", "input": {}},
  "session_id": "<session-id>",
  "budgets": {"max_cost": {"amount": "5.00", "currency": "EUR"}}
}

<session-id> : identifiant d'une session existante de l'écran Sessions.

attention

Arrêter définitivement est irréversible : l'agent reste arrêté, et toute action Reprendre, Suspendre ou Arrêter définitivement répond ensuite agent_killed. Utilisez Suspendre pour arrêter un agent pour un temps.

Rôles

Le portail ne masque aucun bouton sur cet écran : le Control Plane fait autorité et répond forbidden (403) avec les required_roles attendus. Les groupes de rôles viennent de services/control-plane/src/eai/domains/agents/kit.py :

WRITE_ROLES (tenant_admin, developer, application_owner) : modifier un agent.
OPS_ROLES (tenant_admin, developer, agent) : démarrer une exécution.
SECURITY_ROLES (tenant_admin, security_officer) : suspendre, reprendre et arrêter définitivement.
Suppression : tenant_admin seulement. Application d'un manifeste : tenant_admin ou developer (services/control-plane/src/eai/domains/contracts/__init__.py).

Les routes de services/control-plane/src/eai/domains/agents/routes.py contrôlent aussi une relation sur l'agent (viewer, editor, owner, can_invoke), voir Permissions (ReBAC). platform_admin passe tous les contrôles de rôle. Lire la liste demande seulement un tenant.

Tâches courantes

Enregistrer un agent à partir d'un manifeste

Préparer le manifeste. Le registre se remplit à partir d'un manifeste Agent, jamais d'un formulaire libre. Dans Appliquer un manifeste, collez votre manifeste en YAML ou en JSON, ou adaptez l'exemple (metadata.name, metadata.tenant, spec). Résultat attendu : l'éditeur contient votre document. En cas d'échec : cliquez sur Rétablir l'exemple pour repartir de l'exemple.
L'appliquer. Le Control Plane valide le contrat et la politique avant d'enregistrer l'agent. Cliquez sur Appliquer. Résultat attendu : Manifeste appliqué et la réponse de l'API ; après Actualiser, l'agent figure dans le tableau Agents. En cas d'échec : lisez les erreurs listées sous l'éditeur (invalid_manifest) et corrigez les champs qu'elles nomment.
Vérifier la version. Chaque version appliquée est conservée. Ouvrez l'agent, puis l'onglet Versions. Résultat attendu : la version de metadata.version est listée. En cas d'échec : version_immutable signifie que cette version existe déjà avec un autre contenu ; augmentez le numéro de version.

Démarrer une exécution et la suivre

Ouvrir l'agent. Une exécution part toujours d'un agent actif. Cliquez sur sa ligne dans le tableau. Résultat attendu : la page de détail avec le statut Actif. En cas d'échec : quand Démarrer une exécution est désactivé, l'agent est suspendu ou arrêté.
Remplir le formulaire. L'objectif décrit ce que l'agent doit faire. Cliquez sur Démarrer une exécution, saisissez l'Objectif, ajoutez une Entrée en JSON et un Coût max (EUR) si besoin, puis cliquez sur Démarrer une exécution. Résultat attendu : le message Exécution démarrée, puis la page de l'exécution s'ouvre. En cas d'échec : l'erreur s'affiche en haut du panneau (insufficient_scope, agent_not_active, forbidden).
Suivre l'exécution. La page de l'exécution se met à jour seule tant que l'exécution est active. Lisez sa chronologie sur l'écran Exécutions. Résultat attendu : l'état passe à Réussi ou Échoué. En cas d'échec : un état En attente d'approbation demande une décision dans la Boîte d'approbation.

Suspendre un agent, puis le remettre en service

Le suspendre. La suspension bloque les nouvelles exécutions et suspend tout de suite les exécutions actives. Cliquez sur Suspendre dans la page de détail ou dans le menu de ligne. Résultat attendu : le message Terminé et le statut Suspendu. En cas d'échec : forbidden signifie que vous n'êtes ni tenant_admin ni security_officer.
Demander la reprise. Le retour à l'état actif est une promotion qui demande une seconde personne. Cliquez sur Reprendre. Résultat attendu : le message Terminé ; l'agent reste Suspendu et une demande d'action promotion apparaît dans la Boîte d'approbation. En cas d'échec : kill_switch_active signifie qu'un kill switch du SOC retient l'agent ; levez-le par le circuit de reprise de l'écran Kill Switch.
La faire approuver. La séparation des tâches vous interdit d'approuver votre propre demande. Demandez à un autre approbateur de cliquer sur Approuver dans la boîte. Résultat attendu : l'agent redevient Actif et les exécutions qu'il avait suspendues reprennent. En cas d'échec : la promotion peut être refusée par le contrôle de risque ou par une suite d'évaluation bloquante, voir Portes qualité.

Dépannage

Symptôme	Cause	Correction
`forbidden` (403) avec `required_roles`	Vos rôles ne figurent pas dans les `required_roles` de l'erreur, ou la relation sur l'agent manque.	Demandez le rôle, ou la relation sur l'agent, à un administrateur du tenant.
`insufficient_scope` (403) sur Démarrer une exécution	L'identifiant de connexion n'a pas la portée `agents:run`.	Utilisez une clé ou une session qui porte `agents:run`.
`agent_not_active` (409) : « L'agent ... est suspended : les nouvelles exécutions sont bloquées. »	L'agent est suspendu ou arrêté.	Reprenez-le (approbation requise) ou utilisez un autre agent.
`agent_killed` (409)	L'agent a été arrêté définitivement ; il ne peut plus être modifié.	Enregistrez de nouveau l'agent sous un autre nom avec un manifeste.
`kill_switch_active` (409) sur Reprendre	Un kill switch de sécurité retient l'agent.	Demandez à l'équipe sécurité la reprise à quatre yeux (`POST /v1/soc/recoveries`).
`agent_has_active_runs` (409) sur Supprimer	L'agent a encore des exécutions actives.	Annulez-les ou attendez leur fin, puis supprimez.
`invalid_manifest` (422) sous l'éditeur	Le document ne respecte pas le contrat Agent.	Corrigez chaque champ listé dans les erreurs.
`tenant_mismatch` (403) sur Appliquer	`metadata.tenant` désigne un autre tenant.	Indiquez le slug de votre tenant ou retirez le champ.
Impossible de lire le document	Le texte n'est ni du YAML ni du JSON valide.	Corrigez la syntaxe (indentation, guillemets, virgules).
Reprendre affiche Terminé mais l'agent reste suspendu	La reprise est une promotion en attente d'approbation.	Faites approuver la demande dans la Boîte d'approbation.

Ce que montre l'écran​

Actions​

Rôles​

Tâches courantes​

Enregistrer un agent à partir d'un manifeste​

Démarrer une exécution et la suivre​

Suspendre un agent, puis le remettre en service​

Dépannage​

Pages liées​