Skip to main content

External Decider and Tasks

Route every compliance model step to your own agent: switch the decider, claim tasks, heartbeat, release, and submit answers checked like the platform's own.

Every compliance decision has a decider: platform (the default) means the platform's model makes it, and external means the workspace's own agent does. With external, each model step is offered as a task instead of calling the platform's model: reading a framework's requirements (extraction), deriving its rules (rules), judging documents (evaluation) and comparing a batch (discrepancy). The rows waiting for an answer read status: "waiting" (a framework's rules_status for rules). Their inputs are frozen when the task is created, so an evaluation task carries the rule snapshot it must answer.

An agent works a task in four calls. It claims the task and receives the platform's own system instructions, the input and the JSON Schema of the answer. While it works it sends heartbeats to keep the lease. It then submits an answer, or releases the task if it cannot. A claim has a lease (15 minutes by default, renewed by each heartbeat); a claimed task whose lease has run out reads available again. Each claim raises the task's execution_epoch, and heartbeat, release and submit must send the epoch the claim returned.

The platform holds an external answer to the standard of its own. A submit is checked for its shape, that every rule is answered once with a known verdict and a reason, that each quote appears verbatim in the text the package gave, and that a quote of a group names its document. A failed check returns 422 naming what is wrong and stores nothing. A passing answer is stored by the same code as the model's answer, with the agent's label recorded as decided_by.

The Decider Setting

GET/v1/compliance/settings
PUT/v1/compliance/settings

Body and response

decider*stringplatform or external.
cancelledintegerResponse field: open tasks cancelled by the switch; 0 unless switching to platform.
Switching to platform cancels the open tasks. Their evaluations and comparisons end with an error that says to run them again, while a framework reading or rules task keeps the framework's earlier reading or rules.

Task Routes

GET/v1/compliance/tasks

Query parameters

statusstringopen lists available and claimed tasks; all also lists submitted and cancelled ones. Any other value reads as open. Default: open
limitinteger1 to 500; values outside the range are clamped, and a non-numeric value falls back to the default. Default: 100

Task fields

idstring (uuid)The task.
kindstringextraction, rules, evaluation or discrepancy.
evaluation_id / framework_document_idstring | nullThe evaluation or framework the task belongs to.
statusstringavailable, claimed, submitted or cancelled. claimed only while the lease runs.
execution_epochintegerRaised by each claim; sent with heartbeat, release and submit.
claimed_by_label / lease_expires_atstring | nullWho holds the claim and until when.
created_atstring (date-time)When the task was offered.
GET/v1/compliance/tasks/{taskId}
POST/v1/compliance/tasks/{taskId}/claim

Response fields

taskobjectThe claimed task, with the execution_epoch to send later.
summarystringWhat is asked, in one line.
instructionsstringThe platform's system instructions for the work.
inputstringThe document text(s) and numbered rules, or the framework's extracted requirements.
output_schemaobjectJSON Schema of the answer to submit.
how_to_answerstringGuidance on answering.

The package is built before the claim is taken, so a task whose document is still being read stays free and the call returns 409; claim it again a little later. A claim on a task that another agent holds, or that is already submitted or cancelled, also returns 409.

POST/v1/compliance/tasks/{taskId}/heartbeat

Body fields

execution_epoch*integerThe epoch the claim returned (at least 1).
POST/v1/compliance/tasks/{taskId}/release
POST/v1/compliance/tasks/{taskId}/submit

Body fields

execution_epoch*integerThe epoch the claim returned (at least 1).
answer*objectAn object matching the output_schema of the claimed package.

The result by task kind

extractionobject{ framework_document_id, requirement_count }.
rulesobject{ framework_document_id, rule_count }.
evaluationobjectThe ComplianceEvaluation, as returned by the evaluation routes.
discrepancyobject{ run_id, discrepancy_count }.

cURL: Work one task

# 1. See what waits
curl "https://api.talonic.com/v1/compliance/tasks" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# 2. Claim it and read the package (instructions, input, output_schema)
curl -X POST "https://api.talonic.com/v1/compliance/tasks/$TASK_ID/claim" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# 3. Submit an answer matching output_schema
curl -X POST "https://api.talonic.com/v1/compliance/tasks/$TASK_ID/submit" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"execution_epoch": 1, "answer": { "...": "per output_schema" }}'
A rejected submit stores nothing, and the refusal message names what is wrong, so the agent can correct the answer and submit again. See the Error Format section for the envelope the API returns.

Frequently asked questions

Who can switch the decider?+
An owner of the workspace, or a Talonic superadmin, using a key with the write scope. A member's key is refused with 403, as the setting is on the screen. Reading the setting needs only the read scope.
What happens to open tasks when I switch back to platform?+
They are cancelled and the response reports how many in cancelled. Evaluations and comparisons that waited for them end with an error that says to run them again; a framework reading or rules task keeps the framework's earlier reading or rules.
Why does a claim return 409?+
The task is held by another claimant, is already submitted or cancelled, or the package cannot be built yet because the task's document is still being read. In the second case the task stays free; claim it again a little later. Heartbeat, release and submit also return 409 when the caller does not hold the claim at the given epoch.
Is a submit safe to repeat?+
Yes, when the first submit was stored. Repeating it with the same claimant and epoch returns the stored result again instead of storing a second answer.

Related

Compliance Overview
Compliance Frameworks
Document Evaluations
Error Format