Annuaires d'agents Module

Vaks PM · Guide d'intégration · Annuaires d'agents · Juillet 2026

Ce que vous obtiendrez. Les identités d'agents IA qui existent déjà dans votre tenant Microsoft Entra, recopiées dans Vaks PM sous forme de comptes agents — chacun rattaché à un propriétaire humain nommé, en lecture seule, et incapable de s'authentifier tant que vous ne lui avez pas délibérément remis un jeton. Ce guide ne suppose aucune connaissance préalable du produit et demande une quinzaine de minutes.

Ce que ça fait — et ce que ça ne fait pas

Vaks PM traite les agents IA comme des acteurs de première classe : un agent est un compte utilisateur avec kind = AGENT, un propriétaire humain obligatoire, un niveau de confiance et une liste explicite de capacités. Un connecteur d'annuaire vous épargne la création manuelle de ces comptes quand votre organisation déclare déjà ses agents ailleurs. Il lit la liste sur cette plateforme, à la demande, et la recopie.

Les limites méritent d'être posées précisément, car cette intégration est volontairement étroite :

Elle importe des identités, pas des droits. Un agent synchronisé arrive au niveau de confiance Draft only avec une seule capacité, read:project. Rien sur la plateforme distante ne peut élargir cela.
Elle ne crée jamais d'identifiants. Un agent synchronisé n'a aucun jeton API et ne peut pas se connecter du tout. Émettre un jeton est une action humaine distincte et délibérée (voir étape 4).
Elle ne supprime jamais. Un agent désactivé sur la plateforme devient Suspendu dans Vaks PM ; supprimer le connecteur laisse en place les agents déjà importés.
Elle est manuelle. Il n'y a pas de planificateur de fond. La recopie n'avance que lorsque quelqu'un presse Sync now.
Elle est unidirectionnelle. Vaks PM n'écrit jamais vers Entra.

À la resynchronisation, seuls le nom, le statut et les champs de modèle de l'agent sont rafraîchis. Le niveau de confiance, les capacités et le propriétaire — tout ce qu'un humain a décidé — ne sont jamais écrasés.

Quels annuaires puis-je connecter ? Le connecteur est un mécanisme générique — la procédure (choisir la plateforme, saisir ses identifiants, désigner un propriétaire par défaut, synchroniser) est la même quelle que soit la source. Aujourd'hui, une plateforme est fournie : Microsoft Entra Agent ID, et ce guide la détaille. D'autres (AWS Bedrock AgentCore, Google Vertex AI) sont prévues et s'inséreront dans la même procédure. Pour toute plateforme sans connecteur natif, la voie de l'enregistrement entrant fonctionne déjà : la plateforme pousse ses agents vers une API, sans aucune app registration à créer de votre côté.

Un connecteur est-il le bon choix ? Oui lorsqu'un annuaire détient déjà votre liste d'agents et que vous voulez la recopier. Si en revanche votre plateforme d'agents sait appeler une API au moment où elle provisionne un agent, le modèle « push » décrit dans enregistrement entrant est plus simple. Les deux peuvent coexister — ils utilisent des espaces de noms d'identité distincts, donc un même agent importé par les deux voies apparaîtrait deux fois.

Prérequis

Il faut des droits des deux côtés, et ils sont généralement détenus par deux personnes différentes. Vérifiez les deux avant de commencer. Ce qu'il faut en face dépend de la plateforme que vous connectez ; la ligne ci-dessous concerne Microsoft Entra, la plateforme disponible aujourd'hui — une autre plateforme demanderait ses propres identifiants de service à la place d'une app registration.

Côté	Ce qu'il vous faut	Pourquoi
L'annuaire source (Microsoft Entra aujourd'hui)	Pour Entra : le droit de créer une app registration, plus un Administrateur de rôle privilégié ou un Administrateur général pour accorder le consentement	Le connecteur lit les identités d'agents de la plateforme avec ses propres identifiants de service. Pour Entra, il s'agit d'une permission d'application, qui ne prend effet qu'une fois qu'un administrateur a consenti au nom de tout le tenant.
Vaks PM	Le droit `agent:manage` — détenu par tout administrateur d'organisation, ou par un utilisateur portant le grant orthogonal Administrateur IA	Tous les écrans d'agents et de connecteurs sont derrière ce seul droit. Il ne peut jamais être détenu par un agent lui-même.
Vaks PM	Au moins un utilisateur humain actif à désigner comme propriétaire par défaut	Tout agent doit appartenir à un humain actif. Entra n'expose pas de propriétaire pour les identités d'agents : sans propriétaire par défaut, chaque agent est ignoré.

Si vous êtes administrateur IA plutôt qu'administrateur global, ouvrez la liste déroulante du propriétaire par défaut avant de commencer. La remplir exige de pouvoir lister les utilisateurs ; si votre grant ne le couvre pas, la liste s'affiche vide et le reste silencieusement. Vous pourrez enregistrer le connecteur, et il n'importera alors rien du tout. Faites créer le connecteur par un administrateur global, ou faites-lui renseigner le propriétaire par défaut.

Étape 1 — Dans Microsoft Entra

Vous créez une app registration dédiée dont l'unique rôle est de lire la liste des agents. Elle s'authentifie en son nom propre — aucun utilisateur n'est impliqué, personne ne se connecte — via le flux OAuth 2.0 client credentials.

1.1 Créer l'app registration

Rendez-vous dans Centre d'administration Microsoft Entra → Identité → Applications → Inscriptions d'applications → Nouvelle inscription.

Nom : quelque chose qui rende son objet évident à qui l'auditera plus tard, par exemple Vaks PM — sync annuaire d'agents.
Types de comptes pris en charge : mono-tenant (comptes de cet annuaire d'organisation uniquement).
URI de redirection : laissez vide. Cette application ne reçoit jamais de redirection navigateur.

Une fois l'inscription faite, copiez deux valeurs depuis la page Vue d'ensemble — vous collerez les deux dans Vaks PM :

ID d'annuaire (locataire) → le champ Tenant ID
ID d'application (client) → le champ Client ID

1.2 Accorder la permission Graph

Allez dans Autorisations d'API → Ajouter une autorisation → Microsoft Graph → Autorisations d'application, et ajoutez exactement une :

AgentIdentity.Read.All

Puis pressez Accorder le consentement administrateur pour <tenant> et vérifiez que la colonne d'état de la permission affiche Accordé. C'est l'étape la plus souvent oubliée : sans consentement, la permission est listée mais inerte, et le bouton Test du connecteur échouera avec un 403 explicite.

Pourquoi une permission d'application. Le connecteur s'exécute sans utilisateur connecté : les permissions déléguées ne s'appliquent donc pas. AgentIdentity.Read.All est en lecture seule et limitée aux identités d'agents — elle ne donne aucun accès aux utilisateurs, groupes, courriers ou fichiers. C'est toute la surface Graph que touche cette intégration.

1.3 Créer un secret client

Allez dans Certificats & secrets → Secrets client → Nouveau secret client, choisissez une échéance conforme à votre politique de rotation, et copiez immédiatement la Valeur du secret — Entra l'affiche une fois et plus jamais.

Renseignez la date d'expiration optionnelle pour être prévenu. Vaks PM ne peut pas savoir seul quand le secret Entra expire — le formulaire du connecteur a donc un champ optionnel Date d'expiration du secret. Saisissez la date qu'Entra affiche à la création du secret, et Vaks PM envoie un email à vos admins 14 jours avant l'échéance. Laissé vide, aucune alerte : le secret lapse en silence, Sync now échoue avec une erreur d'authentification et la recopie cesse d'avancer. La rotation prend deux minutes : créez un nouveau secret dans Entra, collez-le dans le connecteur, mettez à jour la date d'expiration, enregistrez.

1.4 Alternative — authentification par certificat (sans secret, sans expiration à surveiller)

Au lieu du secret client de l'étape 1.3, cette app registration peut s'authentifier par certificat (private_key_jwt) — voir la procédure détaillée dans le guide SSO OIDC (génération de la paire clé/certificat, upload du .cer, empreinte). C'est la même app Entra que celle de l'étape 1.1 : un seul certificat suffit si vous réutilisez cette app pour d'autres intégrations Entra de Vaks PM.

Contrairement au secret client, un certificat n'a pas de date d'expiration à suivre dans Vaks PM — le champ Date d'expiration du secret ne s'applique qu'au mode secret. Choisissez la durée de validité du certificat directement à sa création.

Étape 2 — Dans Vaks PM

Ouvrez Admin → Integrations → Agent directories et pressez Add directory. Choisissez Microsoft Entra Agent ID comme plateforme, puis remplissez le formulaire :

Champ	Valeur
Label	Texte libre, affiché dans la liste des connecteurs. Utile si vous en exploitez plusieurs.
Tenant ID (Entra)	Le GUID ID d'annuaire (locataire) de l'étape 1.1.
Client ID (app registration)	Le GUID ID d'application (client) de l'étape 1.1.
Client secret ou certificat	La Valeur du secret de l'étape 1.3, ou l'empreinte + la clé privée si vous utilisez l'authentification par certificat (étape 1.4). Chiffrés at-rest (AES-256-GCM) et jamais réaffichés. Laissez vide en modification pour conserver ce qui est déjà enregistré ; une clé privée renseignée prend le pas sur le secret.
Default owner for imported agents	Un humain actif qui devient propriétaire de chaque agent importé. Indispensable en pratique pour Entra — voir l'avertissement ci-dessous.
Enable this connector	Cochez-la. Sync now reste grisé tant que le connecteur n'est pas activé puis enregistré.

Renseignez un propriétaire par défaut, sinon vous n'importerez rien. Tout agent dans Vaks PM doit avoir un propriétaire humain actif. Les identités d'agents Entra n'en portent pas : le propriétaire par défaut est la seule source. Les agents sans propriétaire résoluble sont ignorés, et la synchronisation le dit : elle affiche Aucun import : N agent(s) ignoré(s) faute de propriétaire résolvable au lieu d'un succès. Renseignez le propriétaire par défaut et resynchronisez.

Les astérisques de champ obligatoire ne sont pas contrôlés à l'enregistrement. Un connecteur avec un Tenant ID ou un Client ID vide s'enregistre sans broncher ; le problème n'apparaît qu'au moment du Test. Exécutez toujours le test de l'étape 3 plutôt que de vous fier à un enregistrement réussi.

Deux contraintes à connaître avant de valider : le choix de la plateforme est immuable après création — en changer impose de supprimer puis recréer — et rien n'empêche de créer plusieurs connecteurs pour la même plateforme, donc vérifiez la liste avant d'en ajouter un en double.

Étape 3 — Tester, puis synchroniser

Pressez Test sur la carte du connecteur. L'opération obtient un jeton puis effectue un unique appel Graph minimal. Elle ne change rien et n'enregistre rien — lancez-la aussi souvent que vous voulez.

Résultat attendu : le message Connection OK.
Toute autre réponse signifie que le côté Entra n'est pas prêt. Rapprochez le message de la section Dépannage avant de continuer — synchroniser n'y changera rien.

Une fois le test passé, pressez Sync now. Le connecteur énumère les identités d'agents du tenant et les recopie.

Résultat attendu : Sync done: N created, 0 updated, 0 suspended à la première exécution, où N correspond au nombre d'agents de votre tenant.
La carte affiche ensuite Last sync avec un horodatage. Un échec est également conservé, sous forme d'une pastille Last sync failed suivie du motif.
Relancer est sans danger. Les agents sont rapprochés sur leur identifiant d'objet Entra : une deuxième synchronisation met à jour au lieu de dupliquer.

Confirmez ensuite le résultat là où il compte : Admin → Users & Identity → Agents doit maintenant lister les agents importés, chacun avec son propriétaire et le niveau de confiance Draft only.

Deux limites à connaître. Une synchronisation énumère au plus 500 agents et chaque appel Graph expire au bout de 10 secondes. Au-delà de 500, le surplus est tronqué silencieusement. Et comme il n'y a pas de planificateur, un agent ajouté dans Entra aujourd'hui n'apparaîtra dans Vaks PM que lorsque quelqu'un synchronisera — une synchronisation périodique a donc sa place dans la procédure qui couvre l'arrivée de vos agents.

Étape 4 — Activer un agent

Un agent importé existe mais reste inerte. Il n'a pas de jeton, ne peut pas se connecter, ne peut pas recevoir de mot de passe local, ne consomme aucun siège de licence, et porte une seule capacité : read:project. C'est délibéré — l'import est une étape de gouvernance, pas une étape d'autorisation, et rien dans Entra ne permet de la court-circuiter.

Pour mettre un agent au travail, ouvrez Admin → Users & Identity → Agents, sélectionnez-le, puis :

Confirmez le propriétaire. Le propriétaire par défaut du connecteur s'applique à tous les agents qu'il a importés ; réattribuez agent par agent pour que la responsabilité retombe sur la personne qui l'exploite réellement.
Réglez le niveau de confiance et les capacités au minimum nécessaire. Les capacités sont un plafond dur : les droits effectifs d'un agent sont les permissions de son rôle intersectées avec les scopes de son jeton intersectées avec ses capacités. La finance, les données clients, l'administration et la saisie de temps ne peuvent jamais être accordées à un agent, quoi que vous cochiez.
Émettez un jeton API. Le secret n'est affiché qu'une seule fois — capturez-le à cet instant. Une expiration est obligatoire, par défaut 90 jours.

À partir de là, les actions de l'agent lui sont attribuées dans le journal d'audit en tant que AGENT, aux côtés de l'identité de son propriétaire : chaque action reste traçable jusqu'à un humain responsable.

Distribuer un jeton à la main ne passe pas à l'échelle. Émettre un jeton manuellement convient pour quelques agents. Au-delà — ou dès que l'agent tourne sur une plateforme capable de prouver sa propre identité (Kubernetes, Entra / Copilot Studio / Foundry, GitHub Actions) — laissez l'agent s'authentifier sans secret distribué. Voir Authentification des agents pour la fédération et les identifiants machine rotatifs.

Alternative — enregistrement entrant

Si votre plateforme d'agents n'est pas Entra, ou si vous préférez qu'elle annonce ses agents au fil de leur provisionnement, utilisez le modèle « push ». Il ne demande aucune app registration.

Dans Admin → Integrations → Agent directories, sous Inbound — a platform declares its agents, utilisez la carte Agent registration API pour créer une clé d'organisation. La clé est automatiquement limitée au seul scope agent:manage ; une expiration est obligatoire (un an par défaut, deux ans au maximum).

Votre plateforme appelle alors :

POST /api/v1/agents
Authorization: Bearer vaks_org_<votre-clé>
Content-Type: application/json

{
  "name": "Agent de rédaction docs",
  "externalId": "agent-8842",
  "ownerEmail": "proprietaire@exemple.com",
  "modelProvider": "anthropic",
  "model": "claude-opus-4-8",
  "hostingRegion": "eu-west"
}

name, externalId et ownerEmail sont obligatoires ; les trois derniers champs sont des métadonnées descriptives facultatives. L'appel est idempotent sur externalId : réenregistrer le même agent le met à jour au lieu d'en créer un doublon — la réponse renvoie created: true ou false pour que l'appelant sache ce qui s'est passé.

ownerEmail doit correspondre à un humain actif de l'organisation, sans quoi l'appel est rejeté en 400. Comme avec le connecteur, l'agent arrive en Draft only avec read:project et sans jeton : un humain doit toujours l'activer.

L'enregistrement crée l'identité, pas le profil de coût. Les champs model et modelProvider ne sont que des métadonnées descriptives — ils ne portent aucun tarif. Ce qu'un agent coûte se règle à part, soit dans Admin → Agents, soit par API (ci-dessous), et ce qu'il consomme se déclare par run. Le cycle complet est : enregistrer (identité) → fixer le coût → activer (un humain émet le jeton) → exécuter et déclarer le coût.

Fixer le coût interne d'un agent par API

Vous pouvez maintenir le coût interne en tokens d'un agent aligné sur les tarifs de votre fournisseur depuis la même intégration, sans ouvrir le panneau d'administration. Avec une clé d'organisation scopée agent:manage — le même type de clé que l'enregistrement ci-dessus :

PATCH /api/v1/agents/cost-profile
Authorization: Bearer vaks_org_<votre-clé>
Content-Type: application/json

{
  "externalId": "agent-8842",
  "costRateInPerKTokens": 0.006,
  "costRateOutPerKTokens": 0.03
}

L'agent est retrouvé par externalId, la même clé que l'enregistrement. Les deux taux sont en devise par 1000 tokens ; au moins un est requis, et null efface un taux. La réponse est l'agent mis à jour, et le changement est écrit dans le journal d'audit avec les anciennes et nouvelles valeurs.

Ceci fixe le coût interne uniquement — jamais le taux facturé au client. Les deux taux internes sont ce que le modèle vous coûte (entrée et sortie). Le taux que vous facturez à un client (defaultBillRatePerKTokens) n'est délibérément pas accepté ici : une clé d'organisation ne fixe pas votre prix de vente. Il reste dans Admin → Agents, sous contrôle finance. Si le même externalId existe sur plusieurs sources, l'appel renvoie 409 — ajoutez idpSource pour désambiguïser.

Dépannage

Les messages sont affichés dans la langue de votre interface. Ils sont reproduits ci-dessous en français pour que vous puissiez les rapprocher exactement.

Message	Cause & correctif
Accès refusé (403) — la permission application AgentIdentity.Read.All manque (consentement admin requis).	La permission a été ajoutée mais jamais consentie, ou consentie en déléguée au lieu d'application. Reprenez l'étape 1.2 et vérifiez que la colonne d'état affiche Accordé.
Authentification Entra refusée : …	Le Tenant ID, le Client ID ou le secret client est erroné, ou le secret a expiré. Le texte qui suit est l'explication de Microsoft et désigne généralement lequel. Le secret expiré est la cause la plus fréquente sur un connecteur qui fonctionnait.
Configuration incomplète (tenantId / clientId / clientSecret)	Un champ est resté vide à l'enregistrement. Cela peut aussi signifier que le secret stocké est devenu illisible après une rotation de clé de chiffrement — dans ce cas, ressaisissez simplement le secret et enregistrez.
Connecteur désactivé — activez-le avant de synchroniser.	Cochez Enable this connector et enregistrez. Test fonctionne sur un connecteur désactivé ; Sync now non.
Délai dépassé en joignant Microsoft.	Graph n'a pas répondu en 10 secondes. Généralement passager — réessayez. Si cela persiste, vérifiez l'accès réseau sortant et tout proxy de sortie entre l'instance et `graph.microsoft.com`.
Réponse Graph inattendue (HTTP n) / Énumération Graph échouée (HTTP n)	Graph a répondu avec un statut inattendu. Un 429 signale une limitation de débit — attendez et réessayez. Tout autre code mérite d'être remonté au support avec la ligne Last sync du connecteur.
La synchronisation affiche Aucun import : N agent(s) ignoré(s) faute de propriétaire résolvable	Le propriétaire par défaut manque : tous les agents ont été ignorés faute de propriétaire. Renseignez-le et resynchronisez.
La synchronisation affiche 0 créé(s), 0 mis à jour, 0 suspendu(s) sans aucun ignoré	Le tenant ne contient réellement aucune identité d'agent — à confirmer avec Test, qui réussit dans les deux cas.
defaultOwnerId invalide : humain ACTIF requis.	Le propriétaire choisi est suspendu, supprimé, ou est lui-même un agent. Choisissez un humain actif.

Ce qui est journalisé

Chaque étape décrite ici laisse une trace d'audit, consultable sous Admin → Security & Compliance → Journal d'audit et exportable vers votre SIEM :

Action	Enregistré
Connecteur créé, modifié, supprimé	L'acteur et le connecteur concerné. Les secrets sont expurgés — le secret client n'atteint jamais le journal d'audit.
Synchronisation	La plateforme, plus le décompte des agents créés, mis à jour, suspendus et ignorés. Le message à l'écran indique lui aussi le décompte des ignorés ; le journal d'audit le conserve une fois le message disparu.
Cycle de vie d'un agent	Création, suspension, changements de capacités et de niveau de confiance, émission et révocation de jetons — le tout en sévérité critique.
Activité d'un agent	Chaque action d'un agent est attribuée au type d'acteur `AGENT` avec l'identité de son propriétaire, et peut être filtrée sur cette base.

À lire aussi : toutes les intégrations · produit & fonctionnalités pour le modèle de gouvernance des agents · chiffrement & clés pour la protection des secrets de connecteur at-rest.