enterprise_ai.heartbeat

Source: sdks/python/src/enterprise_ai/heartbeat/__init__.py. Back to the Python SDK reference index.

note

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.

Model HeartbeatResponse

Parsed answer of POST /v1/runs/{id}/heartbeat (shared runtime semantics).

Fields:

Name	Type	Required	Description
run_id	str | None	no	Identifier of the run named in the answer.
state	str | None	no	State of the run, from the state or status field of the answer.
agent_status	str | None	no	Status of the agent reported by the server (for example suspended or killed).
action	str	no	Action asked by the server, in lower case (default continue); becomes stop when the status asks to stop.
reason	str | None	no	Why the action is taken. Written to the audit trail with the actor and the time.
raw	dict[str, Any]	no	Raw answer as a dict.

Attributes:

Name	Type	Required	Description
stop	bool	yes	True when action is stop, kill, cancel or suspend.

HeartbeatResponse.parse

parse(answer: Any) -> HeartbeatResponse

Build a response from a heartbeat answer; an answer that is not a dict gives the default response.

Name	Type	Default	Required	Description
answer	Any		yes	Raw answer of POST /v1/runs/{id}/heartbeat.

Returns: HeartbeatResponse. A HeartbeatResponse: Parsed answer of POST /v1/runs/{id}/heartbeat (shared runtime semantics).

Class Heartbeat

Background heartbeat for a sync run (context manager).

Attributes:

Name	Type	Required	Description
beats		yes	Number of heartbeats answered by the server.
errors		yes	Number of heartbeats that failed with an EaiError.
interval		yes	Seconds between two heartbeats.
last_answer	Any	yes	Raw answer of the last successful heartbeat, or None.
last_response	HeartbeatResponse | None	yes	Last answer parsed as a HeartbeatResponse, or None before the first one.
on_stop		yes	Function called with the raw answer when the server asks to stop, or None.
reason	str | None	yes	Why the action is taken. Written to the audit trail with the actor and the time.
run_id		yes	Identifier of the run that receives the heartbeats.
runs		yes	Runs client used to post the heartbeats.
state		yes	Function that returns the fields of the next heartbeat.
stop_event		yes	threading.Event set when the server asks the run to stop.
stop_requested	bool	yes	True once the server asked this run to stop.

Constructor Heartbeat

Heartbeat(runs: Any, run_id: str, interval: float = 15.0, state: Callable[[], dict[str, Any]] | None = None, stop_event: threading.Event | None = None, on_stop: Callable[[dict[str, Any]], None] | None = None) -> None

Prepare the heartbeat of a run; the background thread starts with start() or on with entry.

Name	Type	Default	Required	Description
runs	Any		yes	Runs client whose heartbeat(run_id, ...) posts /v1/runs/{id}/heartbeat.
run_id	str		yes	Identifier of the run that receives the heartbeats.
interval	float	15.0	no	Seconds between two heartbeats (default 15.0).
state	Callable[[], dict[str, Any]] | None	None	no	Function called before each beat that returns the heartbeat fields (step, message, progress, worker); empty by default.
stop_event	threading.Event | None	None	no	threading.Event to set when the server asks to stop, usually the stop_event of the agent loop; a new one by default.
on_stop	Callable[[dict[str, Any]], None] | None	None	no	Function called with the raw answer when the server asks the run to stop.

Heartbeat.beat

beat() -> Any

Send one heartbeat now; sets stop_event when the server asks to stop.

This element takes no parameter.

Returns: Any. Raw answer of the server, or None when the call raised an EaiError (counted in errors).

Heartbeat.start

start() -> Heartbeat

Start the background thread that beats every interval seconds until stop() or a stop request; does nothing when it already runs.

This element takes no parameter.

Returns: Heartbeat. A Heartbeat: Background heartbeat for a sync run (context manager).

Heartbeat.stop

stop() -> None

Stop the background thread and wait for it at most interval + 1 seconds.

This element takes no parameter.

Returns: None.

Class AsyncHeartbeat

Heartbeat as an asyncio task for the async client (async with).

Attributes:

Name	Type	Required	Description
beats		yes	Number of heartbeats answered by the server.
interval		yes	Seconds between two heartbeats.
run_id		yes	Identifier of the run that receives the heartbeats.
runs		yes	Async runs client used to post the heartbeats.
state		yes	Function that returns the fields of the next heartbeat.
stop_event	asyncio.Event	yes	asyncio.Event set when the server asks the run to stop; it also ends the heartbeat task.

Constructor AsyncHeartbeat

AsyncHeartbeat(runs: Any, run_id: str, interval: float = 15.0, state: Callable[[], dict[str, Any]] | None = None) -> None

Prepare the heartbeat of a run; the asyncio task starts on async with entry and is cancelled on exit.

Name	Type	Default	Required	Description
runs	Any		yes	Async runs client whose heartbeat(run_id, ...) posts /v1/runs/{id}/heartbeat.
run_id	str		yes	Identifier of the run that receives the heartbeats.
interval	float	15.0	no	Seconds between two heartbeats (default 15.0).
state	Callable[[], dict[str, Any]] | None	None	no	Function called before each beat that returns the heartbeat fields (step, message, progress, worker); empty by default.

AsyncHeartbeat.beat

async beat() -> Any

Send one heartbeat now; sets stop_event when the answer asks the agent to stop.

This element takes no parameter.

Returns: Any. Answer of the server, or None when the call raised an EaiError.

Functions

should_stop

should_stop(answer: Any) -> bool

True when a heartbeat answer asks the agent to stop.

Name	Type	Default	Required	Description
answer	Any		yes	Heartbeat answer, as a dict or a HeartbeatResponse.

Returns: bool. True when the action is stop, kill, cancel or suspend, when the run or agent status is terminal (cancelled, killed, suspended, failed) or when stop is true.