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" }
  }
}

prompt_to_string

Sends the prompt to the LLM and returns the response as a plain string. Use prompt_template to build the prompt from previous task outputs.

Key fields:

noop

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

prompt_to_int

Sends the prompt to the LLM and parses the reply as an integer. The eval string is the decimal representation of the result (e.g. "42"). Use with the in_range or equals operators in branches.

Key fields:

raise_error

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