Aller au contenu
English

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.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité

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 mainEnviron 45 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Le projet ~/projects/ai-estate après la dernière leçon, avec son environnement virtuel actif. La variable S doit 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 nom curl.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.

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 :

Deux panneaux. Avant, les clés sont dans les applications : le triage des billets sur triage-svc-01 et le flux de soutien sur workflow-01 utilisent tous deux az-key-1, partagée par une équipe. L'assistant documentaire sur docs-01 utilise az-key-2, partagée par une équipe. Le juge des mises en production sur priya-laptop utilise az-key-3, la clé personnelle de Priya, en rouge. weekly_digest.py sur build-runner-3 utilise fw-7Q2K, personnelle, en rouge. Une note : le fournisseur voit une clé, pas une application; une clé sert à deux applications; deux clés appartiennent à des personnes, pas à des agents. Après, une identité par agent : ticket-triage, support-workflow, doc-assistant, release-judge et helpdesk-assistant ont chacun leur propre identifiant client, en vert. Chacun envoie ses appels à la passerelle de modèles, qui détient az-key-9, la seule clé du fournisseur. Le plan de contrôle signe un jeton valide pendant 10 minutes et donne sa clé publique à la passerelle. La passerelle appelle Azure avec az-key-9. weekly_digest.py n'a aucun enregistrement : son appel à la passerelle se termine par 401. Mais une flèche rouge pointillée, encore ouverte, va directement de ce script à Fernway. Une note : chaque agent demande un jeton avec son propre identifiant client et son secret; le chemin direct reste ouvert jusqu'à ce que le réseau le bloque.
Avant : une clé pour deux applications, et des clés qui appartiennent à des personnes. Après : une identité par agent, et une seule clé du fournisseur, détenue par la passerelle.
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-7Q2K va 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.

  1. 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.
  2. 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.
  3. 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.

Une séquence entre quatre participants : l'application ticket-triage, le plan de contrôle sur le port 8321, la passerelle de modèles sur le port 8322 et le fournisseur, le simulateur. 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/token avec client_id ticket-triage, son client_secret et l'audience model-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. L'application envoie POST /v1/chat/completions avec model fast-small et Authorization : Bearer, suivi du jeton. La passerelle effectue ses vérifications : 1 configuration, 2 identité (signature, audience, temps), 3 enregistrement, 4 capacité. Elle envoie le déploiement chat-small au fournisseur avec sa propre clé az-key-9. Le fournisseur répond 200, 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.
Un appel avec sa propre identité : l'application obtient un jeton une fois. La passerelle le vérifie à chaque appel sans interroger le plan de contrôle.
Description textuelle du diagramme
  1. Toutes les 2 secondes, le plan de contrôle donne un instantané à la passerelle : les enregistrements, le catalogue et la clé publique.
  2. L’application envoie POST /oauth/token au plan de contrôle : client_id (identifiant client) ticket-triage, son client_secret (secret client), et l’audience model-gateway.
  3. 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).
  4. L’application envoie POST /v1/chat/completions à la passerelle, avec model: fast-small et l’en-tête Authorization: Bearer suivi du jeton.
  5. La passerelle vérifie, dans l’ordre : sa configuration, l’identité (signature, audience, temps), l’enregistrement et la capacité.
  6. Elle envoie la requête pour le déploiement chat-small au fournisseur, avec sa propre clé az-key-9.
  7. Le fournisseur répond 200, depuis le modèle gpt-6-luna-2026-09-22.
  8. La passerelle répond à l’application avec 200 et l’en-tête x-gateway-model: chat-small (gpt-6-luna-2026-09-22).
  9. 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.

  1. Arrêtez le parc s’il est en cours d’exécution :

    Fenêtre de terminal
    python -m estate down
  2. Copiez les fichiers de cette leçon :

    Fenêtre de terminal
    S=../nextia-learning-labs/C32/snapshots/end-of-m03
    cp $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 .
  3. Exécutez les tests :

    Fenêtre de terminal
    python -m pytest -q

    La dernière ligne :

    135 passed, 1 deselected in 16.61s

    Votre 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.

  4. Créez les clés du parc et sa première configuration :

    Fenêtre de terminal
    python -m estate init
    Published configuration version 1.
    State folder: /Users/you/projects/ai-estate/state
    The 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.

  1. Émettez les identifiants :

    Fenêtre de terminal
    python -m estate credentials issue ticket-triage
    New 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_id et client_secret. Le secret commence par est-. Git ignore le dossier state/. Le registre nomme ce secret l’identifiant ticket-triage#1; un nouveau secret porterait le suffixe #2.

  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 votre jti (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.

  1. Démarrez le parc :

    Fenêtre de terminal
    python -m estate up

    La sortie (vos numéros de processus seront différents) :

    provsim up (process 90603) http://127.0.0.1:8320
    control up (process 90604) http://127.0.0.1:8321
    gateway up (process 90605) http://127.0.0.1:8322

    Trois services fonctionnent maintenant : le simulateur de fournisseur, le plan de contrôle (jetons, clés et configuration) et une passerelle.

  2. Vérifiez qu’ils répondent :

    Fenêtre de terminal
    python -m estate status
    provsim 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.r10 signifie 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.

  3. Envoyez cinq billets de soutien à trier par la passerelle :

    Fenêtre de terminal
    python -m apps.replay ticket-triage --units 5 --via gateway

    La 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) x5
    tokens: 10,018 in, 2,025 out | cost: US$0.0020

    Les mêmes billets, les mêmes réponses et le même coût qu’au module 1. Seul le chemin a changé.

  4. 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 --verbose
    200 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 choisi chat-small, et son en-tête indique la version du modèle qui a répondu.

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 :

Fenêtre de terminal
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 Unauthorized
x-gateway-request-id: b4206dfc210244e9
x-gateway-replica: a
x-gateway-config: v1.r10
content-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.

Un flux des vérifications de la passerelle, de haut en bas, avec la requête que chacune a arrêtée. Une requête à la passerelle de modèles. Vérification 1, configuration : la passerelle a-t-elle un instantané? Sinon : 503 control_unavailable. Vérification 2, identité : un jeton valide pour la passerelle de modèles? Aucun jeton : 401 missing_token. Une clé de fournisseur, celle de l'équipe ou du résumé : 401 invalid_token, le jeton n'est pas un JWT. Un jeton pour la passerelle d'outils : 401 wrong_audience. Vérification 3, enregistrement : enregistré et actif? Sinon : 403 not_registered, ou agent_suspended. Vérification 4, capacité : l'enregistrement la contient-il? Le triage demande strong-reasoning : 403 capability_not_allowed. Vérification 5, routage : chat-small, avec la clé de la passerelle. Un corps qu'aucun cours n'a enregistré, Hello : 422 no_recording, du simulateur. Une requête de triage enregistrée : 200, x-gateway-model : chat-small (gpt-6-luna-2026-09-22).
Les vérifications de la première passerelle, dans l'ordre. La première vérification qui échoue répond et se nomme dans l'erreur.
Description textuelle du diagramme

La passerelle effectue cinq vérifications dans un ordre fixe. La première qui échoue répond :

  1. Configuration : la passerelle a-t-elle un instantané? Sinon, 503 control_unavailable (contrôle indisponible).
  2. 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é, donne 401 invalid_token : « Le jeton n’est pas un JWT. » Un jeton pour la passerelle d’outils donne 401 wrong_audience.
  3. Enregistrement : l’agent est-il enregistré et actif? Sinon, 403 not_registered (non enregistré) ou agent_suspended (agent suspendu).
  4. Capacité : l’enregistrement la contient-il? Le service de triage qui demande strong-reasoning reçoit 403 capability_not_allowed.
  5. 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_recording du simulateur. Une requête de triage enregistrée reçoit 200, avec x-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.

Exécutez le service de triage comme avant, sans --via gateway :

Fenêtre de terminal
python -m apps.replay ticket-triage --units 1
ticket-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) x1
tokens: 1,954 in, 375 out | cost: US$0.0004

Il 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?

  1. Rejouez deux tâches du flux de travail par la passerelle : python -m apps.replay support-workflow --units 2 --via gateway.

  2. Lisez le message. Émettez ensuite les identifiants du flux de travail, puis rejouez les deux tâches.

  3. 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.py
  4. Envoyez la clé du résumé à la passerelle avec curl, comme dans le tableau ci-dessus : Bearer sim-fw-personal-7Q2K9XW4 et {"model": "fernway-swift"}.

  5. É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; 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-workflow

Avec ses identifiants, rejoué :

support-workflow: 6 requests through the gateway | status {200: 6}
answered by: chat-strong (gpt-6.1-sol-2026-09-29) x6
tokens: 14,776 in, 738 out | cost: US$0.0369

Le 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: Unauthorized

La 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) x3
tokens: 2,385 in, 681 out | cost: US$0.0006
release-judge: 3 requests through the gateway | status {200: 3}
answered by: chat-strong (gpt-6.1-sol-2026-09-29) x3
tokens: 4,559 in, 309 out | cost: US$0.0122

La 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).

Fenêtre de terminal
python -m estate credentials revoke ticket-triage --reason "the secret was in Git"
python -m estate credentials issue ticket-triage
python -m apps.replay ticket-triage --units 1 --via gateway
Revoked 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) x1
tokens: 1,954 in, 375 out | cost: US$0.0004

Le 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é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.

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.

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.

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