Analyze with AI

Analyze with AI runs an instruction through a model and returns an object with the fields you defined. The step is headless: it does not talk to the customer, publish a message or invoke tools. Use it to classify, extract or normalize data before a Condition or an Action.

The model does not receive the conversation automatically. It receives only the text assembled in Instruction, after SquadOS substitutes the variables. To analyze a conversation, include a conversation variable that is available at that point, usually conversation.transcript.

Add and configure the step

In the automation editor:

1. add Analyze with AI from the AI section of the palette;
2. choose the Model, or keep the default;
3. write the Instruction and insert the required variables;
4. open Output fields and add at least one field;
5. connect the step to the following nodes and click Save.

Saving publishes a new version of the graph. Publication rejects an empty output schema, an empty, invalid or duplicate field name, an unknown type, an enumeration with fewer than two entries and a variable that is unavailable on that path.

The editor labels the implicit choice Organization default model, but the current runtime uses the platform’s active global default model. Select a model explicitly if the choice must remain stable. This discrepancy is recorded in the product audit.

Write the instruction

The instruction accepts the variables available above this step. A useful instruction states the input material, the decision and the criteria for every output. For example:

Read the transcript below.
Classify the intent as purchase, support or other.
Mark urgency only when the customer gives a deadline within 24 hours.

Transcript:
{{conversation.transcript}}

Not every trigger provides a conversation. In List, Schedule or Audience flows, use only the groups shown in the picker, such as contact, list or trigger payload. If conversation.transcript is unavailable, create or obtain the required context before the analysis.

Do not leave Instruction empty. Publication currently allows it: the model can still be called, consume credits and return values without useful context. Do not ask the analysis to search a knowledge base, send messages or perform actions either. The node does not provide tools; the graph must make the decision and perform the action in separate steps.

Define output fields

Each Output fields item has:

• Name: the result key and variable suffix. Use only letters, numbers and _, with no spaces;
• Type: Text, Number, Yes or no or One of the options;
• Options: appears for One of the options and accepts comma-separated values;
• Description: tells the model what the field means and how to decide it.

Use stable names such as intent, urgent and estimated_value. For an enumeration, provide at least two distinct, unambiguous options, such as purchase, support, other. The product currently accepts two identical entries as though they were two options; do not rely on that behavior.

Describe each field as a verifiable rule. For example:

• intent, One of the options: “Use purchase for explicit intent to buy; support for a problem with current use; other otherwise.”
• urgent, Yes or no: “True only when the customer mentions a deadline within 24 hours.”
• summary, Text: “One factual sentence, without instructions or facts that are absent from the input.”

SquadOS requires the response to match these types. If the model returns truncated or invalid JSON, the step may retry up to two times. Network, authentication and provider errors do not receive the same automatic retry.

Use the result

After a successful run, every field becomes a variable under the node identifier. If the step is n5 and the field is named intent, use {{n5.intent}}.

The picker offers the output only to downstream nodes on paths that actually pass through the analysis. A parallel branch does not receive that result. The most common pattern is:

1. Analyze with AI returns the fields;
2. Condition compares an output such as {{n5.intent}};
3. each branch applies tags, stores metadata, sends content or ends the flow.

Do not treat the classification as authorization for an irreversible action without an additional rule. A transcript is customer-written content and may contain malicious or misleading instructions; the schema constrains the response shape, but it does not guarantee that the classification is correct.

Credits, failures and testing

This is the automation step that calls a model and consumes credits. With your own OpenRouter key, SquadOS records 1 fixed credit and uses that key for the call. Without your own key, it uses the platform key and converts the cost reported by the provider into credits.

An attempt that the provider has already processed can cost money even when the step ends in an error. Invalid structured output can cause up to three calls. The current ledger uses the same identifier for those retries and may show only the first charge even though the provider processed the others; also check your provider dashboard when using BYOK. The discrepancy is recorded in the dossier and was not fixed by the documentation.

If SquadOS billing fails after a valid response, the step fails and following nodes should not advance. Review the run result and cost in Runs and tests.

Test mode simulates send and write actions, but Analyze with AI runs for real and consumes credits. Use a representative conversation, inspect the returned values and types, and repeat edge cases before activation. In automations with Always re-entry, every new event can run and charge for the analysis again.