Step logic and AI

Use a rule when the answer can be calculated. Use AI when the answer needs interpretation. In a signup journey, “has this person created a project?” is a lookup and a count. “What project fits their stated goal?” needs a recommendation. These are different jobs, with different costs and checks.

maxinja can build either kind of step from your description. The difference is what happens after publication: saved logic runs directly; a runtime AI step calls a model as each customer reaches it.

Choose the right approach

The signup workflow guide connects Query, a compiled decision, AI and an email in one example. Start there if you want to build a journey before learning the configuration details.

Describe what you want

Select a step and its logic box is labelled for what it produces.

Write one plain sentence in it. The greyed example in the box shows the register to aim for: "Customers who purchased in the last 30 days" on a Find Records filter, "The count of contacts created this month" on a Query, "Route by the order's plan tier: free, pro, or enterprise" on a Switch.

An optional filter left empty can include every record of the selected type. Required decision and value fields still need configuration; an empty If/Else condition does not mean every customer takes the true branch.

Eight step types have no generated logic box: Scheduled Timestamp, Evaluated attribute threshold, Incoming Webhook, AI, For Each, HTTP Request, Send Email and Note. Neither does the empty placeholder. You configure those with ordinary fields.

The info button beside the label explains what that particular box controls. It is also where warnings live: errors appear under the box, warnings only inside that info card.

Point at the data the run carries

Type @ in the box and a picker opens listing everything the run carries at this point, with the step that produced each value. Choosing one drops a reference like {{ contact.email }} into your sentence. An amber marker means two earlier steps pass on the same name.

Evaluated attributes do not appear in the picker, even though the logic maxinja writes can read them. Ask for them by name in your sentence. These on-demand lookups are distinct from background Scheduled evaluated attributes, whose published generations can be pinned for an execution.

Send it to maxinja

Press Enter, or the round arrow button beside the box. maxinja opens with your sentence and the step attached, works through it, and reports what it changed.

maxinja may rename the step and rewrite its description in the same pass, so a step can retitle itself after you compile it.

Read back what it wrote

When it is done the box header reads Compiled with a green dot and opens to show three things:

• A plain-English description of what the logic actually does. This is what you check, not code.
• Depends on, listing the Schemas, Attributes and Segments the logic touches. A red Unknown schema, Unknown attribute or Unknown segment badge means something it relied on is gone.
• Reads, a read-only view of the data the step takes in and the related records it loads with it.

The generated logic itself never reaches your browser. There is nothing to view, copy or hand-edit: it stays on the server, and only maxinja can write it. What you review is the description and the dependency list.

Refine it

The box always shows the sentence that was saved, and you can edit it in place. While your edit is unsent, Not compiled yet and a Revert button appear under the box, and the header keeps reporting the state of what is actually saved rather than what you are typing. Send it again and maxinja replaces the whole thing, so rewrite the sentence rather than appending a correction.

Two things to know about the box:

• You cannot empty it to remove logic. An empty box will not compile. To drop a filter, ask maxinja, or pick a segment on the steps that offer one (Find Records, Delete Records, Record Created or Updated, Record Deleted), which replaces the box entirely and discards the sentence.
• The arrow greys out for a moment right after you change another field on the step, because maxinja reads the saved step. Wait for the save to settle.

For a smaller nudge, use the maxinja box at the top of the sidebar instead. It talks about the same step without replacing your sentence wholesale.

Compile once, or decide on every run

This is the distinction worth understanding before you build anything that runs at volume.

Compile a measurable rule such as an order-value comparison. Reserve a model evaluation for a decision that needs interpretation, and provide the evidence and permitted outcomes in the step's instructions. Compiled execution has no fixed internal fee; separate paid tools, model work and email overage still apply when used.

What puts a step in each mode

There is no switch to flip. A step decides on every run when it has a sentence and no compiled logic behind it. maxinja prefers to compile, and falls back only when the logic genuinely cannot be reduced to a rule. When it makes that choice it says so in its report.

The visible signal is a required field group titled AI on every run appearing under the logic box. When a step is compiled, that group is not there. Its disappearance confirms that this controller no longer requires a model evaluation on each run. Standard internal execution has no fixed step fee.

Only three steps can decide on every run

If/Else, Switch and Delay. On those, leaving the logic uncompiled is a publish warning, not a blocker, and the workflow ships:

The condition is not compiled yet, so AI evaluates it on every run, adding latency and cost.

Switch and Delay show the same sentence for their case selection and their delay. Every other step type refuses to publish until its logic is compiled, with a hard error such as The filter is not compiled yet. or The query is not compiled yet.

Pick the model and thinking depth

The AI on every run group holds two required pickers, Model and Thinking (Off, Low, Medium, High). Both start empty, and the workflow will not publish until you set them:

Pick the model for the runtime AI call.

Pick a thinking depth for the runtime AI call.

There is deliberately no workspace default behind them. Changing the model in your workspace AI settings can never move what a published workflow does or what it costs. The trade-off, as the field itself puts it: "Deeper thinking gives better judgment, but makes every run slower and pricier."

Choose from the models currently offered by the step. Use representative input and output complexity to compare speed and usage; model choice alone is not a fixed per-run price.

Decide from customer event history

If/Else offers Customer event history as an explicit alternative to generated condition logic. Choose the event collection, Has occurred or Has not occurred, Look back (days), and the Timing and matching settings.

The window is captured when the step reaches the decision and does not slide forward on every retry. Allow late events (seconds) waits beyond the captured window end before deciding. An absence condition requires at least 60 seconds of grace; the UI supports a lookback of 1–30 days and grace up to one day.

Match can be Events for this customer or object, or Same correlation ID as the triggering event. The latter requires that the trigger actually supplied a correlation ID. The run also needs exactly one authoritative customer or object; an ambiguous subject is an error, not permission to check everybody's activity.

If event storage is behind, the run waits for usable evidence. A decision that cannot be completed within its permitted lifetime fails rather than silently deciding that no event occurred. Once accepted, the decision and evidence are preserved for that step occurrence. Use this when the distinction between no activity and missing data matters to the email you are about to send.

What it costs

The same journey can have very different costs depending on how many times its AI steps run and how much context they use. Count parent and child runs and estimate model/tool work before increasing enrollment.

An AI step's cost depends on its input and output tokens, model, thinking and tools. A fixed per-recipient price inferred from one example is not reliable for a different journey. See workflow billing for the full charging model and the cap on concurrent runs.

Cost also depends on the data configured for the step, including expanded relationships and attributes. Supply what the decision needs. Passing a large profile and related records increases input size compared with passing the one fact a rule actually uses.

The runtime records the result of a model evaluation for its step occurrence. A completed If/Else, Switch, Delay or AI evaluation can be reused during safe recovery. An interrupted evaluation with an unknown outcome is not blindly rerun: the step requires reconciliation. A Delay also keeps its saved deadline rather than starting the wait again.

Choose between them

• Compile anything you can state as a rule over data the run already carries. "The order total is over $50" is a rule. Compiled, it avoids an AI interpretation on each execution and gives a repeatable decision over the same inputs.
• Leave it to a model only for genuine judgment. "This product fits the customer's interests" is not a rule. That is what the per-run mode is for.
• Supply the evidence. Ordinary controller logic evaluates the data configured for that step. Use Query or Find Records to bring other context into the run. If/Else also has a dedicated Customer event history mode for a bounded event-history decision, described below.
• Start cheap. A fast model with Thinking set to Off fits most per-run work. Raise the model or the depth only for nuanced multi-factor reasoning, long or messy context, or an outcome the rest of the run leans on heavily.
• Compiling is a one-time cost. It runs a strong model working through your workspace's data while you wait, which is why it is not instant. Later executions avoid that interpretation cost, while other model, metered tool and email overage costs remain. The benefit depends on how often the workflow runs and how complex the rule is.

The AI step always calls a model

The AI step has no compiled mode. It runs your prompt over the selected context and adds a structured answer that a later branch, record action or email can use.

For the Loopwell signup example, the input is the user’s role and stated goal. The prompt asks for one first-project suggestion, with a generic answer when that context is missing. The result can be a text field named suggestion, passed on as firstProjectGuidance. The earlier Query and If/Else decide whether the person needs this message; the model does not guess their project count.

Configure Expected data, Prompt, Result shape, and the AI settings group’s required Model and Thinking. The model is pinned to the step; changing workspace defaults does not change a published workflow.

Inspect the input and result in run history after execution. Matching the result shape establishes structure, not the quality of a recommendation. Check whether the answer uses the supplied facts, respects missing context and is suitable for its next use.

The answer is run data, not an automatic profile update. If another campaign needs the recommendation, add Create or Update Records to save the chosen field on the identified contact. If it is only needed by this journey's email, pass the named output to that email with Liquid.

The AI step does not automatically receive the later email's brand kit. Include the writing guidance it needs in its prompt or selected data. Inserting its answer with Liquid does not rewrite that answer in the email's brand voice.

Missing customer context and failed generation need different treatment. A prompt can request generic guidance when a field is absent. It cannot recover from a model or output-validation failure: a terminal AI-step error ends the run, so a later email is not a fallback for that failed step. Review a controlled execution before publishing to a wider audience.

Without tools, the step requests one structured answer. With tools, it can make several model turns and tool calls, up to the configured 15-turn bound. That is a limit, not a cost estimate. MCP tools may act on connected systems according to their permissions; review those capabilities as part of publishing the journey.

Review MCP changes and uncertain outcomes

MCP selection grants the connected server's tools to the AI step. The runtime captures its endpoint, credentials, tool definitions and instructions, and checks that they still match before using them. Changing a server's settings or tool contract can stop execution; the step does not silently continue with a different tool.

MCP tools are not guaranteed read-only. A tool may change the connected service, and an external service can accept an action before its response is lost. Inspect that service and the run's recovery reason before triggering replacement work. Needs attention means the run does not automatically continue; Terminate run ends its lineage without reversing accepted effects.

The workflow grants are bounded: at most 32 servers and 128 tools, with up to 64 tool calls for a decision. An individual tool input or result is limited to 256 KiB, and aggregate MCP response data to 4 MiB. Large tool catalogs, changed descriptors or oversized results can fail the step. Supply narrower context or a narrower tool contract rather than expecting an unrestricted loop.

Personalized email bills per recipient

A Send Email step has no AI on every run group, but it can still call a model: surviving Adaptyle instructions are applied while that recipient’s message is prepared for sending. Personalization usage is per recipient, and its model and thinking settings live on the email itself. Adding both an AI step and Adaptyle means two separate generation tasks; use each for a defined purpose.

Content with no Adaptyle instructions in it renders with no model call and no AI cost. Ordinary Liquid substitution does not itself call a model; workflow fees, any configured data calculation and email allowance rules remain separate.

Keep your steps compiled

Compiled logic is dropped when the thing it was built against changes. After any of these, the step goes back to uncompiled and needs a new compile:

• Editing the sentence and saving it.
• Changing the schema the step is bound to.
• Adding, removing or renaming a Switch case. Reordering them is safe.
• Picking a segment, which replaces the box and discards the sentence.

When changing the data model or a referenced segment, inspect the dependent steps and the setup review outcome. A saved edit does not establish that every published workflow has adopted a new definition. Reopen the step, read Depends on and Reads, and regenerate affected logic when required before publication.

Related

• Workflows: the canvas, runs, versioning, and the trigger API.
• Workflow block library: every step type and what you configure on it.
• Workflow billing: model and tool usage, email allowances, and the concurrent run cap.
• Workflow runs: what a run did, and why one failed.
• maxinja: the assistant that compiles your step logic.
• Segments: reusable contact filters you can pick instead of writing a condition.
• Evaluated attributes: on-demand customer facts and related-record lookups.
• Scheduled evaluated attributes: background calculations with published values.