Skip to main content

talonic_get_agent_task

Fetch the immutable input snapshot captured when one document reached an Agent stage. The payload also carries stage instructions, timeout policy, and the only output fields the agent may return.

The payload extends the metadata from talonic_list_agent_tasks with four fields. input_snapshot is the frozen view of the document's extracted data at the moment it entered the stage — later edits to the document do not leak into a running task. output_contract declares every field the agent may submit, each with a key, a dataType, and a required flag. instructions is the stage author's free-text brief. timeout_fallthrough (hold, skip, or route_to_review) says what happens to the document if nobody submits before timeout_at.

Fetching a task does not lease it: another agent can still claim the work while you are reading it. Treat get as the inspection step — confirm the instructions and contract are something you can actually fulfil — then take the lease with talonic_claim_agent_task before doing any real processing. If a claim races you to it, pick another task from the list rather than waiting on that one.

ParameterTypeDescription
task_id *UUIDTask ID returned by `talonic_list_agent_tasks`.
Tool input
{ "task_id": "11111111-1111-4111-8111-111111111111" }

Payload access is deliberately narrow. The worklist never includes snapshots, and each talonic_get_agent_task call is recorded as an audited disclosure of that document's data to the calling credential. Fetch payloads for tasks you actually intend to process rather than sweeping the queue — it keeps the audit trail meaningful and avoids disclosing document contents your workflow never needed.

Key response fields
{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "available",
  "input_snapshot": { "vendor_name": { "value": "Acme" } },
  "output_contract": [
    { "key": "risk_score", "dataType": "number", "required": true }
  ],
  "instructions": "Assess supplier risk from the supplied evidence.",
  "timeout_fallthrough": "route_to_review"
}
Fetching a task payload is an audited data disclosure. Do not fetch tasks speculatively; inspect metadata first and fetch only work you intend to evaluate.

Frequently asked questions

Can the snapshot change while an agent processes it?+
No. It is captured when the document enters the Agent stage and remains immutable for that task. Results are validated against the accompanying output_contract.
Does fetching an Agent task claim it?+
No. talonic_get_agent_task is read-only; the task stays available and another agent can claim it while you inspect. Call talonic_claim_agent_task to take the lease before processing.
What does timeout_fallthrough mean?+
It is the stage's policy for a task nobody submits before timeout_at: hold keeps the document parked, skip lets the document continue without the agent outputs, and route_to_review sends it to human review. Use it to judge how urgent a task is.

Related

talonic_list_agent_tasks
talonic_claim_agent_task