Skip to main content

Deciders

Versioned question sets answered against an input, producing append-only decisions confined to each question's answer space.

Overview​

A decider is a named set of questions. Asked about an input — a ticket, a message, a record — it produces a decision: one answer per question. The questions, the input and the answers are the shapes of OpenAI's Decisions API, and every decision names the question-set version it was answered under.

A decider is answered by exactly one backend: a tool-less agent, which is shown the questions and the input and answers within a schema compiled from them, or an http or pipeline tool of yours, which receives { input, questions } and answers in the contract below. A tool that forwards to OpenAI's /v1/decisions, with model as a preset, answers a decider as it is.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path. It serves two collections — /deciders and /decisions — under that project prefix.

On every plan

Deciders are not gated by plan. A decision is a run: it counts against the plan's monthly runs, and one answered by an agent on a managed provider spends the balance like any other generation.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Deciders.

Data Model​

Decider​

FieldTypeDescription
policy_idsstring[]The policies every decision's backend acts under. Empty for one written without any, which does not run until a write gives it one.
idstring
project_idstring
namestring
descriptionstring, nullable
agent_idstring, nullableThe tool-less agent that answers; null when a tool does
tool_idstring, nullableThe tool that answers, run with no action; null when an agent does
versionintegerThe question set's version. Bumped only by a write that changes questions.
questionsobject[]The questions, in the order the model is shown them.
created_atstring (date-time)
updated_atstring (date-time)

name is unique within the project. tool_id names an http or pipeline tool. A decider holds 1 to 20 questions.

Decision​

FieldTypeDescription
idstring
project_idstring
decider_idstring, nullableThe decider asked; kept after the decider is deleted. Null for a decision sent with its own questions.
decider_versioninteger, nullableThe question-set version the decision was answered under
questionsobject[], nullableThe questions a decision sent with its own was answered under. Null for a decider's decision, whose questions are its decider_version.
statusqueued | running | completed | failed
answersobject[], nullableOne answer per question, in question order. Null until the decision completes, then never rewritten.
answers_by_nameobject, nullableThe same answers keyed by question name, so a JSON Logic path reads one by name (answers_by_name.department.choice) rather than by position.
errorobject, nullableWhy a failed decision failed.
generation_idstring, nullableThe generation that answered, once one has; null for a tool backend. Its receipt carries what the decision cost.
metadataobjectCaller-owned annotations on a resource, stored as the object they were written as: the types a value was written with are the types a read returns, so a filter can ask an ordering question about a number. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase. No key is reserved, and that is the point: every piece of state the platform owns lives in its own typed column, so nothing written here reaches platform state. The platform never reads the bag — it is not an IAM context, not a policy input and not part of a prompt — which is what separates it from a tag bag.
created_atstring (date-time)
updated_atstring (date-time)

id is the polling handle. metadata holds your own identifiers, written once with the decision.

The evaluated input is not stored. Put the id of what was judged in metadata to find the decision again.

Key Concepts​

Questions and answers​

Every question has a type, a name (unique, letters, digits and underscores) and instructions.

typeDeclaresAnswer
predicatenothing more{ "type": "predicate", "name", "probability" }
choicechoices: 2 to 20 { value, description }{ "type": "choice", "name", "choice", "probabilities"?, "confidence"? }
scorelevels: 2 to 20 ordered { label, description }{ "type": "score", "name", "score", "probabilities"?, "confidence"? }

An agent answers a predicate with probability 1 or 0 and a score with the level index. probabilities ([{ value, probability }], plus label on a score) and confidence come only from a tool, carried as it supplied them; a tool may answer a score between two levels.

Input​

input is a string; a list of user messages whose content is a string or input_text and base64 input_image parts; or any other JSON value, which an agent is shown as indented JSON.

Versions​

Changing questions archives the previous set and moves version; a rename, a new description or a new backend does not. Read the questions a decision was answered under with GET /v1/projects/{project_id}/deciders/{decider_id}/versions/{version}, and pass expected_version on PATCH /v1/projects/{project_id}/deciders/{decider_id} to refuse a stale write with 409.

A tool backend​

The tool is called with { "input": …, "questions": [ … ] } and answers { "answers": [ { "name": …, "probability" | "choice" | "score": …, … } ] }, one entry per question in any order. Any other answer field, a repeated or unknown name, or a value outside the answer space fails the decision with DECISION_ANSWER_INVALID. An engine that speaks a close dialect is bridged with a pipeline tool: a step's input maps the request, the pipeline's output maps the answer.

A client, mcp tool, or a tool whose preset_parameters set input or questions, cannot answer a decision: 400 DECIDER_TOOL_NOT_CALLABLE. A tool a decider names cannot be deleted (409 TOOL_HAS_DEPENDENTS), nor can its agent.

Decision authority​

A decision's backend runs under the decider's policy_ids, capped by the caller who requests it. A backend that grant may not start (agents:CreateAgentGeneration or tools:CallTool) is refused 403 ACTION_NOT_HELD before the decision is recorded, even when the caller may start it. Changing policy_ids leaves version alone. A decider with empty policy_ids is allowed nothing; an inline decision runs as its caller.

policy_ids is required on create (400 VALIDATION_FAILED), and every write needs the backend's start action. The writer must hold every grant the policies carry (403 POLICY_GRANT_NOT_HELD); a policy a decider names cannot be deleted (409 POLICY_HAS_DEPENDENTS).

Requesting a decision​

POST /v1/projects/{project_id}/deciders/{decider_id}/decisions takes input, optional metadata and wait. POST /v1/projects/{project_id}/decisions takes the questions with the request, as OpenAI's endpoint does, and names agent_id or tool_id in place of model. With wait omitted the answer is 201 with the decision queued; poll GET /v1/projects/{project_id}/decisions/{decision_id} or subscribe to decisions.completed and decisions.failed on a webhook. With wait: true it is 201 with the decision settled. A failed decision is terminal: request a new one. Its error follows the generation's rule for the provider's own answer.

Before anything reaches the runtime, a decision clears the same gates a generation does. Its backend is read off the decider, or off the body of an inline one: a decision an agent on a managed provider answers is refused while the balance is negative (402 INSUFFICIENT_CREDIT), and its model must carry a price (409 MODEL_NOT_PRICED); one a tool answers is a run that spends no credit. Either is refused when a Free account is out of runs (403 PLAN_LIMIT_REACHED). This holds however the decision arrives: a call to this API or an agent's tool call.

Examples​

Create a decider over an agent​

pol_V1StGXR8Z5jdHi6B allows agents:CreateAgentGeneration on the agent (Decision authority).

naturali create-decider \
--project-id proj_V1StGXR8Z5jdHi6B \
--name support-triage \
--policy-ids pol_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--questions '[
{
"type": "choice",
"name": "route",
"instructions": "Which team should own this ticket?",
"choices": [
{ "value": "billing", "description": "Charges, refunds, invoices" },
{ "value": "technical", "description": "Errors, outages" }
]
},
{
"type": "predicate",
"name": "needs_human",
"instructions": "Must a person read this before any automated reply?"
}
]'

Request a decision and wait for it​

naturali create-decision \
--project-id proj_V1StGXR8Z5jdHi6B \
--decider-id dcd_V1StGXR8Z5jdHi6B \
--input 'I was charged twice for the same order.' \
--metadata '{ "ticket_id": "ZD-48213" }' \
--wait true

Ask questions inline​

naturali create-inline-decision \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--questions '[{ "type": "predicate", "name": "refund", "instructions": "Is the customer asking for money back?" }]' \
--input 'I was charged twice for the same order.' \
--wait true