Applications gouvernées et agents tiers

Cette page explique comment la Plateforme enregistre une application (application d'agents, assistant, workflow ou agent tiers), ne déploie ses versions qu'après une approbation, donne à un agent tiers sa propre identité et la suspend immédiatement en cas de besoin.

Domaine eai.domains.applications (tables eai.applications, eai.application_deployments, eai.application_identities, migration sql/postgres/V155, sécurité au niveau des lignes forcée). Écran du portail : Agents > Applications (/agents/applications).

Concepts

Élément	Valeurs	Description
`kind`	`agent_app`, `assistant`, `workflow`, `external_agent`	Type d'application. `external_agent` reçoit toujours l'origine `third_party`.
`origin`	`internal`, `third_party`	Qui a construit l'application. Défaut `internal`.
`status`	`draft`, `approved`, `active`, `suspended`, `retired`	Cycle de vie. Seule une application `active` peut appeler un outil, un serveur MCP ou un modèle avec son propre identifiant.
`environments`	1 à 10 noms, défaut `dev`	Environnements qu'un déploiement peut viser.
`risk_level`	`low`, `medium`, `high`	Risque déclaré de l'application. Défaut `medium`.
`agents`, `tools`, `mcp_servers`, `models`, `plugins`	listes de noms ou de motifs glob	Ressources accordées à l'application. Un appel vers une ressource qui ne correspond à aucun motif est refusé.

Le nom compte de 1 à 128 caractères : lettres minuscules, chiffres, ., _ et -, en commençant et en finissant par une lettre ou un chiffre.

Points d'API

Route	Rôles	Effet
`GET /v1/applications`	tout membre du tenant	Liste les applications du tenant, triées par nom.
`POST /v1/applications`	`tenant_admin`, `developer`, `application_owner`	Crée une application en `draft`. Audit `application.create`.
`GET /v1/applications/{app_id}`	tout membre du tenant	Lit une application (id ou nom) avec ses déploiements.
`POST /v1/applications/{app_id}/deployments`	`tenant_admin`, `developer`, `application_owner`	Demande le déploiement d'une version vers un environnement et ouvre une approbation `application_deployment` (approbateurs `tenant_admin`, `security_officer`).
`POST /v1/applications/{app_id}/deployments/{deployment_id}/activate`	`tenant_admin`, `developer`, `application_owner`	Active le déploiement une fois son approbation accordée ; le déploiement actif précédent de l'environnement est retiré.
`POST /v1/applications/{app_id}/external-agents`	`tenant_admin`	Enregistre un agent tiers : une clé d'API avec le rôle `agent`, affichée une seule fois.
`POST /v1/applications/{app_id}/status`	`tenant_admin`, `security_officer`	Passe en `suspended` ou `retired` avec un motif obligatoire ; les déploiements actifs suivent.

Déployer une version

Créer l'application. Le registre est la liste de ce qui peut s'exécuter et avec quelles ressources.
```
curl -X POST -H "X-API-Key: $EAI_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name": "invoice-assistant", "kind": "assistant", "environments": ["dev", "prod"], "tools": ["erp.*"], "models": ["gpt-*"]}' \
  <control-plane-url>/v1/applications
```
Résultat attendu : 201 avec "status": "draft".

En cas d'échec : 409 conflict signifie que le nom est déjà utilisé dans le tenant ; 403 signifie que votre rôle n'est ni tenant_admin, ni developer, ni application_owner.
Demander le déploiement. Le déploiement n'est jamais actif à la demande : il attend une approbation humaine.
```
curl -X POST -H "X-API-Key: $EAI_API_KEY" -H 'Content-Type: application/json' \
  -d '{"version": "1.2.0", "environment": "prod", "reason": "Quarterly release"}' \
  <control-plane-url>/v1/applications/invoice-assistant/deployments
```
Résultat attendu : 201 avec un approval_id.

En cas d'échec : 400 invalid_request signifie que l'environnement n'est pas dans environments ; 409 conflict signifie que cette version est déjà déployée dans cet environnement ; 409 application_suspended signifie que l'application est suspendue ou retirée.
Approuver. Un tenant_admin ou un security_officer autre que le demandeur décide avec POST /v1/approvals/{approval_id}/decide (portail : Agents > Approbations). Le domaine des approbations applique la séparation des tâches.

Résultat attendu : l'approbation est approved.
Activer. POST /v1/applications/{app_id}/deployments/{deployment_id}/activate.

Résultat attendu : le déploiement est active, approved_by nomme l'approbateur, l'application devient active.

En cas d'échec : une approbation non accordée refuse l'activation et écrit l'événement d'audit application.deployment.activate avec deny et le motif approval_required.

Agents tiers

POST /v1/applications/{app_id}/external-agents crée une identité de service liée à l'application : une clé d'API nommée app:<application>:<name>, avec le seul rôle agent, le projet de l'application et les portées tools:invoke, models:invoke plus jusqu'à 20 portées demandées. La clé est renvoyée une seule fois dans api_key.

danger

Rangez la clé immédiatement dans votre gestionnaire de secrets : la Plateforme ne garde que son empreinte et ne peut pas l'afficher de nouveau.

À chaque appel fait avec cette clé, la Tool Gateway, la MCP Gateway et la Model Gateway appellent le contrôle du domaine (services/control-plane/src/eai/domains/tools/service.py, services/control-plane/src/eai/domains/mcp/gateway.py, services/control-plane/src/eai/domains/llm/gateway.py) :

application non active : 403 application_suspended, audit application.call avec deny ;
ressource qui ne correspond à aucun motif accordé : 403 application_tool_not_granted, audit application.call avec deny.

Suspendre une application

POST /v1/applications/{app_id}/status avec {"status": "suspended", "reason": "..."} refuse immédiatement tout appel de l'application et suspend ses déploiements actifs. La réaction SOC SUSPEND_APPLICATION utilise le même point d'entrée. retired met fin à la vie de l'application.

Dépannage

Symptôme	Cause	Correction
`404 application_not_found`	Id ou nom inconnu dans le tenant.	Vérifiez `GET /v1/applications`.
`404 application_deployment_not_found`	Id de déploiement inconnu pour cette application.	Lisez les déploiements avec `GET /v1/applications/{app_id}`.
`403 application_suspended` sur un appel d'outil ou de modèle	L'application liée à la clé n'est pas `active`.	Une application `draft` ou `approved` devient `active` quand un déploiement est approuvé puis activé. Une application `suspended` ou `retired` refuse tout nouveau déploiement (`409 application_suspended`) et la route de statut n'accepte que `suspended` et `retired` : enregistrez une nouvelle application.
`403 application_tool_not_granted`	La ressource n'est pas dans les listes accordées.	Ajoutez le nom ou un motif à `tools`, `mcp_servers` ou `models` de l'application.

Preuve : services/control-plane/tests/test_applications_registry.py.

Retour à l'index - English

Concepts​

Points d'API​

Déployer une version​

Agents tiers​

Suspendre une application​

Dépannage​