agent/heartbeat.ts
Source: sdks/typescript/packages/sdk/src/agent/heartbeat.ts. Back to the TypeScript SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Interface HeartbeatResponse
Response of POST /v1/runs/{id}/heartbeat (shared runtime semantics).
Fields:
| Name | Type | Required | Description |
|---|---|---|---|
run_id | string | no | Id of the run the heartbeat was sent for. |
state | string | no | Current state of the run. |
agent_status | string | no | Status of the agent; killed, suspended, blocked or disabled mean stop. |
action | "continue" | "stop" | string | no | continue or stop; the runtime must stop on stop. |
reason | string | null | no | Why the action is taken. Written to the audit trail with the actor and the time. |
Interface HeartbeatOptions
Options of startHeartbeat: interval, request body and the error and stop callbacks.
Fields:
| Name | Type | Required | Description |
|---|---|---|---|
intervalMs | number | no | Time between two heartbeats in milliseconds (default 15000). |
payload | () => Doc | no | Returns the body of each heartbeat request (default an empty object). |
onError | (err: unknown) => void | no | Called with the error each time a heartbeat request fails. |
onStop | (res: HeartbeatResponse) => void | no | Called once, the first time the control plane answers stop. |
Interface HeartbeatHandle
Callable stop function plus the live heartbeat state.
Fields:
| Name | Type | Required | Description |
|---|---|---|---|
stopRequested | boolean | yes | True once a heartbeat response said stop, or the run answered 404 or 410. |
lastResponse | HeartbeatResponse | undefined | yes | Last heartbeat response received, undefined before the first one. |
reason | string | undefined | yes | Why the action is taken. Written to the audit trail with the actor and the time. |
Functions
heartbeatSaysStop
heartbeatSaysStop(res: HeartbeatResponse | Doc | undefined | null): boolean
True when a heartbeat response (or agent document) says the agent must stop.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
res | HeartbeatResponse | Doc | undefined | null | yes | Heartbeat response or agent document; undefined and null give false. |
Returns: boolean. True when action is stop, the status is killed, suspended, blocked or disabled, or killed is true.
startHeartbeat
startHeartbeat(client: EnterpriseAI, runId: string, intervalOrOptions: number | HeartbeatOptions = 15000, payload: () = Doc = () => ({}), onError?: (err: unknown) => void, onStop?: (res: HeartbeatResponse) => void,): HeartbeatHandle
Send a run heartbeat. Records that the runtime is alive and tells it whether to go on: action is continue, or stop with a reason (run_cancelled, run_terminal, run_suspended, agent_killed, agent_suspended). The answer also gives stale_after_seconds. A terminal run is not updated. Needs tenant_admin, developer or agent. Audited only for the first heartbeat of a run and when the runtime is told to stop.
Route: /v1/runs/{run_id}/heartbeat (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
client | EnterpriseAI | yes | Parent client. | |
runId | string | yes | Identifier (UUID) of the run. | |
intervalOrOptions | number | HeartbeatOptions | 15000 | no | Interval in milliseconds (default 15000), or a HeartbeatOptions object that replaces the next arguments. |
payload | () | Doc = () => ({}), onError?: (err: unknown) => void, onStop?: (res: HeartbeatResponse) => void, | no | Optional progress information. |
Returns: HeartbeatHandle. A HeartbeatHandle: Callable stop function plus the live heartbeat state.
Raises: the typed errors of the transport (Errors).
isAgentStopped
async isAgentStopped(clientOrResponse: EnterpriseAI | HeartbeatResponse, agentId?: string): Promise<boolean>
Kill switch check. With a heartbeat response: action "stop" or agent_status suspended / killed. With a client and an agent id: reads the agent document.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
clientOrResponse | EnterpriseAI | HeartbeatResponse | yes | EnterpriseAI client, or a heartbeat response to check directly. | |
agentId | string | no | Id of the agent to read; without it the first argument is read as a heartbeat response. |
Returns: Promise<boolean>. True when the agent must stop; also true when reading the agent answers 404 or 403.