AI reasoning

An AI reasoning step sends a prompt to an LLM with access to your store data. It can read orders, customers, products, and analytics, and — when you opt in — write back through the same tools. Each write tool is gated by an approval policy you set on the step. Use AI reasoning when simple conditions aren’t enough: deciding if a customer is a VIP, screening an order for fraud, or letting the agent pick which Notion page to update based on what it finds.

Configuration

Field	Type	Default	Description
`prompt`	`string`	required	Instructions for the AI (10-4000 characters). Supports data access variables.
`output_schema`	`object`	required	JSON Schema defining the expected output. Must include `type` or `properties`.
`enabled_tools`	`string[]`	`[]`	Allowlist of tools the agent can call. Empty means reasoning only.
`tool_safety`	`object`	`{}`	Per-app write-action approval policy. See Tool approval below.
`max_iterations`	`integer`	`10`	Maximum tool call rounds (1-25)
`timeout_minutes`	`integer`	`5`	Maximum execution time (1-15 minutes)

Tools

Tools come in two kinds: read (fetch data) and write (modify data). Both kinds are listed in the same catalog and selected the same way through enabled_tools. Write tools are off by default — you opt them in per step. Selectors you can put in enabled_tools:

A bare name picks one built-in tool (e.g. "get_order_details")
"colossal__{service}__*" picks every built-in in that service group (e.g. "colossal__orders__*")
"app__{integration}__*" picks every tool from a connected integration
"app__{integration}__{action}" picks one tool from that integration

Built-in tools

See the tools catalog for the full input and output schema of each. Read tools (always safe to enable):

Tool	Description
`get_order_details`	Fetch an order by UID with line items and customer info
`get_order_history`	Fetch a customer’s recent orders
`get_customer_details`	Fetch a customer by UID or email
`get_product_details`	Fetch a product by UID
`get_invoice_details`	Fetch an invoice by UID
`get_payment_details`	Fetch a payment by UID
`get_workspace_products`	Search products in the project
`query_insights`	Run analytics queries against store data
`web_search`	Search the web
`fetch_page`	Fetch and read a web page

Write tools (off by default; gated by tool_safety):

Tool	Description
`update_order_status`	Update an order’s status
`update_order`	Update whitelisted fields on an order
`update_order_metadata`	Set integration metadata on an order
`update_billing_address`	Update an order’s billing address
`update_shipping_address`	Update an order’s shipping address
`publish_product` / `archive_product` / `unarchive_product`	Toggle a product’s storefront visibility
`create_price` / `set_default_price`	Manage product pricing
`create_customer` / `update_customer`	Manage customer records
`create_invoice` / `create_invoice_line_item`	Compose invoices
`create_deliverable` / `update_deliverable` / `archive_deliverable`	Manage product deliverables

Integration tools

Every action from a connected integration shows up in the catalog under app__{integration}__{action}. Read actions (HTTP GET) are tagged read; everything else is tagged write. Notion, Slack, Zendesk, Supabase, and any other installed integration contribute their full action list.

Tool approval

tool_safety sets the approval policy for each app’s write tools. Read tools never consult this field.

{
  "tool_safety": {
    "app__notion": { "default": "always_ask", "overrides": {} },
    "colossal__orders": { "default": "never_ask", "overrides": {} }
  }
}

Each entry has:

Field	Type	Description
`default`	`"always_ask"` \| `"never_ask"` \| `"custom"`	App-wide default for write calls
`overrides`	`object`	Per-tool overrides. Only consulted when `default` is `"custom"`. Each value is `"ask"` or `"auto"`.

always_ask is the safe default. Leaving tool_safety empty ({}) means every app falls back to always_ask — every write call pauses for human review.

What happens at runtime

When the agent calls a write tool that resolves to ask:

Run pauses

The run status flips to Paused.

Approval requested

The step appears in the activity log with status Awaiting approval, showing the tool name, arguments, and the agent’s reasoning excerpt.

Approve or deny

Approve runs the tool with the agent’s chosen arguments and the run resumes. Deny sends a denial message back to the agent (which keeps reasoning) — the run does not cancel.

When the call resolves to auto, the tool runs inline with no pause. Multiple write tool calls in a single agent turn each get their own approval row. The run resumes once every decision is in.

This is different from the approval step. Approval steps pause at a fixed point in the graph — useful when the workflow has already computed the action. Per-tool approval pauses inside the AI reasoning step — useful when the agent picks the action at runtime.

Output schema

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

{
  "type": "object",
  "properties": {
    "is_vip": { "type": "boolean" },
    "reason": { "type": "string" }
  }
}

The output is validated. If validation fails, the AI retries with feedback. Subsequent steps reference output as {{steps.<step_id>.output.<field>}}.

Examples

Reasoning only
Read-only investigation
Write tool with approval

No tool calls — pure prompt-and-output.

{
  "id": "summarize_order",
  "type": "ai_reasoning",
  "prompt": "Write a one-line summary of this order for the activity log.",
  "output_schema": {
    "type": "object",
    "properties": { "summary": { "type": "string" } }
  },
  "enabled_tools": []
}

Reads available; no writes.

{
  "id": "vip_check",
  "type": "ai_reasoning",
  "prompt": "Decide if this customer is a VIP based on order history.",
  "output_schema": {
    "type": "object",
    "properties": { "is_vip": { "type": "boolean" }, "reason": { "type": "string" } }
  },
  "enabled_tools": ["colossal__orders__*", "colossal__customers__*"]
}

Default approval policy is always_ask. Each write call pauses the run for human approval.

{
  "id": "tag_priority",
  "type": "ai_reasoning",
  "prompt": "Look at the customer's history and tag this order with a fulfillment priority by calling update_order_metadata.",
  "output_schema": {
    "type": "object",
    "properties": {
      "fulfillment_priority": { "type": "string", "enum": ["high", "normal"] },
      "reason": { "type": "string" }
    }
  },
  "enabled_tools": [
    "colossal__orders__*",
    "colossal__customers__*",
    "update_order_metadata"
  ],
  "tool_safety": {}
}

Result

Each AI reasoning step produces:

Field	Type	Description
`success`	`boolean`	Whether the step completed successfully
`output`	`object`	The structured output matching your schema
`error`	`string`	Error message if the step failed
`iterations_used`	`integer`	Number of tool call rounds used
`execution_time_ms`	`integer`	Total execution time in milliseconds
`tool_calls`	`array`	List of tools invoked with their arguments
`model`	`string`	The model that was used

Use cases

VIP detection: ai_reasoning outputs a structured {is_vip, reason}, a downstream action step writes the order metadata.
Fraud screening: ai_reasoning decides whether the order is suspicious, an approval step gates the action that creates the Zendesk ticket.
Smart routing: ai_reasoning categorises the request, a choice step branches.
Inventory cleanup: ai_reasoning step calls archive_product directly per matching variant — the agent picks which products to act on at runtime.

The first three use ai_reasoning to produce a structured decision; downstream action/choice steps execute on it. Use that shape when the write target is fixed by the trigger and the decision should be observable in steps.<id>.output. Use the inline write-tool shape (the inventory cleanup case) when the agent must search for the target or make a variable number of writes per run.

Next steps

Approval step. Pause at a fixed point for a human-confirmed deterministic action
App action. Run a deterministic write with known inputs
Data access. Reference trigger and step data in prompts and output schemas

Get started

Platform

Agents

AI Commerce Builder

React SDK

Configuration

Tools

Built-in tools

Integration tools

Tool approval

What happens at runtime

Output schema

Examples

Result

Use cases

Next steps

Get started

Platform

Agents

AI Commerce Builder

React SDK

Documentation Index

​Configuration

​Tools

​Built-in tools

​Integration tools

​Tool approval

​What happens at runtime

​Output schema

​Examples

​Result

​Use cases

​Next steps

Configuration

Tools

Built-in tools

Integration tools

Tool approval

What happens at runtime

Output schema

Examples

Result

Use cases

Next steps