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
• "stop" — model replied with text and stopped
• "length" — reply was truncated at token limit

compact_policy

When the chat history approaches token_limit, the engine summarises older messages in place rather than erroring or sliding the window.

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>",
    "hooks": ["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" }
    ]
  }
}

hook

Calls a specific tool on a named hook 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": "hook",
  "hook": {
    "name": "local_fs",
    "tool_name": "write_file",
    "args": { "path": "/tmp/output.txt" }
  }
}

prompt_to_string

Renders a Go template string using accumulated task output variables. Useful for building prompts that combine outputs from multiple previous tasks.

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.