Skip to main content

talonic_list_agent_tasks

List Agent-stage tasks visible to the current workspace credential. The response contains task metadata and cursor pagination; payload data is deliberately fetched one task at a time so each disclosure can be audited.

Agent stages are pipeline steps that park a running document until an external agent supplies a set of declared output fields — a risk assessment, an enrichment lookup, a judgment call the pipeline cannot make itself. When a document reaches an enabled Agent stage, the platform captures an immutable input snapshot, creates a task, and waits. This tool is the entry point of the pull workflow: it shows what work exists without exposing any document data.

Each row in data[] carries identifiers (id, document_id, pipeline_id, stage_id), the lifecycle status (available, claimed, submitted, timed_out, or cancelled), the current execution_epoch, and the timing fields claimed_at, lease_expires_at, timeout_at, submitted_at, and created_at. That is enough to decide which task to inspect next — and nothing more, by design. pagination.has_more and pagination.next_cursor drive paging.

Start the pull workflow

  1. Call talonic_list_agent_tasks with status: "available".
  2. Inspect a candidate with talonic_get_agent_task.
  3. Claim it with talonic_claim_agent_task before doing work.
  4. Heartbeat while processing, then submit only fields declared in output_contract.
ParameterTypeDescription
statusavailable | claimed | submitted | timed_out | cancelledOptional lifecycle-state filter. Start with `available` when looking for work.
limitintegerPage size from 1 to 100. Defaults to 50.
cursorstringOpaque `pagination.next_cursor` from the previous page.
Tool input and response
// talonic_list_agent_tasks({ "status": "available", "limit": 2 })
{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "document_id": "22222222-2222-4222-8222-222222222222",
      "stage_id": "33333333-3333-4333-8333-333333333333",
      "status": "available",
      "execution_epoch": 1,
      "claimed_at": null,
      "lease_expires_at": null,
      "timeout_at": "2026-08-30T12:00:00.000Z",
      "created_at": "2026-08-29T09:15:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null }
}

For a long-running worker loop, list with status: "available" on a modest interval rather than a tight poll, and page with cursor only when has_more is true. Filtering by claimed or timed_out is useful for supervision — spotting tasks another worker abandoned (their lease expired but they were never resubmitted) that are now eligible for reclaiming via talonic_claim_agent_task.

An empty worklist is normal: tasks exist only when a running document reaches an enabled Agent stage and the credential's Sources-IAM rules allow it.

Frequently asked questions

Does listing Agent tasks expose document data?+
No. The list returns metadata only. Fetching one task's immutable input snapshot uses talonic_get_agent_task and is recorded as an audited disclosure.
What do the Agent task statuses mean?+
available means no one holds the task; claimed means an agent holds a live lease; submitted means outputs were accepted and the document resumed; timed_out means the stage's deadline passed without a submission; cancelled means the platform withdrew the task, for example because the document was removed or the stage was reconfigured.
How does pagination work on the Agent-task worklist?+
Pass limit (1-100, default 50) to size the page. When pagination.has_more is true, pass the opaque pagination.next_cursor value as cursor on the next call. Cursors encode a position, not a filter, so keep the same status filter across pages.

Related

talonic_get_agent_task
talonic_claim_agent_task
talonic_submit_agent_task