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:

| execute_config.retry_policy | No | LLM-call retry and model-fallback settings — see retry_policy below. |

Transition values:

• "tool-call" — model issued one or more tool calls
• "stop" — model replied with text and stopped
• "length" — reply was truncated at token limit

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 <span v-pre>{{now:2006-01-02}}</span>.",
  "execute_config": {
    "model": "<span v-pre>{{var:model}}</span>",
    "provider": "<span v-pre>{{var:provider}}</span>",
    "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. If the model's answer matches no declared label, the default branch is taken.

Key fields:

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:

<span v-pre>{{ .scan_result | toJson }}</span>            serialize a JSON/struct value as clean JSON
<span v-pre>{{ .page_text | trunc 4000 }}</span>            cap an oversized tool output
<span v-pre>{{ (last .history.Messages).Content }}</span>   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.