Aller au contenu principal

Outils

L'écran Outils vous permet de lister les outils du registre, de changer leur description, leur propriétaire et leur statut de cycle de vie, de les supprimer, d'invoquer un outil par la Tool Gateway (portées, politique, DLP, approbation et coût) et de lire les invocations récentes. Chemin dans le portail : /capabilities/tools. Les développeurs enregistrent et testent les outils ; les administrateurs du tenant et les responsables sécurité décident de leur statut. L'écran est dessiné par portal/src/screens/capabilities.tsx.

Ce que montre l'écran​

La page compte quatre blocs, de haut en bas :

  • Tableau Outils, lu par GET /v1/tools (tous les outils en un appel). Colonnes : Nom, Version, Propriétaire, Risque, Statut, Mis à jour. Un clic sur une ligne, ou Voir le détail, ouvre un panneau latéral avec GET /v1/tools/{name}. Vide : Aucun outil enregistré, aide Appliquez un manifeste Tool ci-dessous pour enregistrer un outil.
  • Testeur Invoquer un outil : Nom (obligatoire), Arguments (JSON, obligatoire), Classification des données (public, internal, confidential, restricted), Finalité, Identifiant d'exécution, le bouton Exécuter et une zone Résultat (Lancez la requête pour voir le résultat ici. avant le premier appel).
  • Tableau Invocations récentes, lu par GET /v1/tools/invocations (50 lignes par appel, pagination par curseur). Colonnes : Outil, Version de l'outil, Acteur, Statut, Identifiant de décision, Durée (ms), Créé. Filtres Outil, Statut (succeeded, failed, denied, pending_approval, rate_limited, blocked) et Identifiant d'exécution. Voir le détail affiche la ligne. Vide : Aucune invocation.
  • Panneau Appliquer un manifeste prérempli avec un exemple de manifeste Tool (portal/src/samples/tool-manifest.json), avec Rétablir l'exemple et Appliquer.

Actions​

Bouton ou actionCe qu'il faitAppel d'APIRôles
Actualiser (icône, chaque tableau)Recharge le tableau.GET /v1/tools / GET /v1/tools/invocationsTout membre du tenant
Clic sur une ligne ou Voir le détail (outils)Ouvre la fiche de l'outil.GET /v1/tools/{name}Relation viewer sur l'outil
Menu ModifierFormulaire Description, Propriétaire, Statut (draft, approved, restricted, deprecated, blocked). Un passage à approved ouvre une approbation de promotion ; les autres statuts s'appliquent tout de suite.PATCH /v1/tools/{name}Statut : tenant_admin, security_officer ; autres champs : tenant_admin, developer, application_owner ; relation editor
Menu SupprimerOuvre Confirmer une action destructive ; saisissez le nom de l'outil, puis Confirmer.GET /v1/lineage/graph, puis DELETE /v1/tools/{name}tenant_admin et relation owner
Exécuter (Invoquer un outil)Appelle l'outil par la Tool Gateway et affiche la réponse dans Résultat.POST /v1/tools/{name}/invoketenant_admin, developer, agent et relation can_invoke
Filtrer (invocations)Applique les filtres Outil, Statut et Identifiant d'exécution.GET /v1/tools/invocationsTout membre du tenant
Menu Voir le détail (invocations)Affiche la ligne de l'invocation.AucunTout membre du tenant
Rétablir l'exemple / AppliquerRemet l'exemple / applique le manifeste Tool.POST /v1/manifests/applytenant_admin, developer
Réessayer (état d'erreur)Relance la lecture qui a échoué.Même appelMêmes rôles

Le testeur envoie ce corps ; les champs facultatifs vides ne sont pas envoyés :

{"arguments": {"po_number": "PO-2026-0042"}, "data_classification": "internal", "purpose": "invoice check", "run_id": "<run-id>"}

<run-id> : identifiant facultatif de l'exécution à laquelle appartient l'appel.

La Tool Gateway vérifie dans l'ordre le statut de l'outil, les portées, les arguments contre le schéma de l'outil, la classification des données, la politique, la DLP et l'approbation. Quand une approbation est nécessaire, la réponse est 202 avec status: pending_approval et un approval_id ; la demande apparaît dans la Boîte d'approbation. Le testeur n'a pas de champ approval_id : une fois l'approbation accordée, l'appel est renvoyé avec approval_id depuis le SDK ou l'API.

Rôles​

Le portail ne masque aucun bouton. Dans services/control-plane/src/eai/domains/tools/routes.py : la liste et les invocations demandent un tenant ; un changement de statut demande tenant_admin ou security_officer, les autres modifications WRITE_ROLES (tenant_admin, developer, application_owner) ; la suppression demande tenant_admin ; l'invocation demande OPS_ROLES (tenant_admin, developer, agent). Chaque route contrôle aussi la relation sur l'outil (viewer, editor, owner, can_invoke). platform_admin passe tous les contrôles de rôle.

Tâches courantes​

Enregistrer un outil et le tester​

  1. Appliquer le manifeste. Un outil n'existe qu'une fois son manifeste appliqué. Dans Appliquer un manifeste, collez votre manifeste Tool, puis cliquez sur Appliquer. Résultat attendu : Manifeste appliqué ; après Actualiser, l'outil figure dans le tableau avec sa version et son statut. En cas d'échec : corrigez les erreurs listées sous l'éditeur.
  2. L'invoquer. Le testeur passe par la même passerelle que les agents. Dans Invoquer un outil, saisissez le Nom, les Arguments en JSON, choisissez une Classification des données, puis cliquez sur Exécuter. Résultat attendu : la réponse de l'outil dans Résultat, et une nouvelle ligne dans Invocations récentes. En cas d'échec : lisez le code d'erreur dans Résultat (tool_blocked, invalid_arguments, policy_denied, dlp_blocked).
  3. Vérifier l'invocation. Chaque appel est journalisé avec sa décision de politique. Filtrez Invocations récentes sur l'outil. Résultat attendu : la ligne affiche Statut, Identifiant de décision et Durée (ms). En cas d'échec : cliquez sur Actualiser du tableau.

Approuver un outil pour la production​

  1. Demander la promotion. Le passage à approved demande une seconde personne. Dans le menu de ligne, cliquez sur Modifier, choisissez Approuvé dans Statut, puis cliquez sur Modifier. Résultat attendu : le message Terminé ; le statut ne change pas et une demande promotion apparaît dans la Boîte d'approbation. En cas d'échec : forbidden signifie que vous n'êtes ni tenant_admin ni security_officer.
  2. La faire approuver. La séparation des tâches s'applique. Demandez à un autre approbateur d'approuver la demande. Résultat attendu : l'outil affiche Approuvé. En cas d'échec : la promotion peut être refusée par le contrôle de risque ou par une suite d'évaluation bloquante.

Bloquer tout de suite un outil dangereux​

  1. Changer le statut. Les retraits s'appliquent sans approbation. Dans le menu de ligne, cliquez sur Modifier, choisissez Bloqué, puis cliquez sur Modifier. Résultat attendu : le statut Bloqué ; toute nouvelle invocation répond tool_blocked. En cas d'échec : vérifiez votre rôle (tenant_admin ou security_officer).

Dépannage​

SymptômeCauseCorrection
tool_not_found (404) : « Outil ... introuvable. »Le nom est faux ou l'outil a été supprimé.Copiez le nom depuis le tableau Outils.
tool_blocked (403)Le statut de l'outil est blocked.Demandez à un responsable sécurité de changer le statut.
invalid_arguments (422)Les arguments ne respectent pas le schéma d'entrée de l'outil.Lisez errors dans la réponse et corrigez les chemins indiqués.
classification_exceeded (403)La classification des données dépasse ce que l'agent peut traiter.Utilisez une classification plus basse ou un agent autorisé pour celle-ci.
insufficient_scope (403)L'identifiant de connexion n'a pas une portée exigée par l'outil.Utilisez un identifiant qui porte les required_scopes.
policy_denied (403) avec decision_idUne politique a refusé l'appel.Lisez la décision sur l'écran Journal des décisions avec le decision_id.
dlp_blocked (403)Les arguments contiennent des données sensibles que la DLP bloque.Retirez ou masquez ces données.
Réponse 202 avec pending_approvalL'appel demande une approbation humaine.Approuvez-le dans la Boîte d'approbation, puis rappelez avec approval_id.
upstream_unavailable ou upstream_error (502)Le service derrière l'outil ne répond pas ou a échoué.Vérifiez le point d'accès de l'outil.

Pages liées​