io.enterpriseai.interfaces.SdkInterfaces

Source : sdks/java/enterprise-ai-java/src/main/java/io/enterpriseai/interfaces/SdkInterfaces.java. Retour à l'index de la référence du SDK Java.

remarque

Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.

Classe SdkInterfaces

Les seize interfaces de la référence d'architecture (section B9.3) sur des routes documentées de la Control Plane. Règle : une autorisation n'est rapportée que si le serveur a répondu un booléen explicite ; toute erreur se propage. Usage : SdkInterfaces api = SdkInterfaces.of(client); api.authz().checkBatch(...).

Constructeur SdkInterfaces

SdkInterfaces(Transport t)

Constructeur privé : l'instance se crée avec SdkInterfaces.of(client).

Nom	Type	Défaut	Requis	Description
t	Transport		oui	Transport du client, obtenu par client.transport().

SdkInterfaces.agent

Agent agent()

Interface Agent : runs d'agent : lancement, annulation, point de reprise et reprise.

Cet élément ne prend aucun paramètre.

Retour : Agent. Un Agent : Agents. Registre des agents du tenant et exécution côté serveur de leurs runs : étapes, budgets, points de reprise, heartbeats, sous-agents, messages d'agent à agent (A2A), sessions de conversation, planifications cron, déclencheurs sur événement et exécutions en sandbox.

SdkInterfaces.approval

Approval approval()

Interface Approval : approbations humaines : demande, consultation et annulation.

Cet élément ne prend aucun paramètre.

Retour : Approval. Un Approval : Validations. Humain dans la boucle : demandes de validation des actions sensibles, avec séparation des tâches, quorum et expiration. Les exécutions d'agents qui atteignent un outil soumis à validation, les promotions de modèles, d'agents, d'outils, de compétences, de serveurs MCP ou de plugins, les accès d'urgence et les mandats créent tous leurs demandes de validation ici.

SdkInterfaces.audit

Audit audit()

Interface Audit : piste d'audit : consultation, vérification des preuves et événements applicatifs.

Cet élément ne prend aucun paramètre.

Retour : Audit. Une nouvelle instance de Audit sur le transport du client.

SdkInterfaces.authz

Authz authz()

Interface Authz : vérifications de relations avec décision confirmée, jamais d'autorisation par défaut.

Cet élément ne prend aucun paramètre.

Retour : Authz. Une nouvelle instance de Authz sur le transport du client.

SdkInterfaces.delegation

Delegation delegation()

Interface Delegation : chaînes de délégation : création, vérification, restriction et révocation.

Cet élément ne prend aucun paramètre.

Retour : Delegation. Une nouvelle instance de Delegation sur le transport du client.

SdkInterfaces.finops

Finops finops()

Interface Finops : consultation du budget, réservation de quota et enregistrement de la consommation.

Cet élément ne prend aucun paramètre.

Retour : Finops. Un Finops : FinOps. Gestion des coûts de l'usage de l'IA : grilles tarifaires, événements d'usage, estimations, quotas et réservations, répartition du coût des GPU, rapprochement de la facturation et alertes.

SdkInterfaces.identity

Identity identity()

Interface Identity : identité de l'appelant, vérification des contextes d'exécution et endossement d'une identité de service.

Cet élément ne prend aucun paramètre.

Retour : Identity. Une nouvelle instance de Identity sur le transport du client.

SdkInterfaces.llm

Llm llm()

Interface Llm : appels de modèles via l'AI Gateway : chat, flux SSE, embeddings et vision.

Cet élément ne prend aucun paramètre.

Retour : Llm. Une nouvelle instance de Llm sur le transport du client.

SdkInterfaces.mcp

Mcp mcp()

Interface Mcp : serveurs MCP via la passerelle JSON-RPC : initialisation, liste des outils et appel d'un outil.

Cet élément ne prend aucun paramètre.

Retour : Mcp. Un Mcp : Passerelle MCP. Registre des serveurs MCP amont (Model Context Protocol) et MCP Gateway, un proxy JSON-RPC 2.0 qui applique les contrôles de la plateforme à chaque appel : isolation par projet, appelants permis, listes d'autorisation d'outils et de ressources, scopes, DLP, politique, quota, contrôle d'injection de prompt, comptage et audit.

SdkInterfaces.privacy

Privacy privacy()

Interface Privacy : détection et masquage DLP, tokenisation et chiffrement.

Cet élément ne prend aucun paramètre.

Retour : Privacy. Un Privacy : Vie privée et protection des données. Services de protection des données du tenant : classification, DLP (prévention des fuites de données), tokenisation et chiffrement par enveloppe.

SdkInterfaces.rag

Rag rag()

Interface Rag : bases de connaissances : ingestion, recherche, résultats filtrés par ACL et citations.

Cet élément ne prend aucun paramètre.

Retour : Rag. Un Rag : Bases de connaissances. Bases de connaissances pour la génération augmentée par récupération (RAG) : les documents sont analysés, extraits, contrôlés pour les données personnelles et l'empoisonnement, découpés, vectorisés via le Model Gateway et recherchés avec des filtres d'ACL et d'habilitation.

SdkInterfaces.security

Security security()

Interface Security : posture de sécurité, déclaration d'incident et annulation de run.

Cet élément ne prend aucun paramètre.

Retour : Security. Une nouvelle instance de Security sur le transport du client.

SdkInterfaces.storage

Storage storage()

Interface Storage : objets d'un profil de stockage : URL présignées, liste, suppression et vérification.

Cet élément ne prend aucun paramètre.

Retour : Storage. Un Storage : Stockage. Profils de stockage : les buckets et conteneurs du client dans lesquels la plateforme écrit (exports d'audit, preuves, documents, médias, exports, sauvegardes), avec leur référence d'identifiants et leurs capacités découvertes par de vrais appels.

SdkInterfaces.subagent

Subagent subagent()

Interface Subagent : runs de sous-agents d'un run parent : création, délégation et annulation.

Cet élément ne prend aucun paramètre.

Retour : Subagent. Un Subagent : Agents. Registre des agents du tenant et exécution côté serveur de leurs runs : étapes, budgets, points de reprise, heartbeats, sous-agents, messages d'agent à agent (A2A), sessions de conversation, planifications cron, déclencheurs sur événement et exécutions en sandbox.

SdkInterfaces.tools

Tools tools()

Interface Tools : découverte et invocation des outils, validation d'une invocation d'outil.

Cet élément ne prend aucun paramètre.

Retour : Tools. Une nouvelle instance de Tools sur le transport du client.

SdkInterfaces.trace

Trace trace()

Interface Trace : spans côté client envoyés à POST /v1/telemetry/spans.

Cet élément ne prend aucun paramètre.

Retour : Trace. Un Trace : Télémétrie. Traces, journal des requêtes, flux en direct et objectifs de niveau de service (SLO) de la plateforme.

Classe SdkInterfaces.Agent

Agents. Registre des agents du tenant et exécution côté serveur de leurs runs : étapes, budgets, points de reprise, heartbeats, sous-agents, messages d'agent à agent (A2A), sessions de conversation, planifications cron, déclencheurs sur événement et exécutions en sandbox.

Agent.cancel

JsonNode cancel(String runId)

Annuler un run. Fait passer le run à cancelled avec l'erreur cancelled ; ses runs de sous-agents actifs sont aussi annulés. Demande tenant_admin, developer, agent ou security_officer. Un run déjà terminé répond 409 invalid_transition. Audité sous run.transition.

Route : /v1/runs/{run_id}/cancel (POST).

Nom	Type	Défaut	Requis	Description
runId	String		oui	Identifiant (UUID) du run.

Retour : JsonNode. Réponse JSON décodée de l'opération « Annuler un run ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Agent.checkpoint

JsonNode checkpoint(String runId, Object body)

Enregistrer un point de reprise. Enregistre un état du run avec le numéro de séquence suivant et la séquence d'étape courante, pour que le run puisse reprendre à partir de là. Demande tenant_admin, developer ou agent. Refusé avec 409 run_finished sur un run succeeded ou cancelled. Émet checkpoint.created ; audité sous run.checkpoint.

Route : /v1/runs/{run_id}/checkpoints (POST).

Nom	Type	Défaut	Requis	Description
runId	String		oui	Identifiant (UUID) du run.
body	Object		oui	État à enregistrer et libellé facultatif.

Retour : JsonNode. Réponse JSON décodée de l'opération « Enregistrer un point de reprise ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Agent.resume

JsonNode resume(String runId, Object body)

Reprendre un run. Ramène à running un run suspended, failed, timed_out ou waiting_input (sinon 409 invalid_transition). Demande tenant_admin, developer ou agent ; l'agent doit être actif (409 agent_not_active). Stratégies : 1. from_last_checkpoint (par défaut, sauf pour waiting_input) : reprendre depuis checkpoint_id ou le dernier point de reprise (409 no_checkpoint s'il n'y en a pas). 2. restart_step (par défaut pour waiting_input) : rejouer l'étape courante. 3. restart_run : tout recommencer avec la consommation de budget remise à zéro. Un run en échec sur budget_exceeded, max_steps_exceeded, killed ou approval_rejected ne peut utiliser que restart_run (409 run_not_resumable). Renvoie le run et le point de reprise utilisé.

Route : /v1/runs/{run_id}/resume (POST).

Nom	Type	Défaut	Requis	Description
runId	String		oui	Identifiant (UUID) du run.
body	Object		oui	Point de reprise et stratégie de reprise facultatifs.

Retour : JsonNode. Réponse JSON décodée de l'opération « Reprendre un run ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Agent.run

JsonNode run(String agentId, Object body)

Lancer un run d'un agent. Crée un run et renvoie son Execution Contract (201). Demande tenant_admin, developer ou agent, le scope agents:run et la relation ReBAC can_invoke. Étapes : 1. L'agent doit être active (sinon 409 agent_not_active, audité comme refus). 2. La politique agent.run est évaluée avec le risque, le propriétaire et la finalité de l'agent et la data_classification de la tâche (403 policy_denied). 3. Le budget est celui du manifeste, resserré par budgets (une requête ne peut jamais l'élargir ; 422 invalid_budget). 4. La délégation et l'identité de workload sont rattachées, le run est créé en pending (ou running avec start=true) et audité sous run.create. Une Idempotency-Key répétée renvoie le premier run ; la même clé pour un autre agent répond 409 idempotency_conflict. Un session_id inconnu répond 404 session_not_found.

Route : /v1/agents/{agent_id}/runs (POST).

Nom	Type	Défaut	Requis	Description
agentId	String		oui	Identifiant (UUID) ou nom de l'agent.
body	Object		oui	Tâche du run, session facultative, budget, politique de nouvelle tentative et délégation.

Retour : JsonNode. Réponse JSON décodée de l'opération « Lancer un run d'un agent ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Approval

Validations. Humain dans la boucle : demandes de validation des actions sensibles, avec séparation des tâches, quorum et expiration. Les exécutions d'agents qui atteignent un outil soumis à validation, les promotions de modèles, d'agents, d'outils, de compétences, de serveurs MCP ou de plugins, les accès d'urgence et les mandats créent tous leurs demandes de validation ici.

Approval.cancel

JsonNode cancel(String id, String reason)

Annuler une demande de validation. Retire une demande en attente. Autorisé à son demandeur, à un tenant_admin ou à un security_officer (403 forbidden sinon, le refus étant audité). La demande finit cancelled et son sujet réagit comme à un refus : une exécution en attente échoue (approval_cancelled), un accès d'urgence ou un mandat en attente est refusé. Une demande qui n'est plus en attente répond 409 approval_closed. Écrit l'événement d'audit approval.cancel avec la raison. La réponse porte run_state quand une exécution est rattachée.

Route : /v1/approvals/{approval_id}/cancel (POST).

Nom	Type	Défaut	Requis	Description
id	String		oui	Identifiant (UUID) de la demande de validation.
reason	String		oui	Raison du retrait, 3 à 2000 caractères. Inscrite dans le journal d'audit.

Retour : JsonNode. Réponse JSON décodée de l'opération « Annuler une demande de validation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Approval.check

JsonNode check(String id)

Lire une demande de validation. Renvoie une demande de validation avec ses décisions (valideur, décision, commentaire, date) et approvals_count. Une demande en attente dont l'expiration est passée est marquée expired et son exécution en attente échoue. Ouvert à tout membre du tenant. Répond 404 approval_not_found.

Route : /v1/approvals/{approval_id} (GET).

Nom	Type	Défaut	Requis	Description
id	String		oui	Identifiant (UUID) de la demande de validation.

Retour : JsonNode. Réponse JSON décodée de l'opération « Lire une demande de validation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Approval.request

JsonNode request(Object body)

Demander une validation. Crée une demande de validation en attente. Exige tenant_admin, developer, agent, security_officer ou finops.

Route : /v1/approvals (POST).

Nom	Type	Défaut	Requis	Description
body	Object		oui	Action, ressource, quorum, valideurs et expiration de la demande.

Retour : JsonNode. Réponse JSON décodée de l'opération « Demander une validation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Audit

Piste d'audit : consultation, vérification des preuves et événements applicatifs.

Audit.query

JsonNode query(Map<String, ?> filters)

Rechercher les événements d'audit. Recherche les événements d'audit du tenant, les plus récents d'abord (séquence la plus haute d'abord), paginés. Tous les filtres se combinent. Exige auditor, security_officer ou tenant_admin. La recherche elle-même est inscrite dans le journal d'accès aux preuves (qui, quelle requête, combien de résultats).

Route : /v1/audit/events (GET).

Nom	Type	Défaut	Requis	Description
filters	Map<String, ?>		oui	Filtres de requête de GET /v1/audit/events, peut être null.

Retour : JsonNode. Réponse JSON décodée de l'opération « Rechercher les événements d'audit ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Audit.record

JsonNode record(Object event)

Enregistrer un événement d'audit applicatif. Ajoute un événement applicatif à la chaîne de hachage du tenant. L'acteur vient de l'authentification ; la séquence, les empreintes et occurred_at viennent du serveur ; les details du client sont conservés sous evidence.details.attributes, à côté de stream: sdk. L'événement est scellé et exporté vers la boîte d'envoi et le SIEM comme les événements de la plateforme.

Route : /v1/audit/events (POST).

Nom	Type	Défaut	Requis	Description
event	Object		oui	Événement applicatif (action app.) à sceller dans la chaîne du tenant.

Retour : JsonNode. Réponse JSON décodée de l'opération « Enregistrer un événement d'audit applicatif ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Audit.verifyEvidence

JsonNode verifyEvidence()

Vérifier la chaîne et tous les sceaux. Vérifie toute la chaîne du tenant et tous ses sceaux et renvoie tenant_id, valid, chain (résultat de la chaîne de hachage), seals (nombre et échecs), clock (échecs d'horodatage) et events (nombre vérifié). Exige auditor, security_officer ou tenant_admin. La vérification est inscrite dans le journal d'accès.

Route : /v1/evidence/verify (GET).

Cet élément ne prend aucun paramètre.

Retour : JsonNode. Réponse JSON décodée de l'opération « Vérifier la chaîne et tous les sceaux ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Authz

Vérifications de relations avec décision confirmée, jamais d'autorisation par défaut.

Authz.check

Decision check(Check c)

Vérifier une relation. Indique si subject détient relation sur object, en suivant l'héritage. Jusqu'à 20 contextual_tuples sont tenus pour vrais pour cette seule vérification et jamais enregistrés (un tuple invalide répond 422 validation_error). Ouvert à tout membre du tenant. La réponse donne allowed, engine, subject, relation et object. Écrit l'événement d'audit authz.check avec la décision. Quand le moteur ne peut pas répondre, la décision est un refus, elle est auditée et l'API répond 502 authz_backend_error.

Route : /v1/authz/check (POST).

Nom	Type	Défaut	Requis	Description
c	Check		oui	Vérification de relation sujet, relation, objet à envoyer.

Retour : Decision. Réponse JSON décodée de l'opération « Vérifier une relation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Authz.checkBatch

List<Decision> checkBatch(List<Check> checks)

Vérifier une relation. Indique si subject détient relation sur object, en suivant l'héritage. Jusqu'à 20 contextual_tuples sont tenus pour vrais pour cette seule vérification et jamais enregistrés (un tuple invalide répond 422 validation_error). Ouvert à tout membre du tenant. La réponse donne allowed, engine, subject, relation et object. Écrit l'événement d'audit authz.check avec la décision. Quand le moteur ne peut pas répondre, la décision est un refus, elle est auditée et l'API répond 502 authz_backend_error.

Route : /v1/authz/check (POST).

Nom	Type	Défaut	Requis	Description
checks	List<Check>		oui	Vérifications envoyées une par une ; la première erreur arrête le lot.

Retour : List<Decision>. Réponse JSON décodée de l'opération « Vérifier une relation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Authz.explain

JsonNode explain(Object body)

Autoriser une action sous une délégation. Calcule la permission effective d'une action : utilisateur ET agent ET délégation ET restriction de ressource ET relation (OpenFGA ou les tuples intégrés) ET politique (OPA ou intégrée). Donnez delegation_id, ou run_id pour utiliser la délégation d'une exécution (400 invalid_request sans l'un ni l'autre ; 403 delegation_required pour une exécution sans délégation).

Route : /v1/delegations/authorize (POST).

Nom	Type	Défaut	Requis	Description
body	Object		oui	Action, délégation ou exécution, et la portée, la ressource, la relation, l'audience et la classification à vérifier.

Retour : JsonNode. Réponse JSON décodée de l'opération « Autoriser une action sous une délégation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Modèle SdkInterfaces.Check

Une vérification de relation et sa réponse confirmée.

Champs :

Nom	Type	Requis	Description
subject	String	oui	Sujet de la vérification, par exemple user:alice.
relation	String	oui	Relation vérifiée entre le sujet et l'objet.
object	String	oui	Objet vérifié, <type>:<id>, par exemple project:42.

Modèle SdkInterfaces.Decision

Décision confirmée d'une vérification : la vérification, allowed et le moteur qui a répondu.

Champs :

Nom	Type	Requis	Description
check	Check	oui	Une vérification de relation et sa réponse confirmée.
allowed	boolean	oui	Booléen explicite allowed renvoyé par le serveur.
engine	String	oui	Auto (par défaut), HPA ou KEDA.

Classe SdkInterfaces.Delegation

Chaînes de délégation : création, vérification, restriction et révocation.

Delegation.create

JsonNode create(Object body)

Créer une délégation. Crée une délégation racine de l'appelant vers un délégataire. Ouvert aux membres du tenant ; un agent ne peut pas créer seul une délégation racine (403 delegation_root_forbidden).

Route : /v1/delegations (POST).

Nom	Type	Défaut	Requis	Description
body	Object		oui	Délégataire, droits, limites et expiration de la délégation.

Retour : JsonNode. Réponse JSON décodée de l'opération « Créer une délégation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Delegation.restrict

JsonNode restrict(String id, Object body)

Restreindre une délégation pour un sous-délégataire. Crée une délégation enfant, toujours couverte par son parent : un sous-agent n'obtient jamais de droits plus larges. Autorisé à la racine ou au créateur du parent, à un agent, à un tenant_admin ou à un security_officer (403 forbidden).

Route : /v1/delegations/{delegation_id}/restrict (POST).

Nom	Type	Défaut	Requis	Description
id	String		oui	Identifiant (UUID) de la délégation parente.
body	Object		oui	Sous-délégataire et droits plus étroits.

Retour : JsonNode. Réponse JSON décodée de l'opération « Restreindre une délégation pour un sous-délégataire ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Delegation.revoke

JsonNode revoke(String id, Object body)

Révoquer une délégation. Révoque la délégation et tous ses descendants ; leurs contextes d'exécution sont révoqués avec eux, avec effet à l'action suivante. Autorisé à sa racine, à son créateur ou à la personne représentée, ainsi qu'à tenant_admin et security_officer (403 forbidden). Écrit l'événement d'audit delegation.revoke.

Route : /v1/delegations/{delegation_id}/revoke (POST).

Nom	Type	Défaut	Requis	Description
id	String		oui	Identifiant (UUID) de la délégation.
body	Object		oui	Raison facultative.

Retour : JsonNode. Réponse JSON décodée de l'opération « Révoquer une délégation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Delegation.verify

JsonNode verify(String token, String audience)

Vérifier un contexte d'exécution signé. Contrôle un jeton et renvoie valid, context_id, kid, alg, les revendications et le document de contexte. Contrôles, dans l'ordre : structure et forme canonique (context_malformed), algorithme et signature (context_invalid_signature), clé connue et non révoquée (context_unknown_key), émetteur (context_wrong_issuer), audience (context_wrong_audience), durée de vie (context_expired), tenant de l'appelant (403 context_tenant_mismatch), enregistrement d'émission (context_revoked), empreinte du document et chaîne de délégation (une délégation révoquée donne context_revoked). Les refus répondent 401 sauf mention contraire et sont audités ; un succès rattache l'identité vérifiée aux événements d'audit de la requête.

Route : /v1/context/verify (POST).

Nom	Type	Défaut	Requis	Description
token	String		oui	Le jeton JWS compact (10 à 65536 caractères).
audience	String		oui	Audience attendue par le vérificateur (200 caractères au plus). Par défaut : la première audience de la plateforme.

Retour : JsonNode. Réponse JSON décodée de l'opération « Vérifier un contexte d'exécution signé ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Finops

FinOps. Gestion des coûts de l'usage de l'IA : grilles tarifaires, événements d'usage, estimations, quotas et réservations, répartition du coût des GPU, rapprochement de la facturation et alertes.

Finops.checkBudget

JsonNode checkBudget()

Lire la consommation des quotas. Chaque quota du tenant avec sa fenêtre courante et le coût et les jetons consommés et réservés dans celle-ci. Les quotas par exécution demandent run pour trouver leur fenêtre. Demande un rôle de lecteur et un principal de tenant.

Route : /v1/quotas/usage (GET).

Cet élément ne prend aucun paramètre.

Retour : JsonNode. Réponse JSON décodée de l'opération « Lire la consommation des quotas ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Finops.recordUsage

JsonNode recordUsage(Object event)

Ingérer un événement d'usage. Valide un Usage Event v1, le valorise (coût mesuré dans la devise du tenant) et l'enregistre ; répond 201, ou 200 avec duplicate: true si le même event_id était déjà enregistré. Un événement invalide répond 422 usage_event_invalid avec les erreurs ; un événement d'un autre tenant 403 usage_tenant_mismatch. Un événement d'audit par appel, jamais le contenu. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.

Route : /v1/finops/usage (POST).

Nom	Type	Défaut	Requis	Description
event	Object		oui	Événement de consommation envoyé à POST /v1/finops/usage, par exemple un UsageEvent.

Retour : JsonNode. Réponse JSON décodée de l'opération « Ingérer un événement d'usage ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Finops.reserve

JsonNode reserve(Object body)

Réserver un coût et des jetons. Réserve un montant sur chaque quota actif correspondant à la portée (les quotas du tenant correspondent toujours ; un principal utilisateur ajoute sa propre portée utilisateur) et répond 201 avec la réservation, ses éléments par quota et fenêtre, les quotas souples dépassés et son échéance. Un quota strict qui serait dépassé répond 429 quota_exceeded avec Retry-After: 60, et rien n'est réservé. Les réservations expirées sont d'abord libérées. Audité. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.

Route : /v1/quotas/reserve (POST).

Nom	Type	Défaut	Requis	Description
body	Object		oui	Montant, portée et durée de vie de la réservation.

Retour : JsonNode. Réponse JSON décodée de l'opération « Réserver un coût et des jetons ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Identity

Identité de l'appelant, vérification des contextes d'exécution et endossement d'une identité de service.

Identity.assumeService

JsonNode assumeService(String identityId, String purpose, List<String> audience, Integer ttlSeconds, List<String> scopes)

#assumeService(String, String, List, Integer, List) avec les valeurs par défaut du serveur.

Route : /v1/service-identities/{identity_id}/assume (POST).

Nom	Type	Défaut	Requis	Description
identityId	String		oui	Identifiant de l'identité de service à endosser.
purpose	String		oui	Finalité déclarée de l'endossement, envoyée dans purpose.
audience	List<String>		oui	Services autorisés à accepter le contexte, 1 à 10 audiences connues. Null : l'audience par défaut de l'autorité de contexte.
ttlSeconds	Integer		oui	Durée de vie du contexte en secondes, de 30 à 3600 (900 par défaut).
scopes	List<String>		oui	Portées demandées, 50 au plus. Par défaut : les portées de l'identité. Chacune doit être accordée par l'identité et détenue par l'appelant.

Retour : JsonNode. La réponse du serveur, qui contient toujours un token non vide.

Erreurs levées : IncompleteResponseException, les erreurs typées du transport (Erreurs).

Identity.assumeService

JsonNode assumeService(String identityId, String purpose)

#assumeService(String, String, List, Integer, List) avec les valeurs par défaut du serveur.

Nom	Type	Défaut	Requis	Description
identityId	String		oui	Identifiant de l'identité de service à endosser.
purpose	String		oui	Finalité déclarée de l'endossement, envoyée dans purpose.

Retour : JsonNode. La réponse du serveur, qui contient toujours un token non vide.

Identity.current

JsonNode current()

Afficher l'identité appelante. Renvoie l'identité résolue par la plateforme pour cette requête, quel que soit l'identifiant (jeton OIDC, session du portail, clé d'API, SPIFFE) : id, kind (user, service, agent, system), tenant_id, tenant_slug, roles, scopes, clearance, auth_method et display. En lecture seule, ouvert à tout appelant authentifié, y compris quand un compte local doit encore changer son mot de passe. Utilisez-la pour vérifier un nouveau jeton ou une nouvelle clé.

Route : /v1/identity/whoami (GET).

Cet élément ne prend aucun paramètre.

Retour : JsonNode. Réponse JSON décodée de l'opération « Afficher l'identité appelante ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Identity.verify

JsonNode verify(String token, String audience)

Vérifier un contexte d'exécution signé. Contrôle un jeton et renvoie valid, context_id, kid, alg, les revendications et le document de contexte. Contrôles, dans l'ordre : structure et forme canonique (context_malformed), algorithme et signature (context_invalid_signature), clé connue et non révoquée (context_unknown_key), émetteur (context_wrong_issuer), audience (context_wrong_audience), durée de vie (context_expired), tenant de l'appelant (403 context_tenant_mismatch), enregistrement d'émission (context_revoked), empreinte du document et chaîne de délégation (une délégation révoquée donne context_revoked). Les refus répondent 401 sauf mention contraire et sont audités ; un succès rattache l'identité vérifiée aux événements d'audit de la requête.

Route : /v1/context/verify (POST).

Nom	Type	Défaut	Requis	Description
token	String		oui	Le jeton JWS compact (10 à 65536 caractères).
audience	String		oui	Audience attendue par le vérificateur (200 caractères au plus). Par défaut : la première audience de la plateforme.

Retour : JsonNode. Réponse JSON décodée de l'opération « Vérifier un contexte d'exécution signé ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.IncompleteResponseException

Levée quand un champ documenté est absent de la réponse.

EaiException

Constructeur IncompleteResponseException

IncompleteResponseException(String field)

Crée l'erreur 502 incomplete_response pour le champ manquant.

Nom	Type	Défaut	Requis	Description
field	String		oui	Nom du champ absent, repris dans le message.

Classe SdkInterfaces.Llm

Appels de modèles via l'AI Gateway : chat, flux SSE, embeddings et vision.

Llm.embed

JsonNode embed(Object body)

Calculer des embeddings. Embeddings compatibles OpenAI à travers les mêmes contrôles que la conversation (kill switches, listes d'autorisation, classification, DLP sur chaque entrée, garde-fous de coût, décision de politique, audit). Le modèle doit déclarer la capacité embeddings et, si dimensions est fourni, la prendre en charge (422 capability_not_supported, 422 embedding_dimensions_invalid). Demande un principal de tenant avec le scope models:invoke.

Route : /v1/gateway/embeddings (POST).

Nom	Type	Défaut	Requis	Description
body	Object		oui	Requête d'embeddings OpenAI (model, input sous forme de texte ou de liste, dimensions facultatif) plus l'objet facultatif eai.

Retour : JsonNode. Réponse JSON décodée de l'opération « Calculer des embeddings ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Llm.generate

JsonNode generate(Object body)

Appeler un modèle de conversation. Complétion de conversation compatible OpenAI à travers chaque contrôle de la passerelle ; avec stream: true la réponse est en Server-Sent Events, et les garde-fous de coût sont vérifiés pendant le flux. Demande un principal de tenant (403 platform_only) dont l'identifiant porte le scope models:invoke.

Route : /v1/gateway/chat/completions (POST).

Nom	Type	Défaut	Requis	Description
body	Object		oui	Requête de conversation OpenAI (model est l'identifiant du registre, messages, stream, max_tokens, tools...) plus l'objet facultatif eai : data_classification (public, internal par défaut, confidential, restricted, secret), agent_id, session_id, run_id, purpose, project_id, effort, max_cost, fallback_policy et des listes d'autorisation qui ne peuvent que restreindre celles du tenant (provider_allow, model_allow, region_allow).

Retour : JsonNode. Réponse JSON décodée de l'opération « Appeler un modèle de conversation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Llm.stream

io.enterpriseai.SseStream stream(Map<String, ?> body)

Appeler un modèle de conversation. Complétion de conversation compatible OpenAI à travers chaque contrôle de la passerelle ; avec stream: true la réponse est en Server-Sent Events, et les garde-fous de coût sont vérifiés pendant le flux. Demande un principal de tenant (403 platform_only) dont l'identifiant porte le scope models:invoke.

Route : /v1/gateway/chat/completions (POST).

Nom	Type	Défaut	Requis	Description
body	Map<String, ?>		oui	Requête de conversation OpenAI (model est l'identifiant du registre, messages, stream, max_tokens, tools...) plus l'objet facultatif eai : data_classification (public, internal par défaut, confidential, restricted, secret), agent_id, session_id, run_id, purpose, project_id, effort, max_cost, fallback_policy et des listes d'autorisation qui ne peuvent que restreindre celles du tenant (provider_allow, model_allow, region_allow).

Retour : io.enterpriseai.SseStream. Réponse JSON décodée de l'opération « Appeler un modèle de conversation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Llm.vision

JsonNode vision(Object body)

Analyser une image. Lance un travail d'analyse d'image sur un média image ou une image fournie directement avec un prompt (201, le travail). La réponse passe par la DLP avec dlp_mode. detail répond 422 parameter_unsupported quand le fournisseur configuré ne peut pas l'honorer ; une entrée qui n'est pas une image répond 422 unsupported_media. Demande tenant_admin, developer ou agent.

Route : /v1/multimodal/vision (POST).

Nom	Type	Défaut	Requis	Description
body	Object		oui	Image d'entrée, prompt, modèle, mode DLP et niveau de détail.

Retour : JsonNode. Réponse JSON décodée de l'opération « Analyser une image ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Mcp

Passerelle MCP. Registre des serveurs MCP amont (Model Context Protocol) et MCP Gateway, un proxy JSON-RPC 2.0 qui applique les contrôles de la plateforme à chaque appel : isolation par projet, appelants permis, listes d'autorisation d'outils et de ressources, scopes, DLP, politique, quota, contrôle d'injection de prompt, comptage et audit.

Mcp.connect

JsonNode connect(String serverId)

Appeler un serveur MCP via la passerelle. Proxy JSON-RPC 2.0. Le corps est une requête ou un lot (50 au plus sont traitées). Demande tenant_admin, developer ou agent et la relation ReBAC can_invoke. Les refus sont renvoyés comme erreurs JSON-RPC avec le statut HTTP 200, et audités. Contrôles, dans l'ordre : JSON-RPC 2.0 valide ; serveur active ; isolation par projet (mcp_server_project_mismatch) ; appelants permis (mcp_principal_not_allowed) ; une instance hébergée en sommeil est réveillée ; une application tierce doit être active et avoir reçu le serveur ; méthode permise ; pour tools/call : outil dans allowed_tools, scope tools:invoke, DLP sur les arguments ; politique mcp.call ; réservation de quota ; pour resources/read : URI dans allowed_resources. L'appel est ensuite transmis avec les identifiants amont ; tools/list et resources/list sont filtrés par les listes d'autorisation, les résultats de tools/call sont masqués par la DLP et contrôlés contre l'injection de prompt, et l'appel est compté comme usage d'outil.

Route : /v1/mcp/gateway/{server_id} (POST).

Nom	Type	Défaut	Requis	Description
serverId	String		oui	Identifiant (UUID) ou nom du serveur MCP.

Retour : JsonNode. Réponse JSON décodée de l'opération « Appeler un serveur MCP via la passerelle ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Mcp.invoke

JsonNode invoke(String serverId, String tool, Map<String, ?> arguments)

Appeler un serveur MCP via la passerelle. Proxy JSON-RPC 2.0. Le corps est une requête ou un lot (50 au plus sont traitées). Demande tenant_admin, developer ou agent et la relation ReBAC can_invoke. Les refus sont renvoyés comme erreurs JSON-RPC avec le statut HTTP 200, et audités. Contrôles, dans l'ordre : JSON-RPC 2.0 valide ; serveur active ; isolation par projet (mcp_server_project_mismatch) ; appelants permis (mcp_principal_not_allowed) ; une instance hébergée en sommeil est réveillée ; une application tierce doit être active et avoir reçu le serveur ; méthode permise ; pour tools/call : outil dans allowed_tools, scope tools:invoke, DLP sur les arguments ; politique mcp.call ; réservation de quota ; pour resources/read : URI dans allowed_resources. L'appel est ensuite transmis avec les identifiants amont ; tools/list et resources/list sont filtrés par les listes d'autorisation, les résultats de tools/call sont masqués par la DLP et contrôlés contre l'injection de prompt, et l'appel est compté comme usage d'outil.

Route : /v1/mcp/gateway/{server_id} (POST).

Nom	Type	Défaut	Requis	Description
serverId	String		oui	Identifiant (UUID) ou nom du serveur MCP.
tool	String		oui	Seulement les invocations de cet outil.
arguments	Map<String, ?>		oui	Arguments de l'outil MCP, envoyés comme corps JSON.

Retour : JsonNode. Réponse JSON décodée de l'opération « Appeler un serveur MCP via la passerelle ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Mcp.listTools

JsonNode listTools(String serverId)

Lister les outils d'un serveur MCP. Appelle tools/list sur le serveur via la passerelle et renvoie les outils permis par allowed_tools. Demande la relation ReBAC can_invoke et l'accès au projet du serveur. Une erreur amont répond 502 upstream_error.

Route : /v1/mcp/servers/{server_id}/tools (GET).

Nom	Type	Défaut	Requis	Description
serverId	String		oui	Identifiant (UUID) ou nom du serveur MCP.

Retour : JsonNode. Réponse JSON décodée de l'opération « Lister les outils d'un serveur MCP ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Privacy

Vie privée et protection des données. Services de protection des données du tenant : classification, DLP (prévention des fuites de données), tokenisation et chiffrement par enveloppe.

Privacy.detect

JsonNode detect(Object body)

Inspecter un texte à la recherche de données sensibles. Applique la DLP au texte avec les règles du tenant, en mode detect sauf si mode en décide autrement. La réponse donne text, findings (type, position, score, classification, court aperçu, action, règle), action (action la plus forte appliquée), classification, mode, engine (builtin ou presidio), blocked et count. Un mode inconnu répond 400. Ouvert à tout membre du tenant. Écrit l'événement d'audit dlp.inspect (nombres et types uniquement).

Route : /v1/dlp/inspect (POST).

Nom	Type	Défaut	Requis	Description
body	Object		oui	Texte, mode et langue facultatifs.

Retour : JsonNode. Réponse JSON décodée de l'opération « Inspecter un texte à la recherche de données sensibles ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Privacy.detokenize

JsonNode detokenize(Object body)

Détokeniser des valeurs. Renvoie les valeurs d'origine des jetons donnés dans tokens ou trouvés dans text.

Route : /v1/tokenization/detokenize (POST).

Nom	Type	Défaut	Requis	Description
body	Object		oui	Jetons ou texte contenant des jetons, et finalité.

Retour : JsonNode. Réponse JSON décodée de l'opération « Détokeniser des valeurs ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Privacy.encrypt

JsonNode encrypt(Object body)

Chiffrer des données avec une clé du tenant. Chiffre plaintext (texte UTF-8) ou plaintext_base64 (octets) avec la version courante de la clé, lié à aad. Renvoie ciphertext (eaienc1:...), key_id et key_version. L'une des deux entrées est obligatoire, et le base64 doit être valide (400 invalid_request) ; une clé inconnue répond 404 key_not_found. Ouvert à tout membre du tenant. Écrit l'événement d'audit encryption.encrypt (taille uniquement).

Route : /v1/encryption/encrypt (POST).

Nom	Type	Défaut	Requis	Description
body	Object		oui	Clé, données à chiffrer et données associées.

Retour : JsonNode. Réponse JSON décodée de l'opération « Chiffrer des données avec une clé du tenant ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Privacy.mask

JsonNode mask(String text)

Masquer les données sensibles d'un texte. Comme l'inspection, en mode mask par défaut : chaque constat est remplacé par [TYPE] (par exemple [EMAIL]), ou tokenisé ou bloqué quand une règle du tenant ou mode le demande ; un texte bloqué revient vide avec blocked: true. Ouvert à tout membre du tenant. Écrit l'événement d'audit dlp.redact.

Route : /v1/dlp/redact (POST).

Nom	Type	Défaut	Requis	Description
text	String		oui	Texte à inspecter ou à masquer.

Retour : JsonNode. Réponse JSON décodée de l'opération « Masquer les données sensibles d'un texte ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Privacy.tokenize

JsonNode tokenize(Object body)

Tokeniser des valeurs. Remplace les valeurs sensibles par des jetons déterministes tok_<type>_<hex> du tenant (une même valeur donne toujours le même jeton), les valeurs étant conservées chiffrées dans le coffre. Avec values, renvoie tokens ; avec text, détecte les entités et renvoie le text tokenisé, findings et classification. L'un des deux est obligatoire (400 invalid_request). Ouvert à tout membre du tenant. Écrit l'événement d'audit tokenization.tokenize (nombre uniquement).

Route : /v1/tokenization/tokenize (POST).

Nom	Type	Défaut	Requis	Description
body	Object		oui	Valeurs ou texte à tokeniser.

Retour : JsonNode. Réponse JSON décodée de l'opération « Tokeniser des valeurs ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Rag

Bases de connaissances. Bases de connaissances pour la génération augmentée par récupération (RAG) : les documents sont analysés, extraits, contrôlés pour les données personnelles et l'empoisonnement, découpés, vectorisés via le Model Gateway et recherchés avec des filtres d'ACL et d'habilitation.

Rag.cite

JsonNode cite(String kbId, Object body)

Citations des résultats de la requête.

Nom	Type	Défaut	Requis	Description
kbId	String		oui	Identifiant de la base de connaissances.
body	Object		oui	Corps de la requête, sérialisé en JSON.

Retour : JsonNode. Le champ citations de la réponse ; IncompleteResponseException quand il est absent.

Rag.ingest

JsonNode ingest(String kbId, Object body)

Ajouter un document. Ingère un document (201). Demande la relation ReBAC editor et le droit d'écriture par l'ACL (403 not_permitted_acl). Étapes : 1. Le contenu (content ou content_base64, l'un est requis, sinon 400) est analysé par ClamAV et YARA-X (422 file_blocked, 503 file_scan_unavailable), puis le texte est extrait par Docling (422 unsupported_media). 2. La détection de données personnelles peut relever la classification ; un source_connector doit être actif. 3. Un document de même uri remplace la version précédente (version + 1). 4. Le texte est découpé, vectorisé et enregistré ; le contrôle d'empoisonnement peut mettre le document en quarantaine (status: quarantined). 409 knowledge_base_reindexing pendant une réindexation ; 409 embedding_dimension_mismatch ; 503 vector_store_unavailable. Audité sous knowledge.document.ingest.

Route : /v1/knowledge-bases/{kb_id}/documents (POST).

Nom	Type	Défaut	Requis	Description
kbId	String		oui	Identifiant (UUID) de la base de connaissances.
body	Object		oui	Contenu, titre, URI, classification, lecteurs et métadonnées du document.

Retour : JsonNode. Réponse JSON décodée de l'opération « Ajouter un document ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Rag.retrieve

JsonNode retrieve(String kbId, Object body)

Résultats de la requête filtrés par ACL.

Nom	Type	Défaut	Requis	Description
kbId	String		oui	Identifiant de la base de connaissances.
body	Object		oui	Corps de la requête, sérialisé en JSON.

Retour : JsonNode. Le champ results de la réponse ; IncompleteResponseException quand il est absent.

Rag.search

JsonNode search(String kbId, Object body)

Interroger une base de connaissances. Recherche dans la base et renvoie results (fragment, score, risque d'injection, classification, provenance), citations et un lineage_run_id. Demande la relation ReBAC can_invoke. Étapes : 1. La politique knowledge.query est évaluée et une réservation de quota est prise. 2. La requête est vectorisée avec le modèle de la base ; seuls les fragments dont les lecteurs correspondent aux identités de l'appelant et dont la classification respecte son habilitation sont recherchés. 3. Les fragments trouvés sont contrôlés contre l'injection de prompt (écartés en mode blocage) et vérifiés par rapport aux sources actives. 4. hybrid recalcule le score des candidats avec le recouvrement de mots-clés ; rerank les ordonne avec un modèle de reranking (un refus est signalé dans warnings, jamais caché). Un appelant hors ACL obtient un résultat vide, audité comme refus. Audité sous knowledge.query ; l'usage est mesuré.

Route : /v1/knowledge-bases/{kb_id}/query (POST).

Nom	Type	Défaut	Requis	Description
kbId	String		oui	Identifiant (UUID) de la base de connaissances.
body	Object		oui	Texte de la requête et options de recherche.

Retour : JsonNode. Réponse JSON décodée de l'opération « Interroger une base de connaissances ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Security

Posture de sécurité, déclaration d'incident et annulation de run.

Security.cancelRun

JsonNode cancelRun(String runId)

Annuler un run. Fait passer le run à cancelled avec l'erreur cancelled ; ses runs de sous-agents actifs sont aussi annulés. Demande tenant_admin, developer, agent ou security_officer. Un run déjà terminé répond 409 invalid_transition. Audité sous run.transition.

Route : /v1/runs/{run_id}/cancel (POST).

Nom	Type	Défaut	Requis	Description
runId	String		oui	Identifiant (UUID) du run.

Retour : JsonNode. Réponse JSON décodée de l'opération « Annuler un run ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Security.checkState

JsonNode checkState()

Lire la posture de sécurité. Renvoie environment, generated_at, protections (méthodes d'authentification et autres protections en vigueur), checks (chacun avec son statut pass, warn ou fail, sa gravité et son message) et summary (nombre de contrôles par statut). Pour un appelant rattaché à un tenant, renvoie aussi tenant avec les réglages de sécurité du tenant, dont certains contrôles tiennent compte. Exige security_officer ou tenant_admin. En lecture seule.

Route : /v1/security/posture (GET).

Cet élément ne prend aucun paramètre.

Retour : JsonNode. Réponse JSON décodée de l'opération « Lire la posture de sécurité ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Security.reportIncident

JsonNode reportIncident(Object body)

Ouvrir un incident. Ouvre un incident au statut open, ajoute l'entrée created à la chronologie et le transmet au SIEM. Exige tenant_admin, security_officer, developer ou agent. Une gravité inconnue répond 400 invalid_request. Écrit l'événement d'audit incident.create. La réponse (201) porte l'incident avec sa chronologie.

Route : /v1/incidents (POST).

Nom	Type	Défaut	Requis	Description
body	Object		oui	Titre, gravité, description, catégorie, ressources et responsable.

Retour : JsonNode. Réponse JSON décodée de l'opération « Ouvrir un incident ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Span

Span côté client envoyé par Trace#endSpan.

Champs :

Nom	Type	Requis	Description
traceId	String	oui	Identifiant de trace (32 caractères hexadécimaux), généré quand il n'est pas donné.
spanId	String	oui	Identifiant aléatoire du span (16 caractères hexadécimaux).
parentSpanId	String	oui	Identifiant du span parent, ou null.
name	String	oui	Nom du span.

Classe SdkInterfaces.Storage

Stockage. Profils de stockage : les buckets et conteneurs du client dans lesquels la plateforme écrit (exports d'audit, preuves, documents, médias, exports, sauvegardes), avec leur référence d'identifiants et leurs capacités découvertes par de vrais appels.

Storage.delete

JsonNode delete(String profileId, String key, String versionId)

Supprimer un objet d'un profil. Supprime un objet (ou une de ses versions) à l'intérieur des préfixes de présignature du profil. Un profil qui sert audit_worm ou evidence ne supprime jamais par l'API (409 storage_object_protected) ; un refus de rétention du stockage est renvoyé tel quel. Demande tenant_admin, developer ou agent (profil de plateforme : platform_admin) et la décision de politique storage.object.delete ; audité avec la clé complète et la version. Autres erreurs : 403 storage_key_out_of_scope, 422 storage_key_invalid, 409 storage_profile_disabled.

Route : /v1/storage/profiles/{profile_id}/objects/delete (POST).

Nom	Type	Défaut	Requis	Description
profileId	String		oui	Identifiant (UUID) du profil de stockage.
key	String		oui	Clé de l'objet relative au préfixe de clé du profil, de 1 à 1024 caractères, dans un préfixe de présignature ; aucun caractère de contrôle, pas de / initial, aucun segment . ou ...
versionId	String		oui	Version de l'objet à supprimer sur un bucket versionné, de 1 à 1024 caractères. Omettez-la pour supprimer la version courante.

Retour : JsonNode. Réponse JSON décodée de l'opération « Supprimer un objet d'un profil ».

Erreurs levées : IncompleteResponseException, les erreurs typées du transport (Erreurs).

Storage.get

JsonNode get(String profileId, String key)

Émettre une URL présignée. Émet une URL présignée pour lire (GET) ou écrire (PUT) un objet directement dans le bucket, et répond 201 avec l'identifiant de l'autorisation, l'URL, la méthode, la clé complète, la durée de vie et l'échéance. La clé doit se trouver dans les préfixes de présignature (403 storage_key_out_of_scope) et le profil doit avoir une capacité presign vérifiée et récente (409 storage_capability_missing). La durée de vie ne peut dépasser EAI_STORAGE_PRESIGN_MAX_SECONDS (3600 par défaut, jamais plus de 604800 ; 422 storage_presign_expiry_invalid). Demande tenant_admin, developer ou agent (profil de plateforme : platform_admin) et la décision de politique storage.presign.read ou storage.presign.write. L'autorisation est enregistrée avec un SHA-256 de l'URL (jamais l'URL elle-même) et auditée.

Route : /v1/storage/profiles/{profile_id}/presign (POST).

Nom	Type	Défaut	Requis	Description
profileId	String		oui	Identifiant (UUID) du profil de stockage.
key	String		oui	Clé de l'objet relative au préfixe de clé du profil, de 1 à 1024 caractères, dans un préfixe de présignature du profil.

Retour : JsonNode. Réponse JSON décodée de l'opération « Émettre une URL présignée ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Storage.list

JsonNode list(String profileId, Map<String, ?> query)

Lister les objets d'un profil. Objets rangés sous un préfixe à l'intérieur des préfixes de présignature du profil : clé relative au préfixe de clé du profil (utilisable pour la présignature et la suppression), clé stockée, taille, ETag, type de contenu, SHA-256, version, dernière modification et classe de stockage. Demande tenant_admin, developer, agent ou auditor (profil de plateforme : platform_admin) et la décision de politique storage.object.list ; la liste est auditée. Erreurs : 422 storage_prefix_required si prefix est omis et que le profil n'a pas exactement un préfixe de présignature, 403 storage_key_out_of_scope hors des préfixes de présignature, 409 storage_profile_disabled.

Route : /v1/storage/profiles/{profile_id}/objects (GET).

Nom	Type	Défaut	Requis	Description
profileId	String		oui	Identifiant (UUID) du profil de stockage.
query	Map<String, ?>		oui	Paramètres de la chaîne de requête de la route.

Retour : JsonNode. Réponse JSON décodée de l'opération « Lister les objets d'un profil ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Storage.put

JsonNode put(String profileId, String key)

Émettre une URL présignée. Émet une URL présignée pour lire (GET) ou écrire (PUT) un objet directement dans le bucket, et répond 201 avec l'identifiant de l'autorisation, l'URL, la méthode, la clé complète, la durée de vie et l'échéance. La clé doit se trouver dans les préfixes de présignature (403 storage_key_out_of_scope) et le profil doit avoir une capacité presign vérifiée et récente (409 storage_capability_missing). La durée de vie ne peut dépasser EAI_STORAGE_PRESIGN_MAX_SECONDS (3600 par défaut, jamais plus de 604800 ; 422 storage_presign_expiry_invalid). Demande tenant_admin, developer ou agent (profil de plateforme : platform_admin) et la décision de politique storage.presign.read ou storage.presign.write. L'autorisation est enregistrée avec un SHA-256 de l'URL (jamais l'URL elle-même) et auditée.

Route : /v1/storage/profiles/{profile_id}/presign (POST).

Nom	Type	Défaut	Requis	Description
profileId	String		oui	Identifiant (UUID) du profil de stockage.
key	String		oui	Clé de l'objet relative au préfixe de clé du profil, de 1 à 1024 caractères, dans un préfixe de présignature du profil.

Retour : JsonNode. Réponse JSON décodée de l'opération « Émettre une URL présignée ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Storage.verify

JsonNode verify(String profileId)

Vérifier les capacités d'un profil. Découvre les capacités du bucket par de vrais appels et les enregistre. Demande tenant_admin ou security_officer (profil de plateforme : platform_admin) et la décision de politique storage.profile.verify. Un profil désactivé répond 409 storage_profile_disabled.

Route : /v1/storage/profiles/{profile_id}/verify (POST).

Nom	Type	Défaut	Requis	Description
profileId	String		oui	Identifiant (UUID) du profil de stockage.

Retour : JsonNode. Réponse JSON décodée de l'opération « Vérifier les capacités d'un profil ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Subagent

Agents. Registre des agents du tenant et exécution côté serveur de leurs runs : étapes, budgets, points de reprise, heartbeats, sous-agents, messages d'agent à agent (A2A), sessions de conversation, planifications cron, déclencheurs sur événement et exécutions en sandbox.

Subagent.cancel

JsonNode cancel(String childRunId)

Annuler un run. Fait passer le run à cancelled avec l'erreur cancelled ; ses runs de sous-agents actifs sont aussi annulés. Demande tenant_admin, developer, agent ou security_officer. Un run déjà terminé répond 409 invalid_transition. Audité sous run.transition.

Route : /v1/runs/{run_id}/cancel (POST).

Nom	Type	Défaut	Requis	Description
childRunId	String		oui	Identifiant (UUID) du run.

Retour : JsonNode. Réponse JSON décodée de l'opération « Annuler un run ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Subagent.delegate

JsonNode delegate(String parentRunId, String agent, Map<String, ?> task)

Lancer un run de sous-agent. Lance un run enfant depuis un parent pending ou running (sinon 409 run_not_running) et renvoie son Execution Contract. Demande tenant_admin, developer ou agent et le scope agents:run. Contrôles, dans l'ordre : le Kill Switch Registry ; la profondeur selon autonomy.max_depth (1 par défaut, 409 subagent_depth_exceeded) ; le nombre d'enfants selon autonomy.max_subagents (3 par défaut, 409 subagent_count_exceeded) ; l'agent enfant selon la liste subagents du manifeste parent (403 subagent_not_allowed) ; la délégation du parent. Le budget de l'enfant ne peut dépasser ce qu'il reste au parent, l'enfant rejoint la session du parent et un parent en cours enregistre une étape subagent.

Route : /v1/runs/{run_id}/subagents (POST).

Nom	Type	Défaut	Requis	Description
parentRunId	String		oui	Identifiant (UUID) du run parent.
agent	String		oui	Agent enfant, nom ou agent:<nom>. Par défaut : l'agent du run parent.
task	Map<String, ?>		oui	Tâche du run enfant (task_id, objective, input).

Retour : JsonNode. Réponse JSON décodée de l'opération « Lancer un run de sous-agent ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Subagent.spawn

JsonNode spawn(String parentRunId, Object body)

Lancer un run de sous-agent. Lance un run enfant depuis un parent pending ou running (sinon 409 run_not_running) et renvoie son Execution Contract. Demande tenant_admin, developer ou agent et le scope agents:run. Contrôles, dans l'ordre : le Kill Switch Registry ; la profondeur selon autonomy.max_depth (1 par défaut, 409 subagent_depth_exceeded) ; le nombre d'enfants selon autonomy.max_subagents (3 par défaut, 409 subagent_count_exceeded) ; l'agent enfant selon la liste subagents du manifeste parent (403 subagent_not_allowed) ; la délégation du parent. Le budget de l'enfant ne peut dépasser ce qu'il reste au parent, l'enfant rejoint la session du parent et un parent en cours enregistre une étape subagent.

Route : /v1/runs/{run_id}/subagents (POST).

Nom	Type	Défaut	Requis	Description
parentRunId	String		oui	Identifiant (UUID) du run parent.
body	Object		oui	Agent enfant, tâche et budget.

Retour : JsonNode. Réponse JSON décodée de l'opération « Lancer un run de sous-agent ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Tools

Découverte et invocation des outils, validation d'une invocation d'outil.

Tools.discover

JsonNode discover()

Lister les outils. Outils du tenant dans l'ordre des noms, éventuellement d'un seul statut. Une seule page.

Route : /v1/tools (GET).

Cet élément ne prend aucun paramètre.

Retour : JsonNode. Réponse JSON décodée de l'opération « Lister les outils ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Tools.invoke

JsonNode invoke(String name, Object body)

Invoquer un outil via la passerelle. Exécute la chaîne de la passerelle décrite dans l'introduction du tag et renvoie l'invocation : status, result masqué, error, duration_ms, decision_id, détections DLP, événement d'usage et coût. Demande tenant_admin, developer ou agent et la relation ReBAC can_invoke. Réponses : 200 une fois exécuté (aussi quand l'amont a échoué, voir status et error) ; 202 pending_approval avec approval_id quand une validation humaine est requise (rappelez avec l'approval_id approuvé et les mêmes arguments) ; 202 pour un outil sandbox, avec l'identifiant de l'exécution en sandbox. Erreurs : 403 tool_blocked, insufficient_scope, tool_not_granted, classification_exceeded, policy_denied, dlp_blocked ; 422 invalid_arguments ; 409 approval_consumed (une approbation sert un seul appel réussi) ; 429 rate_limited avec Retry-After: 60 ou quota_exceeded.

Route : /v1/tools/{name}/invoke (POST).

Nom	Type	Défaut	Requis	Description
name	String		oui	Nom de l'outil.
body	Object		oui	Arguments de l'appel et son contexte (run, agent, approbation, finalité, classification).

Retour : JsonNode. Réponse JSON décodée de l'opération « Invoquer un outil via la passerelle ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Tools.validate

JsonNode validate(Object invocation)

Valider un document avec un contrat. Valide le corps avec le contrat, formats compris, sans rien enregistrer. La réponse donne contract, valid et errors, chacune avec le path JSON de la valeur fautive et un message. Ouvert à tout appelant authentifié. Un contrat inconnu répond 404 unknown_contract.

Route : /v1/contracts/{name}/validate (POST).

Nom	Type	Défaut	Requis	Description
invocation	Object		oui	Invocation d'outil validée avec le contrat tool-invocation.

Retour : JsonNode. Réponse JSON décodée de l'opération « Valider un document avec un contrat ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SdkInterfaces.Trace

Télémétrie. Traces, journal des requêtes, flux en direct et objectifs de niveau de service (SLO) de la plateforme.

Trace.endSpan

JsonNode endSpan(Span span, String status)

Ingérer des spans de télémétrie. Accepte jusqu'à 5000 spans et répond 202 avec le nombre accepté, le nombre enregistré (un span déjà connu pour les mêmes identifiants de trace et de span est ignoré) et le résultat de chaque exportateur (ok ou error). Demande un principal de tenant avec tenant_admin, developer ou agent (403 forbidden).

Route : /v1/telemetry/spans (POST).

Nom	Type	Défaut	Requis	Description
span	Span		oui	Span à terminer ; un span déjà terminé lève IllegalStateException.
status	String		oui	Statut final du span, envoyé dans status.

Retour : JsonNode. Réponse JSON décodée de l'opération « Ingérer des spans de télémétrie ».

Erreurs levées : IllegalStateException, les erreurs typées du transport (Erreurs).

Trace.recordEvent

void recordEvent(Span span, String name, Map<String, ?> attributes)

Ajoute un événement horodaté au span, envoyé avec lui par endSpan.

Nom	Type	Défaut	Requis	Description
span	Span		oui	Span qui reçoit l'événement.
name	String		oui	Nom de l'événement.
attributes	Map<String, ?>		oui	Attributs de l'événement, peut être null.

Retour : void.

Trace.startSpan

Span startSpan(String name, String traceId, String parentSpanId, Map<String, ?> attributes)

Démarre un span local, horodaté maintenant ; rien n'est envoyé avant endSpan.

Nom	Type	Défaut	Requis	Description
name	String		oui	Nom du span.
traceId	String		oui	Identifiant de trace à reprendre, ou null pour en générer un.
parentSpanId	String		oui	Identifiant du span parent, ou null.
attributes	Map<String, ?>		oui	Attributs initiaux du span, copiés, peut être null.

Retour : Span. Un Span : span côté client envoyé par Trace#endSpan.

Classe SdkInterfaces.UnconfirmedDecisionException

Levée quand une réponse d'autorisation ne porte pas de décision explicite.

EaiException

Constructeur UnconfirmedDecisionException

UnconfirmedDecisionException()

Crée l'erreur 502 unconfirmed_decision.

Cet élément ne prend aucun paramètre.