Skip to content

Decisions and routing ​

Use .decide() when a stage needs a bounded judgment: a label, a score, or a probability. Use .route() when that judgment chooses which branch runs next. Both stages call typed decisions, so answers are validated before the next stage receives them.

text
Input -> department (route) ─ billing   -> open-refund-case  ─┐
                            └ technical -> open-incident     ─┴-> Output

Pass a decision model from any adapter, such as @anvia/jev or OpenAI decisions.

1. Add a decision stage ​

.decide() maps the current value to decision state, asks the questions, and returns the DecisionResult from decide(). The next stage receives typed answers, optional usage, and the provider's rawResponse:

ts
import { check, score } from '@anvia/core/decision'

const assessTicket = new Pipeline({ id: 'assess-ticket', inputSchema: TicketInput })
  .decide({
    id: 'assess',
    model,
    state: ({ input: ticket }) => ({ subject: ticket.subject, body: ticket.body }),
    questions: {
      urgent: check({ instructions: 'Does this ticket need a response within one hour?' }),
      severity: score({
        instructions: 'How severe is the customer impact?',
        rubric: ['Minor', 'Degraded', 'Blocked'],
      }),
    },
  })
  .step({
    id: 'set-priority',
    run: ({ input: { answers } }) => ({
      page: answers.urgent.probability >= 0.8 || answers.severity.score >= 1.5,
      severity: answers.severity.score,
    }),
  })

Thresholds stay in TypeScript. A probability or score is an estimate, so the step that reads it decides what counts as urgent.

2. Route to one branch ​

.route() asks one choice question and runs only the branch pipeline keyed by the selected option:

ts
import { Pipeline } from '@anvia/core/pipeline'
import { choice, type DecisionModel } from '@anvia/core/decision'
import { z } from 'zod'

const Ticket = z.object({
  subject: z.string().min(1),
  body: z.string().min(1),
})

const billing = new Pipeline({ id: 'billing-flow', inputSchema: Ticket }).step({
  id: 'open-refund-case',
  run: ({ input: ticket }) => ({ queue: 'billing', subject: ticket.subject }),
})

const technical = new Pipeline({ id: 'technical-flow', inputSchema: Ticket }).step({
  id: 'open-incident',
  run: ({ input: ticket }) => ({ queue: 'engineering', subject: ticket.subject }),
})

export function createTriage(model: DecisionModel) {
  return new Pipeline({ id: 'ticket-triage', inputSchema: Ticket }).route({
    id: 'department',
    model,
    state: ({ input: ticket }) => ({ subject: ticket.subject, body: ticket.body }),
    question: choice({
      instructions: 'Which team should handle this ticket?',
      options: {
        billing: 'Payments, invoices, and refunds',
        technical: 'Product bugs, outages, and errors',
      },
    }),
    branches: { billing, technical },
    retries: { maxAttempts: 2 },
  })
}

Every option needs exactly one branch, and every branch must be an option. A missing or extra branch is a TypeScript error and also throws a TypeError when the stage is added. The question is validated at the same point, so an invalid hand-written question fails before any run starts.

Each branch receives the same value the route stage received. Branch pipelines validate that value with their own inputSchema.

3. Read the route output ​

The route output is discriminated by branch:

ts
const { output: routed } = await createTriage(model).run({
  input: { subject: 'Charged twice', body: 'My card was billed two times this month.' },
})

if (routed.branch === 'billing') {
  console.log(routed.output.queue) // typed as the billing pipeline's output
}
console.log(routed.answer.confidence) // provider-reported, when available
console.log(routed.usage) // usage of the routing decision, when reported
FieldMeaning
branchThe selected option key.
answerThe validated ChoiceAnswer, including probabilities and confidence when the provider reports them.
usageToken usage of the routing decision only. Omitted when the provider does not report it.
outputThe selected branch pipeline's output.

The exported RouteOutput<Branches> type describes this union.

4. Pass execution controls ​

Both stages accept retries and providerOptions with the same meaning as decide() execution controls. Both receive the run's abortSignal, so cancelling the run cancels the decision call and the selected branch.

5. Handle failures ​

FailureResult
The provider returns a malformed answer or an unknown optionDecisionProviderOutputError; the stage fails and no branch runs.
The provider declines the questionDecisionRefusalError; the stage fails and no branch runs.
The model cannot answer the question typeDecisionCapabilityError before any provider call.
The selected branch throwsThe branch's stage, the branch, and the route stage each emit stage_failed, then the run rejects with the branch error.

See Errors and validation for the decision error contract and Runs and errors for run-level handling.

6. Inspect the graph ​

Decision stages appear as decision nodes. A route appears as a route node with one branch node per option. Edges from the route to its branches carry the option key as their label, and route branch nodes carry branchOf: 'route'. Parallel branch nodes carry branchOf: 'parallel'.

Only the selected branch emits stage events, so a run shows which path was taken. Studio logs decision stages, route stages, and route branches under the decision category.

Choose the right stage ​

NeedUse
A label, score, or probability to read in a later step.decide()
One of several known flows, selected per input.route()
Several independent flows on the same value.parallel()
Fields extracted from text under a schema.extract()
An open-ended choice of tools or next steps.agent()
A choice that depends only on known fieldsA .step() with ordinary TypeScript

Next, learn how to compose reusable pipelines.

Built for Anvia.