Handlers

Every task has a handler field that determines what it does. This page documents all available handlers and which fields are valid for each.

Handler types

chat_completion

Sends the current input to the LLM and waits for a reply. If the model calls a tool, the transition evaluates to "tool_call".

Key fields:

Transition values:

• "tool_call" — model issued one or more tool calls
• "executed" — model replied with text and finished (no tool calls)

(These are control tokens, not the model’s text. To branch on the model’s actual answer, use the route handler.)

Image input

Chat-history messages can carry image attachments beside their text content:

{ "role": "user", "content": "What is in this screenshot?",
  "images": [ { "data": "<base64>", "mime_type": "image/png" } ] }

A request containing images resolves only to models that declare the vision capability. When no matching vision-capable model is available the task fails with a distinct error — images are never silently dropped to fall back on a text-only model. The served OpenAI-compatible chat/completions endpoint also accepts the standard content-parts array form ({"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}) and decodes it into these attachments; only inline data: URIs are accepted — the runtime never fetches remote image URLs on a client’s behalf.

retry_policy

Controls automatic retries on transient LLM errors and optional model swapping after repeated failures.

Example:

{
  "id": "chat",
  "handler": "chat_completion",
  "system_instruction": "You are a helpful assistant. Today is {{now:2006-01-02}}.",
  "execute_config": {
    "model": "{{var:model}}",
    "provider": "{{var:provider}}",
    "tools": ["nws"]
  },
  "transition": {
    "branches": [
      { "operator": "equals", "when": "tool_call", "goto": "run_tools" },
      { "operator": "default", "when": "", "goto": "end" }
    ]
  }
}

execute_tool_calls

Executes the tool calls emitted by the previous chat_completion task, appends the results to the chat history, and loops back.

Key fields:

Example:

{
  "id": "run_tools",
  "handler": "execute_tool_calls",
  "input_var": "chat",
  "transition": {
    "branches": [
      { "operator": "default", "when": "", "goto": "chat" }
    ]
  }
}

tools

Calls a specific tool on a named tool directly — no LLM involved. Use for deterministic side effects (e.g. writing a file, calling a fixed API endpoint).

Key fields:

Example:

{
  "id": "write_file",
  "handler": "tools",
  "tools": {
    "name": "local_fs",
    "tool_name": "write_file",
    "args": { "path": "/tmp/output.txt" }
  }
}

route

Asks the LLM to classify the input into exactly one of the labels declared by this task’s own equals transition branches, then routes to the matching task. The routes are the branch when values — there is no separate schema; the chain you can read is the route set.

route is routing-only: the task’s input passes through to the next task unchanged. It produces a control-flow decision, never transformed data — so a router can never silently reshape what a downstream task sees.

The model’s answer is normalized before routing: the engine first looks for a case-insensitive exact match against a declared label, then a case-insensitive substring match (a label contained anywhere in the answer). Only if neither matches is the default branch taken. This substring fallback means a model that replies "I think this is urgent" still routes to the urgent label — but it also means overlapping labels (e.g. normal vs abnormal) can collide, so keep route labels distinct.

Key fields:

Common task fields

These fields are valid on any task, regardless of handler:

Template functions

The Go text/template fields — prompt_template and output_template — are rendered with the Sprig function library available in addition to the built-ins. This is what turns a structured task output into clean prompt input instead of Go’s default struct formatting:

{{ .scan_result | toJson }}            serialize a JSON/struct value as clean JSON
{{ .page_text | trunc 4000 }}            cap an oversized tool output
{{ (last .history.Messages).Content }}   pull a single field out

Without it, injecting a non-string task output (a tool’s JSON result, a chat history) into a template renders Go syntax like map[...] or {[{...}]} that the model cannot reliably parse — which is why transforming or evaluating tool output used to mean shelling out. toJson, trunc, and the rest of Sprig remove that step.

noop

Passes input through to the next task unchanged. Useful as an explicit routing node.

raise_error

Immediately halts the chain with the input string as the error message. Use as a terminal error branch — no transition needed.