Agent Editor and Step Types

View as Markdown

The Agent editor is where a repeatable Agent becomes an operational process. Use it to define sources, steps, variables, model settings, structured outputs, trigger behavior, schedules, benchmarks, and evidence expectations.

Agents are built from ordered steps. Each step should have a clear purpose, a predictable input, and a reviewable output.

Editor Areas

The editor commonly includes:

Sources: Clear Ideas Sites, saved Agent Connections, approved MCP tools, and optional web access
Steps: the ordered work the Agent performs
Triggers: webhooks, upload triggers, and sub-agent trigger settings
Benchmarks: output evaluation settings
Schedules: recurring run settings and variable presets
Variable Sets: reusable values for scheduled or repeatable runs

Use the smallest source and tool scope that can complete the Agent's job. If a step does not need sources, configure it to run without inherited sources.

Prompt Steps

Prompt steps ask an approved model to perform analysis, drafting, extraction, synthesis, classification, or transformation.

Use prompt steps for:

reading approved source context
summarizing or comparing documents
extracting structured fields
drafting text or final outputs
generating content for a later file output

Prompt steps can use Agent-level model defaults or override model and reasoning settings when a specific step needs different behavior.

Loop Steps

Loop steps group repeated work. Use them when the same logic should run over multiple items, records, documents, extracted values, or when a step should retry or improve an output until a goal is reached.

Loop steps are useful for:

reviewing many uploaded files
applying the same extraction pattern to each document
building section-by-section outputs
collecting repeated findings before a final summary step
revising one output until a benchmark, score, or other stop condition is met

Keep the loop's purpose narrow. If the loop grows into a separate reusable process, consider a sub-agent step instead.

Loop Configuration

The loop container controls how many times its child steps run and what value the loop returns.

Setting	Description
Source Variable	Optional value to iterate. Use this for map-style loops over arrays, object values, or delimited strings. Leave it empty for a bounded retry loop.
Run Condition	Optional expression checked before an iteration runs. Use it to gate or filter iterations.
Goal (Stop Condition)	Optional expression checked after an iteration finishes. When it evaluates to true, the loop stops before reaching the maximum iteration count.
Loop Item Variable	Variable name for the current source item. Defaults to `item`.
Loop Index Variable	Variable name for the current iteration index. Defaults to `index`.
Loop Result Variable	Variable name for the selected loop result. This value is available to the next loop iteration and later steps after the loop.
Max Iterations	Safety cap. For a loop without a source, this is the number of allowed attempts and defaults to 1.
Loop Output	Choose Collect all to return every iteration result, or Final value to return only the last selected result.

Loop goal example showing a retry loop that stops when the generated number is greater than five.

Goal Loops

Use goal loops for retry and improvement workflows. A goal is evaluated after the child steps finish, so it can reference variables produced during the current iteration.

For example, a loop with Goal (Stop Condition) set to:

{{number}} > 5

can stop once a child step writes number as 6. If you want the loop to stop when the value reaches five, use {{number}} >= 5.

For goal loops, Loop Output is usually Final value because the useful output is the last passing draft, score, or result. Collect all is better for map-style loops where every iteration is part of the final answer.

Loop Variables

Loop child steps can reference normal Agent variables, earlier step outputs, and variables created inside the loop. The runner also exposes loop memory:

{{loop.index}} and {{loop.iteration}}
{{loop.previous.output}}
{{loop.previous.variables.<key>}}
{{loop.current.output}}
{{loop.outputs}}

Use Loop Result Variable to carry a value forward from one iteration to the next. If a child step outputs the same variable, that value is used as the iteration result. Otherwise, the loop stores the last child output under the loop result variable.

Webhook Steps

Webhook steps send data out to an approved endpoint during an Agent run. They are different from inbound webhook triggers, which start a run.

Use webhook steps only when the Agent is intentionally allowed to create an external side effect, such as:

notifying another system that a review is complete
sending a generated summary to an approved endpoint
posting structured output to an internal process

Before adding a webhook step, confirm:

the endpoint is approved
the payload contains only intended data
request signing is enabled when required
retries and timeouts are reasonable
organization policy allows the egress pattern

See Controlled Tools and Egress.

Code Steps

Code steps run controlled code logic inside the Agent process. Use them for deterministic transformation, validation, formatting, or data shaping when a prompt step is not the right tool.

Code steps should not be used to bypass source policy or egress controls. They should have a clear input and output and should avoid hidden side effects.

Good uses include:

validating JSON or tabular output
transforming dates, totals, or records
preparing structured values for a later prompt or webhook
formatting a final result before file generation

Code steps receive Agent variables through CLEARIDEAS_VARIABLES and CLEARIDEAS_VAR_* environment variables. When an earlier step generates files, later steps can read artifact metadata from step-previous-artifacts, step-N-artifacts, or outputVariable-artifacts.

Generated Artifact Variables

When a step creates generated files, the Agent runner exposes sanitized artifact metadata to later steps:

{{step-previous-artifacts}} for artifacts from the immediately previous step
{{step-1-artifacts}}, {{step-2-artifacts}}, and other step-number references
{{report-artifacts}} when a step's output variable is report

Each artifact entry includes fields such as artifactId, filename, contentType, extension, bytes, checksum, skillId, stepIndex, and agentRunId. Use these variables when a later step should iterate over generated files, call MCP tools, or decide whether to create a new file or save a new version in a Site.

Sub-Agent Steps

Sub-agent steps call another Agent from within the current Agent. Use them to split a larger process into reusable components.

Sub-agent steps work well for:

reusable extraction routines
standardized quality checks
recurring review sections
specialized analysis used by multiple Agents

When selecting a sub-agent, map the parent Agent's values into the child Agent's variables and choose the Sites or source scope the child Agent should use. Avoid circular references. Clear Ideas validates sub-agent relationships to prevent self-reference and circular execution.

See Triggers and Webhooks and Variables and Variable Sets.

Human Approval Steps

Human approval steps pause execution for review. Use them when the Agent should not continue until a person confirms, corrects, or supplies information.

Use human approval for:

sensitive outputs
external-facing deliverables
decisions that need accountable review
missing context that only a person can provide

Runs waiting for human input should be treated as active work. Reviewers should understand what the Agent has already done, what it is asking for, and what happens after approval.

Structured Output Contracts

Prompt steps can define structured output expectations. Use structured output contracts when a later step, benchmark, webhook, or file-generation task depends on predictable JSON or field structure.

Use structured outputs for:

extracted metadata
classification results
validation checklists
payloads sent to webhook steps
tabular data used in generated files

Choose a model that supports structured outputs. If the selected model does not support the required output contract, update the model before relying on the step.

Step Design Checklist

Before saving or scheduling an Agent:

confirm each step has a clear purpose
use narrow source policy for steps that need sources
disable inherited sources for steps that do not need them
use structured output contracts where later steps depend on exact fields
keep webhook and code steps reviewable
add a human approval step before sensitive side effects
run a test and inspect step outputs
benchmark important production outputs