Insights agent - Colossal

An insights step asks a natural-language question about your store and returns a structured answer that matches a schema you define. Behind it is a dedicated analytics agent that looks up and analyzes your commerce metrics, interprets what it finds, and fills in the output you asked for. On the canvas the step appears as Insights Agent. Use insights when a step needs a computed metric or aggregate to make its decision: this week’s revenue, the top-selling products over a window, or repeat-purchase rate by cohort. The agent does the analysis; the rest of the workflow acts on the answer.

Configuration

configuration

object

Show properties

question

string

required

The analytics question, in plain language (10-4000 characters). Supports data access variables.

output_schema

object

required

JSON Schema defining the structured answer. Must include type or properties.

max_iterations

integer

default:"10"

Maximum analysis rounds (1-25).

timeout_minutes

integer

default:"5"

Maximum execution time (1-15 minutes).

What it can answer

The insights step runs the same analytics agent that powers insights in chat. It answers aggregate questions over your store’s commerce data: totals, trends, top-N rankings, period-over-period comparisons, cohorts, and funnels across orders, revenue, customers, and products. It applies the correct commerce definitions itself, so you ask in plain language instead of spelling out formulas. The step is read-only. It looks up and analyzes metrics and returns figures.

Writing the question

Ask in plain language, the way you would ask an analyst. The agent owns the metric definitions, so you do not need to specify formulas, status breakdowns, or output formatting. Reference trigger and earlier-step data with data access variables, and fold related metrics into a single question rather than splitting them across steps.

Output schema

The output_schema defines the structure the agent must return. It must be a valid JSON Schema with either type or properties at the top level:

{
  "type": "object",
  "properties": {
    "revenue": { "type": "number" },
    "order_count": { "type": "integer" }
  }
}

The output is validated against the schema. Subsequent steps reference its fields directly as {{steps.<step_id>.<field>}}. The agent also produces a one-line summary interpreting the result in prose, shown in the run view.

Examples

Weekly revenue
Templated question

Ask for a metric, get it back structured.

{
  "id": "weekly_revenue",
  "type": "insights",
  "question": "What was total revenue and order count over the last 7 days?",
  "output_schema": {
    "type": "object",
    "properties": {
      "revenue": { "type": "number" },
      "order_count": { "type": "integer" }
    }
  }
}

Reference trigger or earlier-step data in the question.

{
  "id": "customer_ltv",
  "type": "insights",
  "question": "What is the lifetime revenue for customer {{payload.customer_uid}}?",
  "output_schema": {
    "type": "object",
    "properties": {
      "lifetime_revenue": { "type": "number" },
      "first_order_at": { "type": "string" }
    }
  }
}

Result

Each insights step produces:

result

object

Show properties

success

boolean

Whether the step completed successfully

output

object

The structured answer matching your schema

summary

string

One-line prose interpretation of the result

error

string

Error message if the step failed

iterations_used

integer

Number of analysis rounds used

execution_time_ms

integer

Total execution time in milliseconds

model

string

The model that was used

If the workspace has run out of AI credits, the step pauses instead of failing: success is true, output is empty, and paused is set with a pause_reason of insufficient_credits.

Verify entities before acting on them

Insights reads from your store’s event history. History can name products or customers that no longer exist in the catalog. Aggregate figures need no verification. Entity references do. When a downstream step features, messages about, or updates entities the insights step named, give that step the matching read tools and tell it to verify each one. Ask insights for a few extra entities (top 8 for a top 5) so skipped ones leave no gap.

Use cases

Weekly digest: an insights step computes {revenue, order_count, aov}, a downstream action posts it to Slack.
Restock signal: an insights step returns the top-selling products over a window, a map step runs a restock action per item.
Threshold gate: an insights step returns a metric, a choice step branches when it crosses a threshold.
Best-sellers page: insights ranks products, AI reasoning writes the copy, a storefront builder step updates the page.

Next steps

AI reasoning. The general-purpose agent step
Storefront builder. Turn insights output into a storefront page
Data access. Reference trigger and step data in the question and output schema

​Configuration

​What it can answer

​Writing the question

​Output schema

​Examples

​Result

​Verify entities before acting on them

​Use cases

​Next steps

Configuration

What it can answer

Writing the question

Output schema

Examples

Result

Verify entities before acting on them

Use cases

Next steps