Agent Steps

Steps are the building blocks of an agent workflow. Each agent contains an ordered list of steps that execute sequentially — the output of one step becomes the input to the next. Steps can also reference outputs from any earlier step using substitution variables.

Step Types

Agent steps are organized into seven categories, matching the step selector in the editor:

Common Fields

Every step type shares these base fields:

Child Steps (Composite Steps)

Most step types are composite — they can contain nested child steps. Child steps execute after their parent and receive the parent's output as input.

Nearly every step type is composite and supports child_steps. The only step types that do not support child steps are the terminal / non-composite ones: Display Result, Streaming Result, Item Value, and Retry.

For Each is different from other composite steps: its children are a body template that runs once per iteration of a runtime-resolved list, not a one-shot sequence. See the For Each Step reference for iteration variables, slicing, parallelism, and trace behavior. Also note: display_result, streaming_result, human_in_the_loop, and wait are not allowed inside a For Each body — multiple iterations would produce ambiguous UI output (and, for the parking steps, ambiguous resumption).

If / Else and Switch also dispatch into named subtrees (then_steps / else_steps for If / Else; per-case steps plus else_steps for Switch). Each invocation runs one branch (or no branch when nothing matches and there is no else). After the chosen branch completes, the branch's output flows into the If / Else or Switch step's own child_steps — the post-branch continuation chain that always runs. display_result and streaming_result are not allowed inside any branch subtree (then_steps / else_steps / cases[].steps) because they are terminal output sinks; place them in the branching step's child_steps instead, with each branch ending in a content-producing step (text / prompt_call). See the If / Else and Switch references for branch markers and trace behavior.

Human-in-the-Loop pauses the run, asks one or more humans to pick from a choice list, and resumes with the chosen outcome as the step's output. Downstream if_else / switch / gate steps route on {{step.<hitl_id>.output}}. See the Human-in-the-Loop concept page for the lifecycle / quorum / billing overview and the Human-in-the-Loop Step reference for the field-level configuration.

String Substitutions

Most step fields support dynamic variable substitution using {{placeholder}} syntax. This lets steps reference agent input, other steps' outputs, metadata, and runtime values.

Available Variables

Date & Time Variables

Date and time variables accept an IANA timezone and an optional locale code. Currently, the locale code selects the format pattern (for example, ordering and separators), but month and day names are rendered in English by the backend implementation.

Function-style syntax is also supported: {{datetime(UTC)}} or {{datetime(UTC, es)}}. As with the inline syntax, the locale argument currently affects only the pattern, not the language of month or day names.

Unrecognized placeholders are left unchanged in the output, making it safe to include template syntax that should not be resolved.

File Attachments

For a high-level introduction with worked examples (uploads, generated images, per-file fan-out), see the Attachments guide. The section below is the grammar and routing reference.

Agents accept file attachments alongside text input. When you trigger a run with one or more uploaded files (image, audio, video, PDF, document), each file flows through the agent in two parallel channels:

1. Native binary — capable LLMs (Claude, Gemini, Nova, GPT-4o-class) receive the raw bytes as a media content block.
2. Extracted text — every file is also OCR'd / transcribed; that text is what the LLM sees when the configured model is text-only, and what governance evaluators and the prompt scanner inspect.

A step "sees" attachments only when its template declares the dependency. This narrow-visibility rule prevents trigger uploads from leaking into intermediate steps that don't actually want them.

How to reference attachments

Two declaration forms drive routing:

• Implicit — referencing {{input}}, {{agent.input}}, or {{step.<id>.input|output}} brings in all attachments carried on that source. Templates that already use these placeholders keep working unchanged.
• Explicit — the {{attachments[…]}} family narrows the set. When any explicit selector targets a source, the implicit "all" is replaced by the narrowed subset.

Selector syntax

Multi-match is allowed — a glob that matches three files surfaces three media blocks. Zero-match is a no-op (logged at INFO).

In the resolved prompt text, each placeholder expands to [attachment: <filename>] markers so the LLM sees a textual anchor; the binary flows out-of-band as a native media block (or, when the model is text-only, as the OCR/transcript text under an --- attachment text --- separator).

Per-step attachments config field

Steps that consume a manifest (send_email, write_aws_s3_object, webhook_call, call_agent, publish_content, write_content_attachment, for_each, display_result, streaming_result, add_chat_turn) expose an Attachments config field — a list of {{…}} reference expressions that together narrow which manifest entries the step ingests. Each expression selects attachments from one source — this step's input ({{attachments[…]}}), the trigger uploads ({{agent.attachments[…]}}), or a specific upstream step's output files ({{step.<id>.attachments[…]}}) — by index, filename glob, or all:

[
  "{{attachments[*.png]}}",
  "{{agent.attachments[invoice.pdf]}}",
  "{{step.gen-image.attachments[0]}}"
]

Expressions union their matches in list order; duplicates (same (source, step_id, storage_key)) are pruned with first-seen winning. On consumer steps (send_email, write_aws_s3_object, webhook_call, call_agent, publish_content, write_content_attachment, for_each), null / empty list defaults to "every attachment on the step's input manifest". On the result steps (display_result, streaming_result) and add_chat_turn the default is text only — they surface/persist attachments only when at least one reference is set; leaving the list empty attaches nothing.

The step editor's Attachments widget builds the reference list row-by-row with a live match-count preview. See Attachments references field for the full reference.

Multi-modal routing

For each attachment a prompt_call step receives, the runtime picks one of three paths based on the configured model's capabilities:

1. Native — when the model declares support for the attachment's MIME (e.g. Claude Haiku 4.5 + image/png), the binary is sent as a media content block.
2. OCR / transcript demotion — when the model can't handle the MIME, the extracted-text counterpart is stitched onto the prompt body so the LLM still sees the content.
3. Dropped — no text counterpart available; an INFO log records the attachment, model, and reason.

Each prompt-call step emits a routing summary: Attachment routing for step <id> on model <name>: considered=N native=N demoted=N dropped=N — the forensic anchor when "the model didn't see my image" comes up.

See Send a file for the UI / MCP / API flow that uploads a file and attaches it to a run.

Metadata Filters

The Retrieval step supports MongoDB-style metadata filters to narrow results based on document metadata fields. Any step that accepts a filter field uses this same syntax.

Filter Operators

Logical Operators

Filter Examples

Simple field match (implicit AND):

{
  "category": { "$eq": "technology" },
  "status": { "$ne": "draft" }
}

Using $or:

{
  "$or": [
    { "category": { "$eq": "technology" } },
    { "category": { "$eq": "science" } }
  ]
}

Complex nested filter:

{
  "$and": [
    { "published_date": { "$gte": "2026-01-01" } },
    {
      "$or": [
        { "category": { "$in": ["news", "analysis"] } },
        { "priority": { "$gt": 5 } }
      ]
    },
    { "author": { "$exists": true } }
  ]
}

With substitution variables:

{
  "category": { "$eq": "{{metadata.category}}" },
  "published_date": { "$gte": "{{metadata.start_date}}" }
}

Step Execution Order

Steps execute as a directed acyclic graph (DAG). In the simplest case, steps run sequentially top-to-bottom. With child steps and parallel branches (via merge wait_for), the execution order follows these rules:

1. Root steps execute first, in order
2. Child steps execute after their parent completes, receiving the parent's output as input
3. Merge steps wait for every sibling step named in their wait_for list before executing
4. Awaited branches may continue running in parallel after the merge fires
5. A step only executes after all its dependencies have completed

Step Caching

The Prompt Call and Retrieval steps support result caching to reduce costs and improve performance:

Caching is particularly useful for:

• Retrieval steps that run on the same knowledge base frequently
• Prompt calls with deterministic outputs (e.g., classification tasks with temperature: 0)
• Reducing credit usage for repeated operations

AI Assistant

The AI assistant helps you configure steps by generating configurations from natural language descriptions. It understands your full agent workflow — including all steps and their relationships — and can suggest appropriate values.

Supported step types:

To use the AI assistant, open a supported step and click the AI Assistant button. Describe what you want in natural language, and the assistant will generate or refine the configuration.

Next Steps

• Agent Triggers — Configure when and how agents run
• Agents Overview — Back to the agents overview
• Knowledge Bases — Connect data sources for retrieval steps
• Content Sources — Understand how content flows into knowledge bases
• Memory Banks — Create and manage persistent memory for your agents
• API Examples — Code samples for working with agents