talonic_claim_agent_task
Claim a task before processing. A successful claim returns the full payload plus a new execution_epoch and lease_expires_at; both prevent two agents from writing results for the same task.
The claim is the concurrency boundary of the Agent-task workflow. Listing and fetching are read-only and race-free; the moment real work starts, exactly one actor must own the task. The lease makes ownership crash-safe — if the claimant dies, the lease simply expires and the task becomes reclaimable — while the epoch makes ownership unambiguous: whichever claim is newest wins, and everything an older claimant tries to write afterwards is rejected.
| Parameter | Type | Description |
|---|---|---|
| task_id * | UUID | Available task to claim, or an expired claim to reclaim. |
// talonic_claim_agent_task({ "task_id": "11111111-1111-4111-8111-111111111111" })
{
"id": "11111111-1111-4111-8111-111111111111",
"status": "claimed",
"execution_epoch": 2,
"claimed_at": "2026-08-29T10:00:00.000Z",
"lease_expires_at": "2026-08-29T10:10:00.000Z",
"input_snapshot": { "...": "full payload, same shape as talonic_get_agent_task" },
"output_contract": [{ "key": "risk_score", "dataType": "number", "required": true }],
"instructions": "Assess supplier risk from the supplied evidence."
}Save the returned execution_epoch. Every heartbeat and submit must echo that exact epoch. Reclaiming an expired lease increments it, permanently invalidating work from the earlier claimant.
Because a successful claim returns the complete payload, a worker that goes straight from the list to a claim never needs a separate talonic_get_agent_task call — inspect-then-claim is for when you want to read before committing, claim-directly is for when the worklist row is enough. After claiming, do the work, heartbeat if the lease is running short, and finish with a single talonic_submit_agent_task call.