Référence ExecutionContext

English version: ../../en/guides/execution-context.md

Cette page décrit l'ExecutionContext signé que reçoit chaque exécution, comment l'autorité de contexte l'émet et le vérifie, et comment valider un document selon son contrat. Qui : développeurs d'agents, d'outils et de serveurs MCP qui doivent vérifier pour qui ils agissent, et responsables de la sécurité.

Contrat

Le schéma est contracts/v1/execution-context.schema.json (Execution Context v1). Champs obligatoires : schema_version, execution, tenant, identity, workload_identity, delegation, authorization, security, limits, audit, context_integrity. Champs optionnels : agent, data_governance, models, prompts, tools, rag, multimodal, approvals, storage, observability, finops, runtime_control.

Blocs principaux

execution : execution_id, environment, started_at, status, entrypoint (obligatoires), plus request_id, correlation_id, deadline_at. tenant : tenant_id obligatoire, organization_id, project_id. identity : subject_id, subject_type, provider, token_reference. authorization : enforcement, default_decision, fail_closed, plus openfga, opa, effective_rights, break_glass. limits : max_duration_seconds, max_steps, max_subagents, max_depth, max_tool_calls, max_cost, heartbeat_seconds. context_integrity : issuer, issued_at, expires_at, audience, canonicalization, signing_algorithm, key_id, signature.

Émission et vérification

L'autorité de contexte (services/control-plane/src/eai/domains/context/authority.py) signe un JWS compact dont l'en-tête et la charge sont du JSON canonique RFC 8785, en ES256 ou EdDSA. Routes : POST /v1/context/issue, POST /v1/context/verify, GET /v1/context/jwks (vérification hors ligne), POST /v1/context/{context_id}/revoke. La durée de vie par défaut est EAI_CONTEXT_TTL_SECONDS (900 s), bornée par EAI_CONTEXT_MAX_TTL_SECONDS (3600 s) et par la délégation ; la clé est référencée par EAI_CONTEXT_SIGNING_KEY_REF. Sans clé, l'émission échoue fermée (503 context_authority_unavailable).

const ctx = await client.context.issue({ run_id: "run_1", ttl_seconds: 300 });
await client.context.verify({ token: String(ctx.token) });
const jwks = await client.context.jwks();

Procédures

1. Émettre un contexte pour une exécution. L'exécution et chaque outil qu'elle appelle partagent alors une même déclaration signée du tenant, de l'identité, de la délégation et des limites.

   API : POST /v1/context/issue avec run_id, et en option delegation_id, audience et ttl_seconds.

   Résultat attendu : un jeton dont la durée de vie est ttl_seconds (EAI_CONTEXT_TTL_SECONDS par défaut), ramenée à l'expiration de la délégation quand elle finit plus tôt.

   En cas d'échec : 400 context_ttl_exceeded signale un ttl_seconds inférieur à 30 ou supérieur à EAI_CONTEXT_MAX_TTL_SECONDS ; 503 context_authority_unavailable signale qu'aucune clé de signature n'est utilisable ; 403 delegation_expired signale une délégation qui finit avant le début possible du contexte.

2. Vérifier un contexte reçu par un outil. Un outil ou un serveur MCP ne fait jamais confiance à un contexte qu'il n'a pas vérifié : signature, émetteur, audience, durée de vie, tenant et révocation sont tous contrôlés.

   API : POST /v1/context/verify avec le token. Hors ligne : récupérez une fois les clés publiques avec GET /v1/context/jwks et vérifiez le JWS localement.

   Résultat attendu : le document décodé, chaque contrôle réussi.

   En cas d'échec : 401 avec l'un des codes du tableau de dépannage ; chaque refus écrit un événement d'audit context.verify.

3. Révoquer un contexte. La révocation met fin à un contexte avant son expiration, par exemple quand une exécution est arrêtée ou qu'un identifiant fuit.

   API : POST /v1/context/{context_id}/revoke. Les clés de signature se listent avec GET /v1/context/keys et se révoquent avec POST /v1/context/keys/{kid}/revoke.

   Résultat attendu : la vérification suivante de ce contexte répond 401 context_revoked.

   En cas d'échec : 404 context_not_found signale un contexte inconnu ; 403 forbidden signale que vous ne l'avez pas créé et ne détenez ni tenant_admin ni security_officer.

4. Valider un document selon le contrat. Utilisez-le dans vos tests pour prouver que les documents construits ou conservés suivent le schéma ; voir la section suivante.

   Résultat attendu : le document est valide.

   En cas d'échec : la CLI liste chaque erreur avec son chemin JSON.

Réglages

Réglage	Défaut	Rôle
EAI_CONTEXT_TTL_SECONDS	900	durée de vie par défaut d'un contexte
EAI_CONTEXT_MAX_TTL_SECONDS	3600	borne haute d'une durée de vie et de la fenêtre d'une clé retirée
EAI_CONTEXT_SIGNING_KEY_REF	aucun	référence de la clé de signature
EAI_CONTEXT_ISSUER	urn:eai:context-authority	émetteur écrit dans le jeton et contrôlé
EAI_CONTEXT_AUDIENCES	eai-control-plane	audiences acceptées par POST /v1/context/verify, séparées par des virgules
EAI_CONTEXT_LEEWAY_SECONDS	30	tolérance d'horloge des contrôles de durée de vie
EAI_CONTEXT_REQUIRED	false	chaque exécution exige un contexte signé

Valider un document

Un ExecutionContext se valide localement avec le SDK ou à distance avec POST /v1/contracts/{name}/validate.

enterprise-ai validate -f context.json --contract execution-context

Dépannage

Statut	Code	Cause	Correction
503	context_authority_unavailable	aucune clé de signature utilisable	configurez EAI_CONTEXT_SIGNING_KEY_REF
400	context_ttl_exceeded	durée de vie sous 30 s ou au-dessus du maximum	demandez une durée dans les bornes
400, 401	context_wrong_audience	aucune audience, ou une audience non acceptée	utilisez une audience de EAI_CONTEXT_AUDIENCES
401	context_malformed	structure, encodage ou durée de vie abîmés	envoyez le jeton tel qu'émis
401	context_invalid_signature	algorithme, signature ou empreinte faux	le jeton a été modifié : refusez-le
401	context_unknown_key	identifiant de clé absent du JWKS	relisez GET /v1/context/jwks
401	context_wrong_issuer	émetteur différent de EAI_CONTEXT_ISSUER	vérifiez la plateforme émettrice
401	context_expired	durée de vie écoulée	émettez un nouveau contexte
401	context_revoked	contexte ou délégation révoqué	arrêtez l'action ; n'émettez un nouveau contexte qu'avec une délégation valide
403	context_tenant_mismatch	contexte d'un autre tenant	utilisez l'identifiant du bon tenant

Étapes suivantes

• Référence ActionContext : la décision enregistrée pour chaque action.
• Référence API
• Guide de développement MCP : vérifier le contexte dans un serveur MCP.