agent/heartbeat.ts

Source : sdks/typescript/packages/sdk/src/agent/heartbeat.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 HeartbeatResponse

Réponse de POST /v1/runs/{id}/heartbeat (sémantique d'exécution partagée).

Champs :

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

Interface HeartbeatOptions

Options de startHeartbeat : intervalle, corps de la requête et fonctions de rappel d'erreur et d'arrêt.

Champs :

Nom	Type	Requis	Description
intervalMs	number	non	Délai entre deux heartbeats en millisecondes (15000 par défaut).
payload	() => Doc	non	Renvoie le corps de chaque requête de heartbeat (objet vide par défaut).
onError	(err: unknown) => void	non	Appelée avec l'erreur chaque fois qu'une requête de heartbeat échoue.
onStop	(res: HeartbeatResponse) => void	non	Appelée une seule fois, la première fois que le plan de contrôle répond stop.

Interface HeartbeatHandle

Fonction d'arrêt appelable, accompagnée de l'état courant du heartbeat.

Champs :

Nom	Type	Requis	Description
stopRequested	boolean	oui	Vrai dès qu'une réponse de heartbeat a demandé l'arrêt, ou que le run a répondu 404 ou 410.
lastResponse	HeartbeatResponse | undefined	oui	Dernière réponse de heartbeat reçue, undefined avant la première.
reason	string | undefined	oui	Raison de l'action. Inscrite dans le journal d'audit avec l'acteur et l'heure.

Fonctions

heartbeatSaysStop

heartbeatSaysStop(res: HeartbeatResponse | Doc | undefined | null): boolean

Vrai quand une réponse de heartbeat (ou un document d'agent) indique que l'agent doit s'arrêter.

Nom	Type	Défaut	Requis	Description
res	HeartbeatResponse | Doc | undefined | null		oui	Réponse de heartbeat ou document d'agent ; undefined et null donnent false.

Retour : boolean. Vrai quand action vaut stop, que le statut est killed, suspended, blocked ou disabled, ou que killed est vrai.

startHeartbeat

startHeartbeat(client: EnterpriseAI, runId: string, intervalOrOptions: number | HeartbeatOptions = 15000, payload: () = Doc = () => ({}), onError?: (err: unknown) => void, onStop?: (res: HeartbeatResponse) => void,): HeartbeatHandle

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
client	EnterpriseAI		oui	Client parent.
runId	string		oui	Identifiant (UUID) du run.
intervalOrOptions	number | HeartbeatOptions	15000	non	Intervalle en millisecondes (15000 par défaut), ou un objet HeartbeatOptions qui remplace les arguments suivants.
payload	()	Doc = () => ({}), onError?: (err: unknown) => void, onStop?: (res: HeartbeatResponse) => void,	non	Informations de progression facultatives.

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

isAgentStopped

async isAgentStopped(clientOrResponse: EnterpriseAI | HeartbeatResponse, agentId?: string): Promise<boolean>

Vérification d'arrêt d'urgence. Avec une réponse de heartbeat : action "stop" ou agent_status suspended / killed. Avec un client et un identifiant d'agent : lit le document de l'agent.

Nom	Type	Défaut	Requis	Description
clientOrResponse	EnterpriseAI | HeartbeatResponse		oui	Client EnterpriseAI, ou une réponse de heartbeat à vérifier directement.
agentId	string		non	Identifiant de l'agent à lire ; sans lui, le premier argument est lu comme une réponse de heartbeat.

Retour : Promise<boolean>. Vrai quand l'agent doit s'arrêter ; vrai aussi quand la lecture de l'agent répond 404 ou 403.