Documentation

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, or extracted values.

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

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

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

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