Skip to main content

talonic_heartbeat_agent_task

Extend the lease for a task you already claimed. Heartbeat before lease_expires_at when processing may take longer than the remaining lease window.

A heartbeat is a cheap, targeted call: it echoes the task_id and the execution_epoch from your claim, and the platform pushes lease_expires_at forward. The response is the task's refreshed metadata — no payload — so the field to read is the new lease_expires_at, which becomes your next deadline. Heartbeat only while genuine processing is under way; a worker that heartbeats forever without submitting is indistinguishable from a stuck one and holds the document hostage until timeout_at.

Tool input and response (metadata only)
// talonic_heartbeat_agent_task({
//   "task_id": "11111111-1111-4111-8111-111111111111",
//   "execution_epoch": 2
// })
{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "claimed",
  "execution_epoch": 2,
  "lease_expires_at": "2026-08-29T10:20:00.000Z",
  "timeout_at": "2026-08-30T12:00:00.000Z"
}

Treat a failed heartbeat as a hard stop. HTTP 409 means the epoch is stale — the lease lapsed and someone reclaimed the task — so any result you were computing now belongs to a claim that no longer exists and will be rejected on submit. Discard the work, return to talonic_list_agent_tasks, and pick up something new rather than racing the current owner.

The lease and the stage timeout are separate clocks. Heartbeats move lease_expires_at, which governs who owns the task; they never move timeout_at, the stage-level deadline after which the platform applies the task's timeout_fallthrough policy. A worker can therefore hold a perfectly healthy lease and still lose the task to a stage timeout if processing drags on too long — budget the work against timeout_at, not just the lease.

ParameterTypeDescription
task_id *UUIDClaimed task ID.
execution_epoch *integerExact epoch returned by the current successful claim.
A stale epoch or a claim owned by another actor returns HTTP 409. Stop work and do not submit results after that conflict.

Frequently asked questions

How often should an agent heartbeat?+
Only when needed, comfortably before lease_expires_at. Use the updated lease expiry returned by each successful heartbeat rather than a fixed client-side assumption.
What does a heartbeat return?+
The task's refreshed metadata, including the new lease_expires_at and the current execution_epoch. It never returns the payload — the input snapshot was already delivered by the claim.
My heartbeat returned HTTP 409 — can I still submit?+
No. A 409 means your execution epoch is stale: the lease expired and the task was reclaimed or withdrawn. Submits with that epoch will also be rejected, so discard the in-flight work and claim a different task.

Related

talonic_claim_agent_task
talonic_submit_agent_task