Skip to main content

Conversation mode

By default, a Tool is task-first: you define typed inputs (Text, Number, File URL, Options, JSON, etc.) and return a structured JSON object that other systems, Agents, or APIs can consume.

Turn on Conversation mode to make the same Tool conversation-first: it accepts a running Chat History as its only input and emits a single assistant reply as its output. Everything between the Start Point and the Final node — LLM calls, KB search, API calls, Python, branching, parallelism, guardrails — works exactly the same way.

From the SimplAI team: Conversation mode replaces the standalone AI Chains primitive. Every existing AI Chain has been migrated into a Tool with Conversation mode on; the existing API/SDK/agent bindings continue to work without code changes. See Migration from AI Chains.

What changes when you turn Conversation mode on​

Start Point​

Typed inputs are replaced by a Chat History panel. Each incoming user message is appended to the history automatically. You can also seed system instructions or example turns that are saved with the Tool — see Start Point: Chat History.

The Custom Attributes tab is unchanged — custom attributes (secrets, env values) work identically in both modes.

Final node​

The Outputs node (which returns multiple named keys as JSON) is replaced by a Final Output node with a single Add to conversation template. Whatever this template renders is sent back to the user as one assistant message. Markdown is supported. See Final Output.

Nothing else changes​

Intermediate nodes, branching, parallelism, guardrails, versioning, credits, tracing, audit log, integrations, and the Python/SDK runtime are identical between the two modes.

When to use Conversation mode​

Use Conversation mode when:

  • You're building a copilot, in-product assistant, or chat-style application where the input is a stream of user messages and the output is one reply.
  • You'd previously have built an AI Chain.

Keep Conversation mode off (the default) when:

  • The Tool is called programmatically by another system or Agent.
  • The caller needs a structured JSON response with multiple fields.

Where the toggle lives​

The Conversation mode toggle is at the top of the Start Point side drawer, above the Inputs / Custom Attributes tabs. A small "How does this work?" link next to the toggle opens an in-product explainer with the same content as this page.

The toggle is editable on any Draft version. It is read-only on Published versions — switching modes requires creating a new draft.

Identifying conversation-mode Tools​

In the Tools list, conversation-mode Tools are visually distinguished with a "Conversation" chip/badge. The top-bar resource label inside the builder reads Tool · Conversation mode so it's clear which mode you're in.

Switching modes is destructive​

Switching Conversation mode on or off deletes the current Start Point inputs and the current Final node configuration, because the two modes use incompatible Start and End nodes. All other nodes, wiring, and custom attributes are preserved. See Switching mode for the full warning copy and what's deleted vs. preserved.

Coming from AI Chains?​

If you're a user of the legacy AI Chains primitive — every AI Chain in your workspace has been migrated to a Tool with Conversation mode on, with full ID + API continuity. See Migration from AI Chains for what changed, what's preserved, and what you might (optionally) want to do next.