resources/agents.ts

Source : sdks/typescript/packages/sdk/src/resources/agents.ts. Retour à l'index de la référence du SDK TypeScript.

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.

Interface RunCreate

Corps de POST /v1/agents/{id}/runs.

Doc

Champs :

Nom	Type	Requis	Description
task	{ objective?: string; input?: unknown; task_id?: string } & Doc	non	Tâche confiée à l'agent : objective, input et task_id sont conservés sur le run.
session_id	string	non	Session à laquelle appartient le run.
budgets	Doc	non	Budgets du run.
retry_policy	Doc	non	Politique de nouvelle tentative : max_attempts (1 ou plus, 3 par défaut) et backoff_seconds (0 ou plus, 2 par défaut).
start	boolean	non	Démarrer les services une fois installés. Vrai par défaut.

Classe AgentsResource

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

AgentsResource.create

create(body: Doc, opts?: CallOptions)

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
body	Doc		oui	Manifeste Agent (kind: Agent, metadata avec nom, version et propriétaire, spec).
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

AgentsResource.delete

delete(id: string, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) ou nom de l'agent.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

AgentsResource.get

get(id: string, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) ou nom de l'agent.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

AgentsResource.iterate

iterate(params?: ListParams, opts?: CallOptions)

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
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

AgentsResource.kill

kill(id: string, body: { reason?: string } = {}, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) ou nom de l'agent.
body	{ reason?: string }	{}	non	Raison facultative, conservée sur l'agent et dans le journal d'audit.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

AgentsResource.list

list(params?: ListParams, opts?: CallOptions)

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
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

AgentsResource.resume

resume(id: string, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) ou nom de l'agent.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

AgentsResource.run

run(id: string, body: RunCreate = {}, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) ou nom de l'agent.
body	RunCreate	{}	non	Tâche du run, session facultative, budget, politique de nouvelle tentative et délégation.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

AgentsResource.suspend

suspend(id: string, body: { reason?: string } = {}, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) ou nom de l'agent.
body	{ reason?: string }	{}	non	Raison facultative, conservée sur l'agent et dans le journal d'audit.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

AgentsResource.update

update(id: string, body: Doc, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) ou nom de l'agent.
body	Doc		oui	Champs à modifier ; ceux omis sont conservés.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

AgentsResource.versions

versions(id: string, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) ou nom de l'agent.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

Classe RunsResource

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

RunsResource.addStep

addStep(id: string, body: Doc, opts?: CallOptions)

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	Doc		oui	L'étape : type, état, usage, coût, erreur et indications d'état du run.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

RunsResource.cancel

cancel(id: string, body: { reason?: string } = {}, opts?: CallOptions)

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	{ reason?: string }	{}	non	Raison facultative de l'annulation.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

RunsResource.create

create(agentId: string, body: RunCreate = {}, opts?: CallOptions)

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	RunCreate	{}	non	Tâche du run, session facultative, budget, politique de nouvelle tentative et délégation.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

RunsResource.get

get(id: string, opts?: CallOptions)

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.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

RunsResource.iterate

iterate(params?: ListParams, opts?: CallOptions)

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
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

RunsResource.list

list(params?: ListParams, opts?: CallOptions)

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
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

RunsResource.replay

replay(id: string, opts?: CallOptions)

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.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

RunsResource.resume

resume(id: string, body: { checkpoint_id?: string; strategy?: string } = {}, opts?: CallOptions)

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	{ checkpoint_id?: string; strategy?: string }	{}	non	Point de reprise et stratégie de reprise facultatifs.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

RunsResource.steps

steps(id: string, opts?: CallOptions)

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.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

Classe CheckpointsResource

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

CheckpointsResource.create

create(runId: string, body: Doc, opts?: CallOptions)

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	Doc		oui	État à enregistrer et libellé facultatif.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

CheckpointsResource.get

get(id: string, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) du point de reprise.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

CheckpointsResource.list

list(runId: string, opts?: CallOptions)

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
runId	string		oui	Identifiant (UUID) du run.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

Interface HeartbeatResponse

Sémantique partagée du heartbeat : l'exécution DOIT s'arrêter quand action vaut stop.

Doc

Champs :

Nom	Type	Requis	Description
run_id	string	oui	Identifiant du run pour lequel le heartbeat a été envoyé.
state	string	oui	État courant du run.
agent_status	"active" | "suspended" | "killed"	oui	Statut de l'agent : active, suspended ou killed.
action	"continue" | "stop"	oui	continue ou stop ; l'exécution doit s'arrêter sur stop.
reason	string | null	oui	Raison de l'action. Inscrite dans le journal d'audit avec l'acteur et l'heure.

Classe HeartbeatsResource

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

HeartbeatsResource.send

send(runId: string, body: { step?: string; progress?: Doc | number; message?: string; worker?: string } & Doc = {}, opts?: CallOptions)

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
runId	string		oui	Identifiant (UUID) du run.
body	{ step?: string; progress?: Doc | number; message?: string; worker?: string } & Doc	{}	non	Informations de progression facultatives.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

HeartbeatsResource.stale

stale(params?: ListParams, opts?: CallOptions)

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	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

Classe SubagentsResource

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

SubagentsResource.cancel

cancel(subagentRunId: string, body: { reason?: string } = {}, opts?: CallOptions)

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
subagentRunId	string		oui	Identifiant (UUID) du run.
body	{ reason?: string }	{}	non	Raison facultative de l'annulation.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

SubagentsResource.delegate

delegate(runId: string, body: { agent: string; task: unknown; budgets?: Doc }, opts?: CallOptions)

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
runId	string		oui	Identifiant (UUID) du run parent.
body	{ agent: string; task: unknown; budgets?: Doc }		oui	Agent enfant, tâche et budget.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

SubagentsResource.list

list(runId: string, opts?: CallOptions)

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
runId	string		oui	Identifiant (UUID) du run parent.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

SubagentsResource.spawn

spawn(runId: string, body: Doc, opts?: CallOptions)

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
runId	string		oui	Identifiant (UUID) du run parent.
body	Doc		oui	Agent enfant, tâche et budget.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

Classe A2AResource

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

A2AResource.inbox

inbox(params: { recipient: string; unread?: boolean; limit?: number }, opts?: CallOptions)

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
params	{ recipient: string; unread?: boolean; limit?: number }		oui	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

A2AResource.send

send(body: { to: string; type: "request" | "response" | "event"; from?: string; payload?: unknown; conversation_id?: string; in_reply_to?: string } & Doc, opts?: CallOptions)

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
body	{ to: string; type: "request" | "response" | "event"; from?: string; payload?: unknown; conversation_id?: string; in_reply_to?: string } & Doc		oui	Destinataire, type de message, charge utile et fil de conversation facultatif.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

Classe SessionsResource

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

SessionsResource.create

create(body: Doc = {}, opts?: CallOptions)

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
body	Doc	{}	non	Agent, propriétaire, canal, titre, métadonnées et durée de vie de la session.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

SessionsResource.delete

delete(id: string, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) de la session.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

SessionsResource.get

get(id: string, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) de la session.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

SessionsResource.list

list(params?: ListParams, opts?: CallOptions)

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
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

SessionsResource.listMessages

listMessages(id: string, params?: ListParams, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) de la session.
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

SessionsResource.sendMessage

sendMessage(id: string, body: { role?: string; content: unknown } & Doc, opts?: CallOptions)

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
id	string		oui	Identifiant (UUID) de la session.
body	{ role?: string; content: unknown } & Doc		oui	Rôle, contenu et métadonnées du message.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

Classe SchedulesResource

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

SchedulesResource.create

create(body: { cron: string; agent_id: string; enabled?: boolean; timezone?: string; input?: unknown } & Doc, opts?: CallOptions)

Créer une planification. Planifie des runs d'un agent à partir d'une expression cron évaluée dans un fuseau horaire ; la première échéance next_run_at est calculée (422 invalid_cron). Quand Temporal est configuré, la planification y est créée (503 scheduler_unavailable en cas d'échec). Demande tenant_admin, developer ou application_owner. 404 agent_not_found. Audité sous schedule.create.

Route : /v1/schedules (POST).

Nom	Type	Défaut	Requis	Description
body	{ cron: string; agent_id: string; enabled?: boolean; timezone?: string; input?: unknown } & Doc		oui	Agent, expression cron, fuseau horaire, entrée du run et activation.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

SchedulesResource.delete

delete(id: string, opts?: CallOptions)

Supprimer une planification. Supprime la planification ; elle ne lance plus aucun run. Demande tenant_admin, developer ou application_owner. Quand la planification est portée par Temporal, elle y est aussi supprimée (503 scheduler_unavailable si Temporal est injoignable). 404 schedule_not_found. Audité sous schedule.delete.

Route : /v1/schedules/{schedule_id} (DELETE).

Nom	Type	Défaut	Requis	Description
id	string		oui	Identifiant (UUID) de la planification.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

SchedulesResource.list

list(params?: ListParams, opts?: CallOptions)

Lister les planifications. Planifications cron du tenant, de la plus ancienne à la plus récente, éventuellement pour un seul agent. Une seule page.

Route : /v1/schedules (GET).

Nom	Type	Défaut	Requis	Description
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

SchedulesResource.update

update(id: string, body: Doc, opts?: CallOptions)

Modifier une planification. Modifie l'expression cron, le fuseau horaire, l'entrée ou l'activation. La prochaine échéance est recalculée (422 invalid_cron pour une expression ou un fuseau invalide) et la planification Temporal est mise à jour quand Temporal la porte (503 scheduler_unavailable). Demande tenant_admin, developer ou application_owner. Audité sous schedule.update.

Route : /v1/schedules/{schedule_id} (PATCH).

Nom	Type	Défaut	Requis	Description
id	string		oui	Identifiant (UUID) de la planification.
body	Doc		oui	Champs à modifier ; ceux omis sont conservés.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

Classe TriggersResource

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

TriggersResource.create

create(body: { subject: string; agent_id: string; filter?: string } & Doc, opts?: CallOptions)

Créer un déclencheur. Lance un run de l'agent pour chaque événement publié dont le sujet correspond (jokers NATS * et > admis) et dont la charge utile passe le filtre. Demande tenant_admin, developer ou application_owner. 422 invalid_subject ou invalid_filter ; 404 agent_not_found. Audité sous trigger.create.

Route : /v1/triggers (POST).

Nom	Type	Défaut	Requis	Description
body	{ subject: string; agent_id: string; filter?: string } & Doc		oui	Agent, sujet et filtre facultatif sur la charge utile.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

TriggersResource.delete

delete(id: string, opts?: CallOptions)

Supprimer un déclencheur. Supprime le déclencheur sur événement ; les événements correspondants ne lancent plus de run. Demande tenant_admin, developer ou application_owner. 404 trigger_not_found. Audité sous trigger.delete.

Route : /v1/triggers/{trigger_id} (DELETE).

Nom	Type	Défaut	Requis	Description
id	string		oui	Identifiant (UUID) du déclencheur.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

TriggersResource.list

list(params?: ListParams, opts?: CallOptions)

Lister les déclencheurs. Déclencheurs sur événement du tenant, du plus ancien au plus récent : agent, sujet et filtre. Une seule page.

Route : /v1/triggers (GET).

Nom	Type	Défaut	Requis	Description
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

Classe EventsResource

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

EventsResource.publish

publish(body: { subject: string; payload?: unknown; headers?: Record<string, string> } & Doc, opts?: CallOptions)

Publier un événement. Publie un événement (202) : sur NATS JetStream quand il est configuré, sinon dans l'outbox de la plateforme. Le contexte de trace W3C courant est ajouté aux en-têtes. Chaque déclencheur dont le sujet et le filtre correspondent lance un run de son agent (idempotent par événement et déclencheur) ; la réponse les liste dans triggered, avec skipped et un code d'erreur quand un run n'a pas pu démarrer. Demande tenant_admin, developer ou agent. 422 invalid_subject. Audité sous event.publish.

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

Nom	Type	Défaut	Requis	Description
body	{ subject: string; payload?: unknown; headers?: Record<string, string> } & Doc		oui	Sujet, charge utile et en-têtes de l'événement.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

Classe SandboxResource

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

SandboxResource.execute

execute(body: { image: string; command?: string[]; env?: Record<string, string>; profile?: "gvisor" | "kata" | "wasm" | "none"; limits?: Doc; run_id?: string } & Doc, opts?: CallOptions)

Exécuter une commande en sandbox. Crée une exécution en sandbox : l'image et la commande tournent comme Job Kubernetes avec la classe de runtime du profil (gVisor, Kata, Wasm) quand Kubernetes est configuré (status: submitted, ou failed si la soumission échoue). Demande tenant_admin, developer ou agent ; le profil none demande tenant_admin (403). Un profil, une image ou des limites invalides répondent 422 invalid_sandbox. L'usage est mesuré et la demande auditée sous sandbox.execute.

Route : /v1/sandbox/executions (POST).

Nom	Type	Défaut	Requis	Description
body	{ image: string; command?: string[]; env?: Record<string, string>; profile?: "gvisor" | "kata" | "wasm" | "none"; limits?: Doc; run_id?: string } & Doc		oui	Profil, image, commande, environnement et limites de ressources.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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

SandboxResource.get

get(id: string, opts?: CallOptions)

Lire une exécution en sandbox. Renvoie l'exécution en sandbox : profil, image, commande, limites, spécification de Job Kubernetes générée, statut, exécuteur et résultat. 404 sandbox_execution_not_found.

Route : /v1/sandbox/executions/{execution_id} (GET).

Nom	Type	Défaut	Requis	Description
id	string		oui	Identifiant (UUID) de l'exécution en sandbox.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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