Une identité par agent
- Leçon 8
- 45 min
- Module 3 : Enregistrer chaque agent
Où nous en sommes
Dans la dernière leçon, nous avons enregistré six agents, chacun avec un responsable, un niveau de risque, des classes de données et un budget. Mais un enregistrement n'est qu'une fiche. Les applications appellent encore le fournisseur avec des clés partagées ou personnelles. Rien ne relie un appel à un enregistrement. Dans cette leçon, nous donnons à chaque agent sa propre identité et des identifiants de courte durée. Une passerelle devant le fournisseur refuse tout appel sans eux. C'est comme un bureau qui remplace un code de porte commun par une carte d'accès par personne.
Leçon 8 sur 21 · Gouverner les agents d'IA : passerelles, registres et contrôlesUne identité par agent
1. Pourquoi les agents ont besoin de contrôles de plateforme
2. Demander des capacités, pas des modèles
3. Enregistrer chaque agent
4. La passerelle de modèles
5. Gouverner les outils et les actions
6. Utilisation, preuves et IA fantôme
7. Construire, acheter et déployer
Ce que vous saurez faire
Donnez à chaque agent de Larkfield sa propre identité : un identifiant client et un secret. L’agent les échange contre un jeton d’accès valide pendant 10 minutes. Faites ensuite passer les appels des applications par une passerelle de modèles. Elle détient la seule clé du fournisseur. Elle refuse tout appel sans jeton valide et sans enregistrement actif.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- Les enregistrements et leurs statuts, présentés dans Le contenu d’un enregistrement. Votre registre contient 6 enregistrements actifs.
- Les capacités et les associations du catalogue (fast-small → chat-small, strong-reasoning → chat-strong), présentées dans Associer les capacités aux modèles.
- Utile, mais facultatif : les identifiants client, présentés dans Flux d’application : trois appelants, trois identités. Les parties d’un jeton signé, présentées dans Lire un jeton : JWT, signatures et clés. Les deux leçons font partie du cours Authentification, autorisations et applications multilocataires. Cette leçon explique les notions dont elle a besoin.
Ce qu’il vous faut sur votre ordinateur
- Le projet
~/projects/ai-estateaprès la dernière leçon, avec son environnement virtuel actif. La variableSdoit désigner l’instantanéend-of-m03(l’étape 1 ci-dessous la définit de nouveau). - Les ports 8320, 8321 et 8322 libres : le simulateur, le plan de contrôle et la passerelle les utilisent.
curl. Il est inclus avec macOS, Windows 10 et les versions suivantes (sous le nomcurl.exe), et la plupart des systèmes Linux.
Testé sur macOS (puce Apple) avec Python 3.12.13. Les commandes Windows (PowerShell) et Linux sont fournies, mais elles n’ont pas été exécutées pour ce cours.
Un code de porte et une carte d’accès
Section intitulée « Un code de porte et une carte d’accès »Imaginez un petit bureau avec un code de porte, 4711. Tout le monde le connaît : le personnel, l’équipe de nettoyage, un entrepreneur de l’année passée. Un jour, le code apparaît sur un papier dans la rue. Pour empêcher un inconnu d’entrer, le bureau doit changer le code et communiquer le nouveau à tout le monde. Et quand le journal d’alarme indique « porte ouverte à 3 h 12 avec 4711 », personne ne sait qui l’a ouverte.
Le bureau voisin donne une carte d’accès à chaque personne. La carte porte le nom de la personne. La porte vérifie la carte dans une liste à la réception, et le journal indique « Mei, 3 h 12 ». Quand un entrepreneur quitte, la réception retire un nom de la liste. Rien ne change pour les autres. Les visiteurs reçoivent une carte d’une journée qui cesse de fonctionner le soir. La perte d’une telle carte pose donc un petit problème.
Le problème : des clés qui appartiennent à une équipe ou à une personne
Section intitulée « Le problème : des clés qui appartiennent à une équipe ou à une personne »Les applications de Larkfield utilisent des codes de porte. La partie gauche du schéma montre les clés que vous avez vues dans le module 1 :
Description textuelle du diagramme
Avant (clés dans les applications) : le service de triage (triage-svc-01) et le flux de soutien (workflow-01) partagent az-key-1, la clé de l’équipe de service. L’assistant documentaire (docs-01) utilise az-key-2, la clé de l’équipe de données. Le juge des mises en production sur priya-laptop utilise az-key-3, la clé personnelle de Priya. weekly_digest.py sur build-runner-3 utilise fw-7Q2K, une clé Fernway personnelle. Le fournisseur voit une clé, pas une application.
Après (une identité par agent) : chacune des cinq applications possède son propre identifiant client : ticket-triage, support-workflow, doc-assistant, release-judge et helpdesk-assistant. Chacune envoie ses appels à la passerelle de modèles. La passerelle détient az-key-9, la seule clé du fournisseur, et l’utilise pour appeler Azure. Le plan de contrôle signe des jetons valides pendant 10 minutes. Il donne à la passerelle la clé publique qui les vérifie. Le résumé hebdomadaire n’a aucun enregistrement, donc la passerelle le refuse avec 401. Son chemin direct vers Fernway reste ouvert jusqu’à ce que le réseau le bloque, dans le module 6.
Chacune de ces clés pose un problème que vous pouvez nommer :
- Une clé partagée ne permet pas d’arrêter une seule application. Supposons que le flux tourne en boucle et dépense de l’argent. Pour l’arrêter, Kwame doit révoquer
az-key-1. Cela arrête aussi le service de triage. Les 822 billets de soutien quotidiens attendent alors qu’une personne s’en occupe. - Une clé personnelle part avec la personne. Si Priya quitte, sa clé cesse de fonctionner. Pire encore, elle pourrait continuer de fonctionner sur un compte que personne ne surveille. Le juge des mises en production, qui vérifie chaque mise en production, en dépend.
- Une clé dans une application ne permet pas de savoir « quelle application ». La facture indique
az-key-1. Elle ne précise pas si le service de triage ou le flux a dépensé l’argent. - Une clé détenue par une application peut aller n’importe où.
fw-7Q2Kva chez un fournisseur sans contrat, et rien entre les deux ne peut la refuser.
Tomás n’est pas d’accord : « Une clé partagée par équipe, ça suffit. L’équipe connaît ses applications. » Cela fonctionne jusqu’au jour où l’équipe doit arrêter une seule application, où une personne quitte, ou où il faut répartir la facture entre les applications. L’équipe a alors un code de porte.
L’idée : une identité par agent et des jetons de courte durée
Section intitulée « L’idée : une identité par agent et des jetons de courte durée »La solution comporte trois parties, et chacune reprend le principe de la carte d’accès.
- Une identité par agent. Chaque agent enregistré reçoit son propre identifiant client, qui correspond à son identifiant d’enregistrement. Il reçoit aussi un secret client, une chaîne aléatoire que seul l’agent connaît. Le registre conserve seulement un hachage du secret, une empreinte qui ne permet pas de retrouver le secret. Cette paire constitue les identifiants de l’agent.
- Un jeton de courte durée. L’agent n’envoie pas son secret à chaque appel. Il échange ses identifiants contre un jeton d’accès au point de terminaison des jetons du plan de contrôle. Il utilise le flux appelé client credentials (identifiants client). Le plan de contrôle est le service propre au parc. Il émet les jetons, conserve la clé de signature et publie le registre et le catalogue pour les passerelles. Le jeton est un JSON Web Token (JWT) : du JSON lisible, signé par le plan de contrôle. Il nomme l’agent, le service auquel il est destiné (son audience) et son expiration : après 600 secondes. Il nomme aussi le secret qui a permis de l’obtenir, par son identifiant. C’est la carte d’accès d’une journée.
- Une seule porte. Les applications n’appellent plus le fournisseur. Elles appellent la passerelle de modèles, un service qui utilise la même API que le fournisseur. La passerelle détient la seule clé du fournisseur. Elle vérifie chaque jeton avec la clé publique du plan de contrôle. Elle consulte l’enregistrement de l’agent avant de transmettre quoi que ce soit.
Le jeton ne contient aucune équipe, aucun rôle et aucune autorisation. Il dit seulement « c’est ticket-triage, pour la passerelle de modèles, jusqu’à 14 h 10 ». La passerelle lit dans le registre ce que ticket-triage peut faire. Elle utilise un instantané reçu du plan de contrôle toutes les 2 secondes. Un changement au registre s’applique donc immédiatement, même aux jetons déjà émis. Le format du jeton est le même que dans Authentification, autorisations et applications multilocataires et MCP : connecter les applications d’IA aux outils et aux données : RS256, typ: at+jwt, émetteur, sujet, audience et expiration.
Description textuelle du diagramme
- Toutes les 2 secondes, le plan de contrôle donne un instantané à la passerelle : les enregistrements, le catalogue et la clé publique.
- L’application envoie
POST /oauth/tokenau plan de contrôle :client_id(identifiant client) ticket-triage, sonclient_secret(secret client), et l’audiencemodel-gateway. - Le plan de contrôle vérifie que le hachage du secret correspond et que l’enregistrement est actif. Il répond avec un jeton d’accès : RS256,
typ: at+jwt,expires_in: 600(expire dans 600 secondes). - L’application envoie
POST /v1/chat/completionsà la passerelle, avecmodel: fast-smallet l’en-têteAuthorization: Bearersuivi du jeton. - La passerelle vérifie, dans l’ordre : sa configuration, l’identité (signature, audience, temps), l’enregistrement et la capacité.
- Elle envoie la requête pour le déploiement
chat-smallau fournisseur, avec sa propre cléaz-key-9. - Le fournisseur répond 200, depuis le modèle
gpt-6-luna-2026-09-22. - La passerelle répond à l’application avec 200 et l’en-tête
x-gateway-model: chat-small (gpt-6-luna-2026-09-22). - L’application conserve le jeton et en demande un nouveau 30 secondes avant son expiration.
Larkfield : ajouter des identités et la première passerelle
Section intitulée « Larkfield : ajouter des identités et la première passerelle »Vous copiez le code d’identité, le plan de contrôle, la passerelle, le nouveau client des applications et les tests du module. Votre projet correspond alors à l’instantané end-of-m03.
-
Arrêtez le parc s’il est en cours d’exécution :
Fenêtre de terminal python -m estate down -
Copiez les fichiers de cette leçon :
Fenêtre de terminal S=../nextia-learning-labs/C32/snapshots/end-of-m03cp $S/estate/identity.py $S/estate/server.py $S/estate/configstore.py estate/cp $S/estate/cli/identity.py $S/estate/cli/config.py $S/estate/cli/core.py estate/cli/cp -R $S/gateway .cp $S/apps/client.py $S/apps/replay.py apps/cp $S/tests/conftest.py $S/tests/test_identity.py $S/tests/test_configstore.py tests/cp $S/tests/test_gateway_first.py $S/tests/test_replay.py $S/tests/test_registry.py tests/cp $S/README.md $S/.env.example .Fenêtre de terminal $S = "..\nextia-learning-labs\C32\snapshots\end-of-m03"Copy-Item $S\estate\identity.py, $S\estate\server.py, $S\estate\configstore.py estate\Copy-Item -Force $S\estate\cli\identity.py, $S\estate\cli\config.py, $S\estate\cli\core.py estate\cli\Copy-Item -Recurse $S\gateway .Copy-Item -Force $S\apps\client.py, $S\apps\replay.py apps\Copy-Item -Force $S\tests\conftest.py, $S\tests\test_identity.py, $S\tests\test_configstore.py tests\Copy-Item -Force $S\tests\test_gateway_first.py, $S\tests\test_replay.py, $S\tests\test_registry.py tests\Copy-Item -Force $S\README.md, $S\.env.example .Fenêtre de terminal S=../nextia-learning-labs/C32/snapshots/end-of-m03cp $S/estate/identity.py $S/estate/server.py $S/estate/configstore.py estate/cp $S/estate/cli/identity.py $S/estate/cli/config.py $S/estate/cli/core.py estate/cli/cp -R $S/gateway .cp $S/apps/client.py $S/apps/replay.py apps/cp $S/tests/conftest.py $S/tests/test_identity.py $S/tests/test_configstore.py tests/cp $S/tests/test_gateway_first.py $S/tests/test_replay.py $S/tests/test_registry.py tests/cp $S/README.md $S/.env.example . -
Exécutez les tests :
Fenêtre de terminal python -m pytest -qLa dernière ligne :
135 passed, 1 deselected in 16.61sVotre durée diffère. Les 31 nouveaux tests vérifient le registre, les jetons, la configuration publiée par le plan de contrôle et les premières vérifications de la passerelle.
-
Créez les clés du parc et sa première configuration :
Fenêtre de terminal python -m estate initPublished configuration version 1.State folder: /Users/you/projects/ai-estate/stateThe gateway's provider key is in state/secrets.json (only the gateway reads it).The signing key of the estate's tokens is in state/identity/ (only the control plane reads it).Deux secrets existent maintenant, et chacun n’a qu’un seul lecteur. La passerelle lit la clé du fournisseur. Le plan de contrôle lit la clé qui signe les jetons.
Un petit exemple détaillé : les identifiants et le jeton d’un agent
Section intitulée « Un petit exemple détaillé : les identifiants et le jeton d’un agent »Émettez les identifiants du service de triage et examinez son jeton.
-
Émettez les identifiants :
Fenêtre de terminal python -m estate credentials issue ticket-triageNew credentials for ticket-triage: client ID ticket-triage, credential ticket-triage#1; the secret is in state/credentials/ticket-triage.json (shown nowhere else; keep it out of code and out of Git).Le fichier contient deux champs,
client_idetclient_secret. Le secret commence parest-. Git ignore le dossierstate/. Le registre nomme ce secret l’identifiantticket-triage#1; un nouveau secret porterait le suffixe#2. -
Obtenez un jeton avec ces identifiants et affichez ses deux parties lisibles :
Fenêtre de terminal python -m estate token ticket-triage --claims{"header": {"alg": "RS256","kid": "0250ab693191b30a","typ": "at+jwt"},"claims": {"iss": "larkfield-estate","sub": "ticket-triage","aud": "model-gateway","iat": 1792721016,"nbf": 1792721016,"exp": 1792721616,"jti": "19a7b2e5d9da4f3c8f777a4070e5617c","client_id": "ticket-triage","cid": "ticket-triage#1","scope": "model:call"}}Votre
kid(identifiant de clé), vos heures et votrejti(identifiant du jeton) diffèrent.
Lisez chaque valeur, comme le fait la passerelle :
| Champ | Valeur | Signification |
|---|---|---|
alg |
RS256 |
Signé avec la clé RSA privée du plan de contrôle. La passerelle le vérifie avec la clé publique. |
kid |
0250ab693191b30a |
La clé publique à utiliser. Il provient d’un hachage de la clé, donc une nouvelle clé reçoit un nouveau kid. |
typ |
at+jwt |
Un jeton d’accès, pas un autre type de JWT. La passerelle refuse les autres types. |
iss |
larkfield-estate |
Son émetteur : le plan de contrôle du parc. |
sub |
ticket-triage |
Qui appelle : l’identifiant d’enregistrement. La passerelle consulte cet enregistrement. |
aud |
model-gateway |
Le service auquel il est destiné. La passerelle d’outils le refuse. |
iat, nbf, exp |
exp − iat = 1 792 721 616 − 1 792 721 016 = 600 |
Émis à, pas avant et expiration : valide pendant 600 secondes, soit 10 minutes. |
jti |
un identifiant aléatoire | L’identifiant propre à ce jeton, pour les journaux (logs). |
scope |
model:call |
Il permet les appels de modèles, rien d’autre. |
cid |
ticket-triage#1 |
L’identifiant (le secret) qui a permis d’obtenir le jeton. Les jetons d’un identifiant révoqué sont refusés. |
Remarquez ce qui manque : aucune équipe, aucune capacité, aucun budget. Si un jeton contenait « capacités : fast-small », un changement à l’enregistrement attendrait jusqu’à 10 minutes que les anciens jetons expirent. Comme la passerelle lit les capacités dans le registre, un changement s’applique au prochain appel.
Démarrer la plateforme et y faire passer les appels
Section intitulée « Démarrer la plateforme et y faire passer les appels »-
Démarrez le parc :
Fenêtre de terminal python -m estate upLa sortie (vos numéros de processus seront différents) :
provsim up (process 90603) http://127.0.0.1:8320control up (process 90604) http://127.0.0.1:8321gateway up (process 90605) http://127.0.0.1:8322Trois services fonctionnent maintenant : le simulateur de fournisseur, le plan de contrôle (jetons, clés et configuration) et une passerelle.
-
Vérifiez qu’ils répondent :
Fenêtre de terminal python -m estate statusprovsim running {"ok":true,"recordings":5253,"speed":0.0,"egress":"open"}control running {"ok":true,"revision":10}gateway running {"replica":"a","config":"v1.r10","freshness":"fresh"}v1.r10signifie version 1 de la configuration, avec la révision 10 du registre. Chaque modification du registre augmente la révision.fresh(à jour) signifie que la dernière interrogation du plan de contrôle par la passerelle a réussi. -
Envoyez cinq billets de soutien à trier par la passerelle :
Fenêtre de terminal python -m apps.replay ticket-triage --units 5 --via gatewayLa sortie, rejouée :
ticket-triage: 10 requests through the gateway | status {200: 10}answered by: chat-small (gpt-6-luna-2026-09-22) x5, embed-small (text-embedding-3-small) x5tokens: 10,018 in, 2,025 out | cost: US$0.0020Les mêmes billets, les mêmes réponses et le même coût qu’au module 1. Seul le chemin a changé.
-
Envoyez-les de nouveau avec
--verbose, puis lisez les deux premières lignes :Fenêtre de terminal python -m apps.replay ticket-triage --units 5 --via gateway --verbose200 fast-small -> chat-small (gpt-6-luna-2026-09-22)200 embed -> embed-small (text-embedding-3-small)L’application a demandé la capacité
fast-small. La passerelle a choisichat-small, et son en-tête indique la version du modèle qui a répondu.
Cinq requêtes, cinq points d’arrêt
Section intitulée « Cinq requêtes, cinq points d’arrêt »Testez maintenant la porte. Chaque requête ci-dessous comporte une erreur. Avant d’envoyer chacune, prédisez quelle vérification l’arrêtera. Envoyez une requête sans jeton :
curl -s -i -X POST http://127.0.0.1:8322/v1/chat/completions -H 'Content-Type: application/json' -d '{"model": "fast-small"}'curl.exe -s -i -X POST http://127.0.0.1:8322/v1/chat/completions -H "Content-Type: application/json" -d '{\"model\": \"fast-small\"}'curl -s -i -X POST http://127.0.0.1:8322/v1/chat/completions -H 'Content-Type: application/json' -d '{"model": "fast-small"}'La réponse, sans trois en-têtes (date, server, content-length) :
HTTP/1.1 401 Unauthorizedx-gateway-request-id: b4206dfc210244e9x-gateway-replica: ax-gateway-config: v1.r10content-type: application/json
{"error":{"code":"missing_token","message":"Send your access token: Authorization: Bearer <token>.","type":"gateway","check":"identity"}}La réponse nomme la vérification qui l’a refusée : "check": "identity" (vérification : identité). Les quatre autres requêtes utilisent la même commande avec un autre en-tête ou corps. Placez d’abord un jeton dans une variable : sur macOS et Linux, TOKEN=$(python -m estate token ticket-triage); dans PowerShell, $TOKEN = python -m estate token ticket-triage. Ajoutez ensuite -H "Authorization: Bearer $TOKEN" à la commande.
| Vous envoyez | La passerelle répond |
|---|---|
La clé de fournisseur de l’équipe de service, Bearer sim-az-service-team-0001 |
401 invalid_token (jeton invalide) : « Le jeton n’est pas un JWT. » |
Un jeton pour la passerelle d’outils : python -m estate token ticket-triage --audience tool-gateway |
401 wrong_audience (mauvaise audience) : « Ce jeton n’est pas destiné à model-gateway. » |
Le jeton de triage, avec "model": "strong-reasoning" et un message, « Hello » |
403 capability_not_allowed (capacité non autorisée) : « L’enregistrement de ticket-triage ne contient pas strong-reasoning. » |
Le jeton de triage, avec "model": "fast-small" et le message « Hello » |
422 no_recording (aucun enregistrement), du simulateur |
La dernière requête a passé toutes les vérifications de la passerelle. La passerelle l’a envoyée au fournisseur avec sa propre clé, mais le simulateur n’avait aucun enregistrement de « Hello ». Ce code 422 montre que la requête a vraiment franchi la porte.
Description textuelle du diagramme
La passerelle effectue cinq vérifications dans un ordre fixe. La première qui échoue répond :
- Configuration : la passerelle a-t-elle un instantané? Sinon,
503 control_unavailable(contrôle indisponible). - Identité : un jeton valide pour la passerelle de modèles? Sans jeton, elle renvoie
401 missing_token(jeton manquant). Une clé de fournisseur, celle de l’équipe ou du résumé, donne401 invalid_token: « Le jeton n’est pas un JWT. » Un jeton pour la passerelle d’outils donne401 wrong_audience. - Enregistrement : l’agent est-il enregistré et actif? Sinon,
403 not_registered(non enregistré) ouagent_suspended(agent suspendu). - Capacité : l’enregistrement la contient-il? Le service de triage qui demande strong-reasoning reçoit
403 capability_not_allowed. - Routage : la passerelle envoie la requête à chat-small avec sa propre clé. Un corps qu’aucun cours n’a enregistré (« Hello ») reçoit
422 no_recordingdu simulateur. Une requête de triage enregistrée reçoit 200, avecx-gateway-model: chat-small (gpt-6-luna-2026-09-22).
L’ordre compte. L’identité précède l’enregistrement, car la passerelle doit savoir qui appelle avant de chercher son enregistrement. La capacité suit l’enregistrement, car celui-ci contient les capacités. Le prochain module ajoute les classes de données, les limites, les garde-fous et les modes de défaillance au même chemin.
L’ancienne porte est encore ouverte
Section intitulée « L’ancienne porte est encore ouverte »Exécutez le service de triage comme avant, sans --via gateway :
python -m apps.replay ticket-triage --units 1ticket-triage: 2 requests straight to the provider | status {200: 2}answered by: chat-small (gpt-6-luna-2026-09-22) x1, embed-small (text-embedding-3-small) x1tokens: 1,954 in, 375 out | cost: US$0.0004Il fonctionne, car l’application contient encore az-key-1 dans son code. python -m provsim bill montre la différence : les deux requêtes directes utilisent az-key-1. Toutes les autres utilisent az-key-9, la clé de la passerelle. Une passerelle gouverne seulement les appels qui passent par elle. L’enregistrement est obligatoire seulement s’il est impossible de le contourner. Seule la passerelle peut détenir des clés de fournisseur. Le réseau doit bloquer tous les autres chemins vers les fournisseurs. Trouver l’IA non enregistrée, au module 6, repère qui utilise encore l’ancienne porte et la ferme avec une règle réseau.
À vous : le flux de travail de soutien et le script non enregistré
Section intitulée « À vous : le flux de travail de soutien et le script non enregistré »Changez une condition : un autre agent, puis un script sans enregistrement. Prédisez d’abord : que se passe-t-il si vous rejouez maintenant le flux de travail de soutien par la passerelle?
-
Rejouez deux tâches du flux de travail par la passerelle :
python -m apps.replay support-workflow --units 2 --via gateway. -
Lisez le message. Émettez ensuite les identifiants du flux de travail, puis rejouez les deux tâches.
-
Dirigez le résumé hebdomadaire vers la passerelle, puis exécutez-le :
Fenêtre de terminal FERNWAY_URL=http://127.0.0.1:8322/v1 python apps/digest/weekly_digest.pyFenêtre de terminal $env:FERNWAY_URL = "http://127.0.0.1:8322/v1"; python apps/digest/weekly_digest.py; Remove-Item Env:FERNWAY_URLFenêtre de terminal FERNWAY_URL=http://127.0.0.1:8322/v1 python apps/digest/weekly_digest.py -
Envoyez la clé du résumé à la passerelle avec curl, comme dans le tableau ci-dessus :
Bearer sim-fw-personal-7Q2K9XW4et{"model": "fernway-swift"}. -
Émettez les identifiants des trois dernières applications. Rejouez trois unités de l’assistant documentaire et de l’évaluateur de mises en production par la passerelle.
Fenêtre de terminal for a in doc-assistant release-judge helpdesk-assistant; do python -m estate credentials issue $a; doneFenêtre de terminal foreach ($a in "doc-assistant", "release-judge", "helpdesk-assistant") { python -m estate credentials issue $a }Fenêtre de terminal for a in doc-assistant release-judge helpdesk-assistant; do python -m estate credentials issue $a; done
Vérifiez votre travail
Sans ses identifiants, le flux de travail ne peut même pas demander un jeton (votre chemin sera différent) :
No credentials for support-workflow (/Users/you/projects/ai-estate/state/credentials/support-workflow.json). Register it and run: python -m estate credentials issue support-workflowAvec ses identifiants, rejoué :
support-workflow: 6 requests through the gateway | status {200: 6}answered by: chat-strong (gpt-6.1-sol-2026-09-29) x6tokens: 14,776 in, 738 out | cost: US$0.0369Le flux de travail a demandé strong-reasoning, et son enregistrement contient cette capacité. La passerelle l’a donc envoyé à chat-strong.
Le résumé, par la passerelle, se termine par une trace d’erreur Python dont la dernière ligne est :
urllib.error.HTTPError: HTTP Error 401: UnauthorizedLa requête curl montre pourquoi :
{"error":{"code":"invalid_token","message":"The token is not a JWT.","type":"gateway","check":"identity"}}Le résumé envoie une clé personnelle de fournisseur, pas un jeton. Il ne peut pas obtenir de jeton, car il n’a aucun enregistrement. Il ne peut pas s’enregistrer, car son propriétaire est parti. La passerelle le refuse donc à la vérification d’identité, avant qu’un fournisseur voie ses messages clients. Mais sans FERNWAY_URL, le résumé va encore directement à Fernway. Le refus est réel, et la faille l’est aussi.
Les dernières exécutions, rejouées :
doc-assistant: 3 requests through the gateway | status {200: 3}answered by: chat-small (gpt-6-luna-2026-09-22) x3tokens: 2,385 in, 681 out | cost: US$0.0006release-judge: 3 requests through the gateway | status {200: 3}answered by: chat-strong (gpt-6.1-sol-2026-09-29) x3tokens: 4,559 in, 309 out | cost: US$0.0122La clé personnelle de Priya ne fait plus partie du chemin de l’évaluateur de mises en production. Le module 5 utilise les identifiants de l’assistant du centre d’assistance. Le serveur MCP de soutien n’en reçoit aucun : il est appelé et n’appelle aucun modèle.
Erreur courante
Un secret collé dans le code
Symptôme : Amira veut démarrer le service de triage sans le fichier state/credentials/ticket-triage.json. Elle colle donc le secret client dans apps/client.py. Une semaine plus tard, le secret se trouve dans l’historique Git, que quarante personnes peuvent lire. Rien n’échoue et aucune erreur n’apparaît.
Cause : un secret client est un identifiant de longue durée, comme la clé de fournisseur qu’il remplace. Dans le code, il accompagne chaque copie du dépôt.
Diagnostic : cherchez le préfixe des secrets du parc dans le code : grep -rn "est-" apps sur macOS et Linux, ou Select-String -Path apps\*.py -Pattern "est-" dans PowerShell. Dans un projet propre, la recherche ne trouve rien. Le module 6 ajoute un outil d’analyse qui trouve les clés de fournisseur et les secrets dans le code.
Rétablissement : révoquez les identifiants, puis émettez-en de nouveaux immédiatement. Conservez d’abord l’ancien jeton pour un test : OLD=$(python -m estate token ticket-triage) (PowerShell : $OLD = python -m estate token ticket-triage).
python -m estate credentials revoke ticket-triage --reason "the secret was in Git"python -m estate credentials issue ticket-triagepython -m apps.replay ticket-triage --units 1 --via gatewayRevoked 1 credential(s) of ticket-triage. Their tokens are refused too, for good.Told 1 of 1 gateway replicas to refresh now.New credentials for ticket-triage: client ID ticket-triage, credential ticket-triage#2; the secret is in state/credentials/ticket-triage.json (shown nowhere else; keep it out of code and out of Git).Told 1 of 1 gateway replicas to refresh now.ticket-triage: 2 requests through the gateway | status {200: 2}answered by: chat-small (gpt-6-luna-2026-09-22) x1, embed-small (text-embedding-3-small) x1tokens: 1,954 in, 375 out | cost: US$0.0004Le nouveau secret fonctionne immédiatement. Envoyez maintenant l’ancien jeton avec la commande curl de cette leçon, -H "Authorization: Bearer $OLD" :
{"error":{"code":"token_revoked","message":"This token's credentials (ticket-triage#1) were revoked.","type":"gateway","check":"identity"}}L’ancien jeton reste invalide, même s’il n’a pas encore expiré. Retirez ensuite le secret du code. Gardez le nouveau secret hors du code : ici, dans le fichier d’identifiants. En production, utilisez un coffre de secrets ou l’identité de charge de travail de la plateforme.
Cela fonctionne parce que chaque secret est un identifiant distinct, avec son propre ID : ticket-triage#1, puis ticket-triage#2. Le jeton porte cet ID dans sa revendication (claim) cid, et le registre conserve chaque révocation définitivement. La passerelle compare les ID, pas les heures. Elle reste donc exacte, même au cours de la même seconde. L’équipe du cours a trouvé un véritable bogue en rédigeant cette leçon, puis l’a corrigé. Dans la première version, les nouveaux identifiants remplaçaient la ligne révoquée dans le registre. La passerelle oubliait alors la révocation à sa prochaine interrogation. Un jeton volé avant la révocation fonctionnait de nouveau, jusqu’à son expiration. Le prochain secret ne doit jamais écraser une liste de révocation.
Conséquence pour le travail en IA : la fuite d’un secret client a moins de portée que celle d’une clé de fournisseur. Il fonctionne pour un seul agent enregistré, selon les capacités et les limites de son enregistrement. La plateforme peut le révoquer sans toucher aux autres applications. C’est l’intérêt d’une identité par agent, mais seulement si le secret reste hors du code.
Quand utiliser une identité par agent, et ce qu’elle coûte
Section intitulée « Quand utiliser une identité par agent, et ce qu’elle coûte »Utilisez-la dès que deux applications partagent un compte fournisseur ou qu’une clé personnelle fait fonctionner un outil partagé. Les avantages sont ceux du badge. Vous pouvez arrêter un seul agent. Une personne qui part n’emporte aucun agent, et chaque appel nomme son agent.
Cela coûte trois choses. D’abord, un plan de contrôle qui émet des jetons. S’il tombe en panne, une application avec un jeton valide fonctionne encore jusqu’à 10 minutes. Mais une application redémarrée ne peut pas obtenir de jeton. Le module 4 mesure cela. Ensuite, un secret par agent que quelqu’un doit stocker, renouveler et révoquer. Enfin, une passerelle pour chaque appel. C’est le sujet du prochain module, y compris ce qui arrive quand elle tombe en panne.
L’identité a aussi ses limites. Elle nomme l’agent, pas la personne qu’il sert. Quand l’assistant du centre d’assistance lit un billet pour Sam, le jeton indique helpdesk-assistant, pas Sam. Déléguer les droits d’une personne à un agent est un sujet du cours Authentification, autorisations et applications multilocataires. Et le serveur MCP de soutien verra la passerelle d’outils, pas l’agent. Le module 5 montre ce que cela signifie.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Le flux de travail et le service de triage partagent az-key-1. Le flux de travail commence à tourner en boucle. Que peut faire Kwame aujourd'hui avec la clé partagée? Que pourra-t-il faire quand chaque application aura sa propre identité derrière la passerelle?
Afficher la réponse
Avec la clé partagée, il peut seulement révoquer az-key-1. Cela arrête aussi le service de triage. Une personne devrait alors traiter les 822 billets quotidiens en attente. Avec une identité par agent, il suspend ou révoque seulement support-workflow. Sa prochaine demande de jeton est refusée, et la passerelle refuse ses appels. Le jeton du service de triage continue de fonctionner. La clé de fournisseur az-key-9 reste dans la passerelle, intacte.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Prédisez : un attaquant copie le jeton d'accès du service de triage dans un journal à 14 h. Que peut-il en faire, et jusqu'à quand? Qu'est-ce qui serait différent avec une clé de fournisseur volée?
Afficher la réponse
Il peut appeler la passerelle de modèles comme ticket-triage, seulement avec les capacités de son enregistrement : fast-small et embed. Le jeton fonctionne jusqu’à son expiration, 600 secondes après son émission, vers 14 h 10. La passerelle d’outils le refuse, car son audience est model-gateway. Révoquer les identifiants du triage l’invalide immédiatement. Une clé de fournisseur volée fonctionnerait pour n’importe quel modèle, de partout, sans enregistrement ni limites. Elle fonctionnerait jusqu’à ce que quelqu’un la change pour chaque application qui l’utilise.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Le jeton ne contient ni capacités ni équipe. Pourquoi est-ce un bon choix ici? Quel en est le coût?
Afficher la réponse
La passerelle lit les autorisations dans l’instantané du registre, qu’elle actualise toutes les 2 secondes. Une modification prend donc effet au prochain appel, comme retirer une capacité ou suspendre l’agent. Avec les autorisations dans le jeton, il faudrait attendre l’expiration des anciens jetons. Le coût : la passerelle doit avoir un instantané récent. Elle dépend donc du plan de contrôle pour sa configuration. Elle conserve le dernier instantané quand le plan de contrôle tombe en panne, ce que mesure le module 4.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Récapitulatif
- Chaque agent enregistré a sa propre identité : un ID client (son ID d’enregistrement) et un secret client. Le registre conserve seulement le hachage du secret.
- L’agent échange ses identifiants client contre un jeton d’accès, un JWT signé (RS256,
typ: at+jwt). Celui-ci nomme l’agent (sub), le service (aud) et l’expiration, 600 secondes plus tard. Il ne contient aucune autorisation. - La passerelle de modèles détient la seule clé de fournisseur,
az-key-9. Elle vérifie la configuration, l’identité, l’enregistrement et la capacité, dans cet ordre. Le premier échec répond avec son code et sa vérification. - Une clé de fournisseur, un jeton pour la passerelle d’outils, un agent inconnu et une capacité absente de l’enregistrement sont refusés. Le résumé hebdomadaire est refusé à la vérification d’identité.
- L’ancien chemin fonctionne encore tant qu’une application détient une clé de fournisseur et que le réseau autorise sa sortie.
Votre projet maintenant : ~/projects/ai-estate, identique à l’instantané end-of-m03, avec 135 tests réussis, trois services et des identifiants pour cinq applications. Vous pouvez maintenant relier chaque appel à la passerelle à un agent enregistré. Mais les enregistrements ne restent pas exacts : les propriétaires partent, les dates de révision passent et les agents sont remplacés. Ensuite, nous suivons un agent pendant toute sa vie et trouvons ceux dont personne ne s’occupe.
Leçon suivante : Le cycle de vie d'un agent