io.enterpriseai.resources.RunsClient
Source : sdks/java/enterprise-ai-java/src/main/java/io/enterpriseai/resources/RunsClient.java. Retour à l'index de la référence du SDK Java.
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 RunsClient
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.
Constructeur RunsClient
RunsClient(Transport transport)
Crée le client sur le transport partagé ; EnterpriseAIClient le construit, on y accède par l'accesseur du même nom.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
transport | Transport | oui | Transport partagé par les sous-clients d'un même client. |
RunsClient.addStep
JsonNode addStep(String id, Object body)
Déclarer une étape d'un run. Enregistre une étape déclarée par le runtime et renvoie la décision du Loop Controller : run_state, next_kind, retry, backoff_seconds, error, approval_id et les budgets. Demande tenant_admin, developer ou agent. Étapes : 1. Le Kill Switch Registry et, pour une étape sensible, la chaîne de délégation, la session et la politique sont vérifiés. 2. Un run pending passe à running ; tout autre état que running répond 409 run_not_running. 3. L'usage et le coût s'ajoutent à la consommation de budget (coût dans la devise du run, sinon 400 invalid_request). 4. Une étape qui correspond à autonomy.human_approval_for sans approval_id reste pending, une approbation est ouverte et le run passe à waiting_approval ; une étape de type approval à l'état pending ouvre une approbation avec quorum. 5. Les budgets, le nombre maximal d'étapes et les nouvelles tentatives décident de l'état suivant (failed ou timed_out en cas de dépassement).
Route : /v1/runs/{run_id}/steps (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | String | oui | Identifiant (UUID) du run. | |
body | Object | oui | L'étape : type, état, usage, coût, erreur et indications d'état du run. |
Retour : JsonNode. Réponse JSON décodée de l'opération « Déclarer une étape d'un run ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RunsClient.addStep
JsonNode addStep(String id, Object body, RequestOptions options)
Déclarer une étape d'un run. Enregistre une étape déclarée par le runtime et renvoie la décision du Loop Controller : run_state, next_kind, retry, backoff_seconds, error, approval_id et les budgets. Demande tenant_admin, developer ou agent. Étapes : 1. Le Kill Switch Registry et, pour une étape sensible, la chaîne de délégation, la session et la politique sont vérifiés. 2. Un run pending passe à running ; tout autre état que running répond 409 run_not_running. 3. L'usage et le coût s'ajoutent à la consommation de budget (coût dans la devise du run, sinon 400 invalid_request). 4. Une étape qui correspond à autonomy.human_approval_for sans approval_id reste pending, une approbation est ouverte et le run passe à waiting_approval ; une étape de type approval à l'état pending ouvre une approbation avec quorum. 5. Les budgets, le nombre maximal d'étapes et les nouvelles tentatives décident de l'état suivant (failed ou timed_out en cas de dépassement).
Route : /v1/runs/{run_id}/steps (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | String | oui | Identifiant (UUID) du run. | |
body | Object | oui | L'étape : type, état, usage, coût, erreur et indications d'état du run. | |
options | RequestOptions | oui | Options de l'appel (clé d'idempotence, traceparent, en-têtes, signal d'annulation). |
Retour : JsonNode. Réponse JSON décodée de l'opération « Déclarer une étape d'un run ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RunsClient.cancel
JsonNode cancel(String id)
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 |
|---|---|---|---|---|
id | 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).
RunsClient.cancel
JsonNode cancel(String id, Object body)
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 |
|---|---|---|---|---|
id | String | oui | Identifiant (UUID) du run. | |
body | Object | oui | Raison facultative de l'annulation. |
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).
RunsClient.events
SseStream events(String id)
Suivre les événements d'un run. Flux Server-Sent Events (text/event-stream) des événements du run : run.created, run.state, step.recorded, checkpoint.created, subagent.spawned. Chaque message porte id, event et data (type, data, at). Étapes : 1. Les événements déjà enregistrés après Last-Event-ID sont envoyés. 2. Sans follow, le flux se termine aussitôt ; avec follow=true, il interroge chaque seconde. 3. Le flux se termine par un événement end portant l'état (state) du run quand le run est terminé, quand timeout est écoulé ou quand le client se déconnecte. 404 run_not_found.
Route : /v1/runs/{run_id}/events (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | String | oui | Identifiant (UUID) du run. |
Retour : SseStream. Réponse JSON décodée de l'opération « Suivre les événements d'un run ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RunsClient.get
ExecutionContract get(String id)
Lire un run. Renvoie l'Execution Contract v1 du run : agent et version, tâche, état, étapes, limites et consommation de budget, erreurs, politique de nouvelle tentative, informations de reprise et trace. 404 run_not_found.
Route : /v1/runs/{run_id} (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | String | oui | Identifiant (UUID) du run. |
Retour : ExecutionContract. Réponse JSON décodée de l'opération « Lire un run ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RunsClient.getRaw
JsonNode getRaw(String id)
Lire un run. Renvoie l'Execution Contract v1 du run : agent et version, tâche, état, étapes, limites et consommation de budget, erreurs, politique de nouvelle tentative, informations de reprise et trace. 404 run_not_found.
Route : /v1/runs/{run_id} (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | String | oui | Identifiant (UUID) du run. |
Retour : JsonNode. Réponse JSON décodée de l'opération « Lire un run ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RunsClient.list
Page<JsonNode> list()
Lister les runs. Runs du tenant, du plus récent au plus ancien, paginés avec cursor. Filtres : agent_id (identifiant ou nom ; agent en est un alias), state, session_id, parent_run_id. Un état inconnu ou un UUID mal formé répond 400 invalid_request.
Route : /v1/runs (GET).
Cet élément ne prend aucun paramètre.
Retour : Page<JsonNode>. Réponse JSON décodée de l'opération « Lister les runs ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RunsClient.list
Page<JsonNode> list(Map<String, ?> query)
Lister les runs. Runs du tenant, du plus récent au plus ancien, paginés avec cursor. Filtres : agent_id (identifiant ou nom ; agent en est un alias), state, session_id, parent_run_id. Un état inconnu ou un UUID mal formé répond 400 invalid_request.
Route : /v1/runs (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
query | Map<String, ?> | oui | Paramètres de la chaîne de requête de la route. |
Retour : Page<JsonNode>. Réponse JSON décodée de l'opération « Lister les runs ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RunsClient.replay
JsonNode replay(String id)
Rejouer un run. Renvoie l'historique complet d'un run pour revue : son Execution Contract, ses étapes, ses points de reprise, les événements d'audit qui le citent et une timeline unique triée par date (événements du run et d'audit). Demande tenant_admin, developer, agent, auditor ou security_officer. Lecture seule : rien n'est réexécuté.
Route : /v1/runs/{run_id}/replay (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | String | oui | Identifiant (UUID) du run. |
Retour : JsonNode. Réponse JSON décodée de l'opération « Rejouer un run ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RunsClient.resume
JsonNode resume(String id)
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 |
|---|---|---|---|---|
id | String | oui | Identifiant (UUID) du run. |
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).
RunsClient.resume
JsonNode resume(String id, 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 |
|---|---|---|---|---|
id | 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).
RunsClient.spawnSubagent
JsonNode spawnSubagent(String id, 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 |
|---|---|---|---|---|
id | 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).
RunsClient.spawnSubagent
JsonNode spawnSubagent(String id, Object body, RequestOptions options)
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 |
|---|---|---|---|---|
id | String | oui | Identifiant (UUID) du run parent. | |
body | Object | oui | Agent enfant, tâche et budget. | |
options | RequestOptions | oui | Options de l'appel (clé d'idempotence, traceparent, en-têtes, signal d'annulation). |
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).
RunsClient.start
JsonNode start(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).
RunsClient.start
JsonNode start(String agentId, Object body, RequestOptions options)
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. | |
options | RequestOptions | oui | Options de l'appel (clé d'idempotence, traceparent, en-têtes, signal d'annulation). |
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).
RunsClient.steps
JsonNode steps(String id)
Lister les étapes d'un run. Étapes du run dans l'ordre, chacune avec seq, type, état, tentative, jetons, coût et erreur le cas échéant. Une seule page. 404 run_not_found.
Route : /v1/runs/{run_id}/steps (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | String | oui | Identifiant (UUID) du run. |
Retour : JsonNode. Réponse JSON décodée de l'opération « Lister les étapes d'un run ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RunsClient.subagents
JsonNode subagents(String id)
Lister les runs de sous-agents. Résumés des runs enfants lancés par ce run, du plus ancien au plus récent. Une seule page. 404 run_not_found.
Route : /v1/runs/{run_id}/subagents (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | String | oui | Identifiant (UUID) du run parent. |
Retour : JsonNode. Réponse JSON décodée de l'opération « Lister les runs de sous-agents ».
Erreurs levées : les erreurs typées du transport (Erreurs).