AI Steps
An AI step is the specialist on your assembly line: where every other block follows fixed rules, an agent reads, understands, and decides. Agents are genuinely powerful — a single agent step can carry a whole multi-part job on its own: research something, create the files it needs, call several tools, and coordinate the work end to end. That's how classic automations were built, and they still work great. The trade-off is simple: AI steps are the only blocks that use credits, and their output varies run to run. So the craft is choosing per step — free blocks where the rules are strict and predictable, agent steps where the work needs judgment or dynamism: dynamic files, flexible coordination, handling whatever shape the data arrives in.
Agent Step
One agent, one job. Click the block to set up:
| Setting | What it does |
|---|---|
| Agent | Which agent runs this step — the default Nirvai agent or any agent you can use. Pick specialists for specialist work. |
| Instructions | What to do, written like a brief to a capable colleague. Use {{variables}} to hand it the data from earlier steps — they're filled in with real values when the step runs. |
| Output | Where the result goes, so later steps can use it. |
Example instructions
Read the deal below and write a short, friendly welcome email to the new customer. Deal name:
{{trigger.dealname}}— Amount:{{trigger.amount}}Keep it under 120 words and sign as "The Nirvai Team".
Free vs. structured output
By default an agent answers freely — great for prose, emails, summaries. If a later block needs to reach into the result (say, pick out score and reason separately), switch the step to structured output and define the fields you expect. It's the difference between asking for an essay and handing over a form to fill in: with a form, every later step knows exactly which box to read, and the variable picker marks those fields as Verified structure. If the agent finishes without filling the form correctly, Nirvai sends it back to fix it before the run continues.
Router
A router is a manager standing at a fork: it looks at what the previous step produced and decides which path the run takes. You give it the question to judge ("Is this message a complaint, a question, or praise?") and one outgoing path per answer. Because a router thinks, it uses credits — when your decision is a simple comparison ("amount over 1000?"), use the free Condition or Switch block instead.
One big agent step or several small ones?
Both are valid — this is a cost-and-control decision, not a capability limit:
| Shape | When it wins |
|---|---|
| One agent step doing a multi-part job | The work is dynamic — research + write + coordinate, files whose shape you can't predict, judgment at every turn. One capable agent handles it in a single go. |
| Several steps: free blocks around small agent steps | Most of the job is mechanical and rule-based. The free blocks do the fixed parts for nothing, and each small agent step is cheaper and easier to inspect. |
This choice is exactly why automations were upgraded: the old agent-only automations still work well — free blocks just let you stop paying for the parts that never needed intelligence.
Common mistakes
| Mistake | Better approach |
|---|---|
| Using an agent for a fixed rule ("if amount > 1000") | That's a free Condition — save the credits for real judgment. |
| Breaking a genuinely dynamic job into many rigid blocks | If the flow needs flexibility more than strict rules, one agent step coordinating the whole job is the better (and simpler) build. |
| Instructions that don't mention the incoming data | Reference it explicitly with {{variables}} so the agent knows exactly what to work with. |
| Expecting later steps to read fields from a free-form answer | Turn on structured output and define the fields. |
What's next
- Logic & Action Blocks — the free blocks that surround your AI steps
- Data Between Steps — how
{{variables}}carry data from step to step