Handlers

Handlers define what happens when a trigger fires. They contain execution blocks that run in sequence.

Handler Structure

Each block has a human-readable name (shown in debug UI) and a block field that determines its behavior.

Block Kinds

next-message

Generate a response from the LLM:

With options:

For structured output (typed JSON response):

When responseType is specified:

• The LLM generates JSON matching the type schema
• The output variable receives the parsed object (not plain text)
• The client receives a UIObjectPart for custom rendering

See Types for more details.

add-message

Add a message to the conversation:

For internal directives (LLM sees it, user doesn't):

For structured user input (object shown in UI, prompt for LLM context):

When uiContent is set:

• The variable value is shown in the UI (string → text part, object → object part)
• The prompt text is hidden from the UI but kept for LLM context
• Useful for rich UI interactions where the visual differs from the LLM context

tool-call

Call a tool deterministically:

set-resource

Update a persistent resource:

start-thread

Create a named conversation thread:

The model field can also reference a variable for dynamic model selection:

serialize-thread

Convert conversation to text:

generate-image

Generate an image from a prompt variable:

Edit an existing image using reference images:

This block is for deterministic image generation pipelines where the prompt is constructed programmatically (e.g., via prompt engineering in a separate thread). When referenceImages are provided, the prompt describes how to modify those images.

For agentic image generation where the LLM decides when to generate, configure imageModel in the agent config.

Display Modes

Every block has a display property:

Complete Example

Block Input Mapping

The input field on blocks controls which variables are passed to the prompt. Only variables listed in input are available for interpolation.

Variables can come from protocol.input, protocol.resources, protocol.variables, trigger.input, or outputs from prior blocks.

Independent Blocks

Use independent: true for content that shouldn't go to the main chat:

This is useful for:

• Background processing
• Summarization in separate threads
• Generating content for tools