enterprise_ai.agent.clients

Source : sdks/python/src/enterprise_ai/agent/clients.py. Retour à l'index de la référence du SDK Python.

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 AgentsClient

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.

Resource

AgentsClient.create

create(manifest: dict[str, Any]) -> Any

Enregistrer un agent ou une version. Applique un manifeste Agent : crée l'agent, ou ajoute une version à un agent existant et la rend courante. Le manifeste est validé selon le contrat v1 (422 invalid_manifest) ; le niveau de risque unacceptable est refusé (422 agent_risk_unacceptable) ; la même version avec un autre contenu est refusée (409 version_immutable). apply_status dans la réponse vaut created, version_added ou unchanged. Demande tenant_admin, developer ou application_owner ; l'appelant devient propriétaire ReBAC. Audité sous agent.apply.

Route : /v1/agents (POST).

Nom	Type	Défaut	Requis	Description
manifest	dict[str, Any]		oui	Agent Manifest envoyé comme corps de la requête.

Retour : Any. Réponse JSON décodée de l'opération « Enregistrer un agent ou une version ».

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

AgentsClient.delete

delete(agent_id: str) -> Any

Supprimer un agent. Supprime l'agent et ses versions. Demande le rôle tenant_admin et la relation ReBAC owner sur l'agent. Refusé avec 409 agent_has_active_runs tant qu'un run de l'agent est encore actif (en attente, en cours, en pause ou suspendu) ; 404 agent_not_found pour un agent inconnu. Audité sous agent.delete.

Route : /v1/agents/{agent_id} (DELETE).

Nom	Type	Défaut	Requis	Description
agent_id	str		oui	Identifiant (UUID) ou nom de l'agent.

Retour : Any. Réponse JSON décodée de l'opération « Supprimer un agent ».

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

AgentsClient.get

get(agent_id: str) -> Any

Lire un agent. Renvoie l'agent, le manifeste de sa version courante et runs, le nombre de ses runs par état. Demande la relation ReBAC viewer sur l'agent. 404 agent_not_found.

Route : /v1/agents/{agent_id} (GET).

Nom	Type	Défaut	Requis	Description
agent_id	str		oui	Identifiant (UUID) ou nom de l'agent.

Retour : Any. Réponse JSON décodée de l'opération « Lire un agent ».

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

AgentsClient.kill

kill(agent_id: str, reason: str | None = None) -> Any

Arrêter définitivement un agent. Kill switch : tous les runs actifs de l'agent sont annulés avec l'erreur killed et le statut de l'agent devient killed définitivement (il ne peut plus reprendre). Demande tenant_admin ou security_officer. 409 agent_killed s'il est déjà arrêté. La réponse liste affected_runs. Audité sous agent.kill.

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

Nom	Type	Défaut	Requis	Description
agent_id	str		oui	Identifiant (UUID) ou nom de l'agent.
reason	str | None	None	non	Raison de l'action. Inscrite dans le journal d'audit avec l'acteur et l'heure.

Retour : Any. Réponse JSON décodée de l'opération « Arrêter définitivement un agent ».

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

AgentsClient.list

list(**page: Any) -> Any

Lister les agents. Agents du tenant, dans l'ordre des noms, paginés avec cursor. Tout principal du tenant peut l'appeler.

Route : /v1/agents (GET).

Nom	Type	Défaut	Requis	Description
**page	Any		non	Options de pagination : limit (nombre maximal d'agents par page) et cursor (curseur de la page à lire).

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

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

AgentsClient.resume

resume(agent_id: str) -> Any

Demander la reprise d'un agent. Ouvre une approbation de promotion pour ramener un agent suspendu à active et répond 202 avec approval_id et status: pending_approval ; les approbateurs sont tenant_admin ou security_officer. Une fois approuvée, les runs suspendus par la suspension de l'agent reprennent. Demande tenant_admin ou security_officer. Refusé avec 409 agent_killed, ou 409 kill_switch_active tant qu'un confinement SOC retient l'agent (levé uniquement via POST /v1/soc/recoveries).

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

Nom	Type	Défaut	Requis	Description
agent_id	str		oui	Identifiant (UUID) ou nom de l'agent.

Retour : Any. Réponse JSON décodée de l'opération « Demander la reprise d'un agent ».

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

AgentsClient.run

run(agent_id: str, task: object = None, session_id: str | None = None, budgets: dict[str, Any] | None = None, start: bool | None = None, idempotency_key: str | None = None, **extra: Any) -> Any

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
agent_id	str		oui	Identifiant (UUID) ou nom de l'agent.
task	object	None	non	Tâche du run : task_id, objective, input sont conservés ; data_classification sert au contrôle de politique.
session_id	str | None	None	non	Session (UUID) à laquelle appartient le run.
budgets	dict[str, Any] | None	None	non	Limites de budget (par exemple jetons maximaux, max_cost avec montant et devise). Elles ne peuvent que resserrer le budget du manifeste de l'agent ; la devise doit être la même.
start	bool | None	None	non	Si vrai, le run démarre en running. Faux par défaut (pending jusqu'à la première étape).
idempotency_key	str | None	None	non	En-tête Idempotency-Key : une reprise avec la même clé rejoue la première réponse.
**extra	Any		non	Champs supplémentaires fusionnés dans le corps de la requête.

Retour : Any. 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).

AgentsClient.suspend

suspend(agent_id: str, reason: str | None = None) -> Any

Suspendre un agent. Kill switch réversible : le statut de l'agent devient suspended, ses runs actifs passent à suspended et les nouveaux runs sont refusés. Demande tenant_admin ou security_officer. 409 agent_killed pour un agent arrêté. La réponse liste affected_runs. Audité sous agent.suspend.

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

Nom	Type	Défaut	Requis	Description
agent_id	str		oui	Identifiant (UUID) ou nom de l'agent.
reason	str | None	None	non	Raison de l'action. Inscrite dans le journal d'audit avec l'acteur et l'heure.

Retour : Any. Réponse JSON décodée de l'opération « Suspendre un agent ».

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

AgentsClient.update

update(agent_id: str, **changes: Any) -> Any

Modifier un agent. Modifie les champs de registre de l'agent (propriétaire, niveau de risque, description, libellés) sans créer de version. Demande tenant_admin, developer ou application_owner et la relation ReBAC editor. Une valeur invalide répond 400 invalid_request. Audité sous agent.update avec les noms des champs modifiés.

Route : /v1/agents/{agent_id} (PATCH).

Nom	Type	Défaut	Requis	Description
agent_id	str		oui	Identifiant (UUID) ou nom de l'agent.
**changes	Any		non	Champs de l'agent à modifier, envoyés comme corps du PATCH.

Retour : Any. Réponse JSON décodée de l'opération « Modifier un agent ».

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

AgentsClient.versions

versions(agent_id: str) -> Any

Lister les versions d'un agent. Toutes les versions enregistrées de l'agent, de la plus récente à la plus ancienne, avec manifeste, empreinte, auteur et current (vrai pour la version en service). Demande la relation ReBAC viewer. Une seule page.

Route : /v1/agents/{agent_id}/versions (GET).

Nom	Type	Défaut	Requis	Description
agent_id	str		oui	Identifiant (UUID) ou nom de l'agent.

Retour : Any. Réponse JSON décodée de l'opération « Lister les versions d'un agent ».

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

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.

Resource

RunsClient.add_step

add_step(run_id: str, step: dict[str, Any]) -> Any

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
run_id	str		oui	Identifiant (UUID) du run.
step	dict[str, Any]		oui	Résolution des séries de métriques en secondes, de 10 à 86400, 60 par défaut.

Retour : Any. 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

cancel(run_id: str, reason: str | None = None) -> Any

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
run_id	str		oui	Identifiant (UUID) du run.
reason	str | None	None	non	Raison de l'action. Inscrite dans le journal d'audit avec l'acteur et l'heure.

Retour : Any. 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_subagent

cancel_subagent(subagent_run_id: str, reason: str | None = None) -> Any

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
subagent_run_id	str		oui	Identifiant (UUID) du run.
reason	str | None	None	non	Raison de l'action. Inscrite dans le journal d'audit avec l'acteur et l'heure.

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

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

RunsClient.checkpoint

checkpoint(run_id: str, state: dict[str, Any], label: str | None = None, **extra: Any) -> Any

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
run_id	str		oui	Identifiant (UUID) du run.
state	dict[str, Any]		oui	État à enregistrer, toute valeur JSON. Par défaut : objet vide.
label	str | None	None	non	Libellé du point de reprise (200 caractères au plus).
**extra	Any		non	Champs supplémentaires fusionnés dans le corps de la requête.

Retour : Any. 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).

RunsClient.checkpoints

checkpoints(run_id: str) -> Any

Lister les points de reprise d'un run. Points de reprise du run dans l'ordre de séquence. Une seule page. 404 run_not_found.

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

Nom	Type	Défaut	Requis	Description
run_id	str		oui	Identifiant (UUID) du run.

Retour : Any. Réponse JSON décodée de l'opération « Lister les points de reprise d'un run ».

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

RunsClient.delegate

delegate(run_id: str, agent: str, task: object, budgets: dict[str, Any] | None = None) -> Any

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
run_id	str		oui	Identifiant (UUID) du run parent.
agent	str		oui	Agent enfant, nom ou agent:<nom>. Par défaut : l'agent du run parent.
task	object		oui	Tâche du run enfant (task_id, objective, input).
budgets	dict[str, Any] | None	None	non	Limites de budget de l'enfant, plafonnées par ce qu'il reste au parent.

Retour : Any. 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.events

events(run_id: str, last_event_id: str | None = None) -> Any

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
run_id	str		oui	Identifiant (UUID) du run.
last_event_id	str | None	None	non	Identifiant du dernier événement déjà reçu, envoyé dans l'en-tête Last-Event-ID pour reprendre le flux après lui.

Retour : Any. 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

get(run_id: str) -> Any

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
run_id	str		oui	Identifiant (UUID) du run.

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

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

RunsClient.get_checkpoint

get_checkpoint(checkpoint_id: str) -> Any

Lire un point de reprise. Renvoie un point de reprise : run, numéro de séquence, séquence d'étape au moment de l'enregistrement, libellé et état enregistré. 404 checkpoint_not_found.

Route : /v1/checkpoints/{checkpoint_id} (GET).

Nom	Type	Défaut	Requis	Description
checkpoint_id	str		oui	Identifiant (UUID) du point de reprise.

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

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

RunsClient.heartbeat

heartbeat(run_id: str, step: Any = None, message: str | None = None, progress: Any = None, worker: str | None = None, **extra: Any) -> Any

Envoyer un heartbeat de run. Enregistre que le runtime est vivant et lui indique s'il doit continuer : action vaut continue, ou stop avec une reason (run_cancelled, run_terminal, run_suspended, agent_killed, agent_suspended). La réponse donne aussi stale_after_seconds. Un run terminé n'est pas mis à jour. Demande tenant_admin, developer ou agent. Audité seulement pour le premier heartbeat d'un run et quand le runtime reçoit l'ordre d'arrêter.

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

Nom	Type	Défaut	Requis	Description
run_id	str		oui	Identifiant (UUID) du run.
step	Any	None	non	Résolution des séries de métriques en secondes, de 10 à 86400, 60 par défaut.
message	str | None	None	non	Message d'état (2000 caractères au plus).
progress	Any	None	non	Progression : un nombre (par exemple une fraction de 0 à 1) ou un objet au choix du runtime.
worker	str | None	None	non	Worker qui exécute le run (200 caractères au plus). Par défaut : le principal appelant.
**extra	Any		non	Champs supplémentaires fusionnés dans le corps de la requête.

Retour : Any. Réponse JSON décodée de l'opération « Envoyer un heartbeat de run ».

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

RunsClient.list

list(state: str | None = None, agent_id: str | None = None, session_id: str | None = None, parent_run_id: str | None = None, **page: Any) -> Any

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
state	str | None	None	non	Seulement les runs dans cet état : pending, running, waiting_approval, waiting_input, suspended, succeeded, failed, cancelled ou timed_out.
agent_id	str | None	None	non	Seulement les runs de cet agent (UUID ou nom).
session_id	str | None	None	non	Seulement les runs de cette session (UUID).
parent_run_id	str | None	None	non	Seulement les runs de sous-agents lancés par ce run parent (UUID).
**page	Any		non	Options de pagination : limit (nombre maximal de runs par page) et cursor (curseur de la page à lire).

Retour : Any. 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

replay(run_id: str) -> Any

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
run_id	str		oui	Identifiant (UUID) du run.

Retour : Any. 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

resume(run_id: str, checkpoint_id: str | None = None) -> Any

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
run_id	str		oui	Identifiant (UUID) du run.
checkpoint_id	str | None	None	non	Identifiant (UUID) du point de reprise.

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

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

RunsClient.spawn_subagent

spawn_subagent(run_id: str, agent: str, task: object = None, **extra: Any) -> Any

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
run_id	str		oui	Identifiant (UUID) du run parent.
agent	str		oui	Agent enfant, nom ou agent:<nom>. Par défaut : l'agent du run parent.
task	object	None	non	Tâche du run enfant (task_id, objective, input).
**extra	Any		non	Champs supplémentaires fusionnés dans le corps de la requête.

Retour : Any. 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.stale_heartbeats

stale_heartbeats(**params: Any) -> Any

Lister les heartbeats des runs. Vivacité des runs censés envoyer des heartbeats (running et waiting_input). Par défaut, seuls les runs sans heartbeat dans le délai sont renvoyés, avec active, stale_count et stale_after_seconds. Avec format=prometheus, la réponse est un texte d'exposition Prometheus (eai_runs_total, eai_runs_active, eai_runs_stale, eai_heartbeat_stale_threshold_seconds).

Route : /v1/heartbeats (GET).

Nom	Type	Défaut	Requis	Description
**params	Any		non	Champs supplémentaires fusionnés dans la requête.

Retour : Any. Réponse JSON décodée de l'opération « Lister les heartbeats des runs ».

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

RunsClient.steps

steps(run_id: str) -> Any

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
run_id	str		oui	Identifiant (UUID) du run.

Retour : Any. 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

subagents(run_id: str) -> Any

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
run_id	str		oui	Identifiant (UUID) du run parent.

Retour : Any. 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).

Classe SessionsClient

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.

Resource

SessionsClient.create

create(agent_id: str | None = None, **extra: Any) -> Any

Ouvrir une session. Ouvre une session de conversation, détenue par user_id ou par l'appelant. Ouvrir une session pour un autre utilisateur demande tenant_admin ou agent (403 forbidden). Demande tenant_admin, developer ou agent. 404 agent_not_found pour un agent_id inconnu. Audité sous session.create.

Route : /v1/sessions (POST).

Nom	Type	Défaut	Requis	Description
agent_id	str | None	None	non	Agent de la conversation (UUID ou nom).
**extra	Any		non	Champs supplémentaires fusionnés dans le corps de la requête.

Retour : Any. Réponse JSON décodée de l'opération « Ouvrir une session ».

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

SessionsClient.delete

delete(session_id: str) -> Any

Supprimer une session. Supprime la session et ses messages. Demande tenant_admin, developer ou agent, et l'appelant doit voir la session (son propriétaire, ou tenant_admin, auditor, security_officer, agent) ; sinon 404 session_not_found. Audité sous session.delete.

Route : /v1/sessions/{session_id} (DELETE).

Nom	Type	Défaut	Requis	Description
session_id	str		oui	Identifiant (UUID) de la session.

Retour : Any. Réponse JSON décodée de l'opération « Supprimer une session ».

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

SessionsClient.get

get(session_id: str) -> Any

Lire une session. Renvoie une session. Visible par son propriétaire, par tenant_admin, auditor, security_officer et par le rôle agent ; sinon 404 session_not_found.

Route : /v1/sessions/{session_id} (GET).

Nom	Type	Défaut	Requis	Description
session_id	str		oui	Identifiant (UUID) de la session.

Retour : Any. Réponse JSON décodée de l'opération « Lire une session ».

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

SessionsClient.list

list(**page: Any) -> Any

Lister les sessions. Sessions, de la plus récente à la plus ancienne, paginées avec cursor. Un appelant voit ses propres sessions ; tenant_admin, auditor et security_officer voient toutes les sessions du tenant.

Route : /v1/sessions (GET).

Nom	Type	Défaut	Requis	Description
**page	Any		non	Options de pagination : limit (nombre maximal de sessions par page) et cursor (curseur de la page à lire).

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

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

SessionsClient.messages

messages(session_id: str, **page: Any) -> Any

Lister les messages d'une session. Messages dans l'ordre, paginés avec cursor. after (identifiant de message ou horodatage) permet à un runtime de ne récupérer que les nouveaux messages ; un identifiant inconnu ou un horodatage mal formé répond 400 invalid_request.

Route : /v1/sessions/{session_id}/messages (GET).

Nom	Type	Défaut	Requis	Description
session_id	str		oui	Identifiant (UUID) de la session.
**page	Any		non	Options de pagination : limit (nombre maximal de messages par page) et cursor (curseur de la page à lire).

Retour : Any. Réponse JSON décodée de l'opération « Lister les messages d'une session ».

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

SessionsClient.post_message

post_message(session_id: str, content: str, role: str = 'user', **extra: Any) -> Any

Ajouter un message à une session. Ajoute un message avec le numéro de séquence suivant. La session doit être ouverte et non expirée (409 session_closed). Demande tenant_admin, developer ou agent. L'événement d'audit session.message.add ne garde que le rôle et la longueur, jamais le contenu.

Route : /v1/sessions/{session_id}/messages (POST).

Nom	Type	Défaut	Requis	Description
session_id	str		oui	Identifiant (UUID) de la session.
content	str		oui	Texte du message (1 à 200000 caractères).
role	str	'user'	non	Rôle de l'auteur : user (par défaut), assistant, system ou tool.
**extra	Any		non	Champs supplémentaires fusionnés dans le corps de la requête.

Retour : Any. Réponse JSON décodée de l'opération « Ajouter un message à une session ».

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

Classe A2AClient

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.

Resource

A2AClient.inbox

inbox(recipient: str, unread: bool | None = None, **page: Any) -> Any

Lire une boîte de réception A2A. Renvoie les messages A2A adressés à recipient, du plus ancien au plus récent, chacun avec verified (la signature HMAC-SHA256 de l'enveloppe correspond à la clé du tenant). La lecture marque les messages renvoyés comme lus. Une seule page (next_cursor vaut toujours null).

Route : /v1/a2a/inbox (GET).

Nom	Type	Défaut	Requis	Description
recipient	str		oui	Partie dont la boîte est lue : agent:<nom> ou run:<id> (au moins 3 caractères).
unread	bool | None	None	non	Si vrai, seulement les messages pas encore lus. Faux par défaut.
**page	Any		non	Options de pagination : limit (nombre maximal de messages par page) et cursor (curseur de la page à lire).

Retour : Any. Réponse JSON décodée de l'opération « Lire une boîte de réception A2A ».

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

A2AClient.send

send(to: str, payload: dict[str, Any] | None = None, type: str = 'request', sender: str | None = None, conversation_id: str | None = None, in_reply_to: str | None = None, **extra: Any) -> Any

Envoyer un message A2A. Envoie un message signé d'agent à agent (enveloppe a2a.v1, signature HMAC-SHA256 propre au tenant). Demande tenant_admin, developer ou agent. Étapes : 1. to et from sont résolus : agent:<nom> ou run:<id> (400 invalid_request sinon). Sans from, l'expéditeur est le principal appelant. 2. Un expéditeur run: doit être un run créé par l'appelant (ou l'appelant est tenant_admin, sinon 403 forbidden) et non terminé (409 run_finished). 3. La politique agent.a2a.send est évaluée et la charge utile est filtrée comme contenu non fiable ; une injection de prompt est refusée avec prompt_injection_blocked après enregistrement de l'événement de sécurité. 4. L'enveloppe est déposée dans la boîte du destinataire et auditée sous a2a.send.

Route : /v1/a2a/messages (POST).

Nom	Type	Défaut	Requis	Description
to	str		oui	Destinataire : agent:<nom> ou run:<id> (3 à 300 caractères).
payload	dict[str, Any] | None	None	non	Contenu du message, toute valeur JSON. Filtré contre l'injection de prompt avant remise.
type	str	'request'	non	Type de message : request, response ou event.
sender	str | None	None	non	Identifiant de l'agent émetteur, envoyé dans le champ from de l'enveloppe ; omis s'il est vide.
conversation_id	str | None	None	non	Conversation à laquelle appartient le message (200 caractères au plus). Une nouvelle est générée si omise.
in_reply_to	str | None	None	non	Identifiant du message auquel celui-ci répond.
**extra	Any		non	Champs supplémentaires fusionnés dans le corps de la requête.

Retour : Any. Réponse JSON décodée de l'opération « Envoyer un message A2A ».

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