Aller au contenu principal

Premiers pas : un premier agent sécurisé

English version: ../../en/guides/getting-started.md

Ce tutoriel vous mène d'un tenant vide à un premier agent gouverné : vous vous connectez au portail, créez un projet et une clé d'API, générez, testez et déployez un agent, démarrez une exécution, approuvez l'action qu'il demande et suivez sa trace. Qui : un développeur avec le rôle tenant_admin pour les étapes 1 à 3 (ou un administrateur qui les fait pour vous), puis le rôle developer. Durée : environ 30 minutes.

Prérequis​

Le SDK Python et la CLI s'installent ensemble ; l'accès se fait avec une clé d'API de tenant ou un jeton OIDC. Le tenant est toujours résolu à partir de l'identifiant, jamais du corps de la requête.

pip install -e sdks/python
enterprise-ai login --base-url https://ai.acme.example --api-key eai_...
enterprise-ai doctor
BesoinVérification
Un compte du portail (OIDC Keycloak ou compte local)Vous ouvrez la page de connexion du portail.
Python 3 et pippython3 --version
Les binaires opa et fga pour les tests d'autorisationopa version, fga version (un binaire manquant est une erreur, jamais un test ignoré)
Une seconde personne avec un rôle d'approbateur pour l'étape 8Le demandeur n'approuve jamais sa propre demande.
remarque

Les exemples utilisent https://ai.acme.example et eai_.... Remplacez-les par l'adresse de votre Control Plane et la clé créée à l'étape 3. Sans --base-url, la CLI lit EAI_BASE_URL, puis le profil actif.

Tutoriel​

  1. Se connecter au portail. Le portail est la console du Control Plane : chaque écran utilisé ci-dessous appelle la même API que la CLI, sous votre identité.

    Écran : ouvrez l'adresse du portail, puis Se connecter. Avec un compte local, le portail appelle POST /v1/auth/login ; avec Keycloak, il suit le flux OIDC de votre organisation.

    Résultat attendu : la page Vue d'ensemble affiche la santé, l'usage et les dépenses de votre tenant.

    En cas d'échec : 401 invalid_credentials signale un nom d'utilisateur ou un mot de passe faux ; 429 account_locked signale trop de tentatives (attendez details.retry_after secondes) ; 403 local_auth_disabled signale que votre site n'accepte que l'OIDC.

  2. Créer un projet. Un projet regroupe agents, modèles et budgets, et chaque clé d'API, activation et exécution appartient à un projet du tenant. Chaque projet a les environnements dev, test, staging et prod.

    Écran : Administration > Projets et environnements > Nouveau projet, donnez un slug (support) et un nom. API : POST /v1/projects avec slug et name (tous deux obligatoires).

    curl -X POST -H "X-API-Key: $EAI_API_KEY" -H 'Content-Type: application/json' \
      -d '{"slug": "support", "name": "Support"}' https://ai.acme.example/v1/projects

    Résultat attendu : le projet apparaît dans la liste avec ses environnements (GET /v1/projects/{project_id}/environments).

    En cas d'échec : 403 forbidden avec details.required_roles signale qu'il vous manque tenant_admin ; 409 conflict signale que le slug est déjà pris dans le tenant.

  3. Créer une clé d'API. La CLI, les SDK et votre CI s'authentifient avec une clé de tenant liée à un projet et à un environnement ; ses droits ne peuvent pas dépasser les vôtres.

    Écran : Administration > Clés d'API > Nouvelle clé d'API, choisissez le projet support, l'environnement dev et la plus petite liste de droits. API : POST /v1/api-keys (name obligatoire, plus project, environment, scopes, roles, expires_in_days).

    Résultat attendu : le secret eai_... s'affiche une seule fois. Copiez-le dans votre gestionnaire de secrets, puis lancez avec lui la commande enterprise-ai login des prérequis ; enterprise-ai doctor indique le contrôle authentication à PASS.

    En cas d'échec : 403 forbidden avec details.reason: scope_not_held signale un droit demandé que vous ne détenez pas. À l'usage, 401 invalid_api_key signale une clé mal recopiée et 401 api_key_revoked une clé révoquée : créez-la ou renouvelez-la (POST /v1/api-keys/{key_id}/rotate).

  4. Créer le projet d'agent. Le modèle fournit un manifeste valide, ses politiques et ses tests : le premier déploiement passe déjà les contrôles. Le détail est dans la section suivante.

    Résultat attendu : enterprise-ai validate -f agent.yaml indique que le manifeste est valide.

    En cas d'échec : la CLI liste chaque erreur de schéma avec son chemin JSON ; corrigez agent.yaml et validez à nouveau.

  5. Tester puis déployer l'agent. Le déploiement passe par la porte qualité : un agent qui échoue à ses tests d'autorisation ou de sécurité n'est jamais déployé. Les commandes sont dans « Tester puis déployer » ci-dessous.

    Écran : Agents > Registre affiche ticket-helper avec sa version et son statut.

    Résultat attendu : l'agent est actif en dev (enterprise-ai agent inspect ticket-helper).

    En cas d'échec : enterprise-ai test authz nomme le test OPA ou OpenFGA en échec ; enterprise-ai test security sort en code 1 au-dessus du seuil.

  6. Démarrer une première exécution. Une exécution (run) traite une tâche avec l'agent ; elle reçoit un ExecutionContext signé et chaque appel de modèle et d'outil est contrôlé.

    Écran : Agents > Exécutions > Démarrer une exécution. CLI : enterprise-ai run start ticket-helper --task "..." --follow. API : POST /v1/agents/{agent_id}/runs avec un objet task.

    Résultat attendu : l'exécution passe de pending à running, puis succeeded, ou à waiting_approval quand une action demande une décision humaine.

    En cas d'échec : 409 agent_not_active signale un agent suspendu ou arrêté (details.status) ; 429 rate_limited signale une fenêtre de quota pleine.

  7. Trouver l'exécution en attente d'approbation. Une action sensible (écriture, paiement, mise en production) met l'exécution en pause au lieu de s'exécuter sans contrôle.

    enterprise-ai runs list --state waiting_approval
    enterprise-ai runs get <run_id>

    <run_id> : identifiant affiché par run start.

    Résultat attendu : l'exécution est à l'état waiting_approval avec l'approbation qu'elle attend.

    En cas d'échec : une liste vide signifie qu'aucune action de la tâche ne demandait d'approbation ; l'exécution est déjà terminée.

  8. Approuver l'action. Séparation des tâches : une seconde personne avec un rôle d'approbateur décide, jamais le demandeur.

    Écran : Agents > Approbations, ouvrez la demande, puis Approuver ou Rejeter. API : POST /v1/approvals/{approval_id}/decide avec {"decision": "approve"} ou {"decision": "reject"} et un comment facultatif.

    Résultat attendu : une fois le quorum atteint, l'approbation passe à approved et l'exécution reprend ; un rejet termine l'exécution avec le code approval_rejected.

    En cas d'échec : 403 separation_of_duties signale que le demandeur a tenté d'approuver ; 403 forbidden signale un rôle manquant (details.required_roles) ; 409 approval_closed signale une demande déjà décidée ou expirée ; 409 already_decided signale que vous avez déjà voté.

  9. Suivre la trace. La trace prouve ce que l'agent a fait : chaque étape, chaque appel de modèle et d'outil, chaque décision de politique et son événement d'audit.

    enterprise-ai run events <run_id>
    enterprise-ai logs <run_id>

    Écran : Agents > Exécutions, ouvrez l'exécution pour ses étapes ; Observabilité > Traces pour les spans. API : GET /v1/runs/{run_id}/steps, GET /v1/runs/{run_id}/events et GET /v1/telemetry/traces.

    Résultat attendu : les étapes listent les appels de modèle par la passerelle, les appels d'outil par la Tool Gateway et la décision d'approbation.

    En cas d'échec : 404 not_found sur l'exécution signale qu'elle appartient à un autre tenant ou projet que votre clé.

Créer le projet​

enterprise-ai create agent copie le modèle sdks/python/src/enterprise_ai/templates/agent-basic : manifeste valide selon contracts/v1/agent-manifest.schema.json, politiques OPA et leurs tests, tests unitaires, AGENTS.md et RULES.md. Le modèle secure-agent est un alias de agent-basic.

enterprise-ai create agent ticket-helper --template secure-agent
cd ticket-helper
enterprise-ai validate -f agent.yaml

Tester puis déployer​

enterprise-ai test authz exécute opa test et les tests du modèle OpenFGA (un binaire manquant est une erreur), enterprise-ai test security lance une campagne red team. Le déploiement passe par la porte qualité.

enterprise-ai test authz
enterprise-ai test security --threshold 0
enterprise-ai deploy agent -f agent.yaml --env dev
enterprise-ai run start ticket-helper --task "Résume ce ticket" --follow

Ce qui protège l'agent​

Chaque appel de modèle passe par la passerelle (POST /v1/gateway/chat/completions), chaque outil par la Tool Gateway (POST /v1/tools/{name}/invoke) ; le run reçoit un ExecutionContext signé (voir Référence ExecutionContext) et chaque action produit un ActionContext (Référence ActionContext).

Vérifier​

ContrôleCommande ou écranRésultat attendu
Profil et connexionenterprise-ai doctorchaque contrôle PASS (configuration, connectivity, tls, authentication, versions, clock)
Agent déployéenterprise-ai agent inspect ticket-helperstatut active
Exécution terminéeenterprise-ai runs get <run_id>état succeeded
Décision enregistréeAgents > Approbationsapprobation approved par deux personnes distinctes

Dépannage​

SymptômeCauseCorrection
401 invalid_api_keyclé mal recopiée ou tronquéerecopiez la clé, lancez enterprise-ai login --api-key ...
401 api_key_revokedclé révoquée ou renouveléecréez une clé dans Administration > Clés d'API
401 unauthenticatedaucun identifiant envoyélancez enterprise-ai login, ou définissez EAI_API_KEY
403 forbiddenrôle ou droit manquantdemandez à un tenant_admin le rôle nommé dans details.required_roles
409 agent_not_activeagent suspendu ou arrêtéreprenez-le (POST /v1/agents/{agent_id}/resume) une fois la cause comprise
403 separation_of_dutiesle demandeur approuve sa propre demandefaites décider un autre approbateur
409 approval_closedapprobation déjà décidée ou expiréerelancez l'exécution
429 rate_limitedfenêtre de quota pleineattendez la fenêtre, ou consultez enterprise-ai quotas usage

Étapes suivantes​