Skip to main content

Decision guides

Quick guides for choosing between the most common pairs of SimplAI primitives.

Agent vs. Tool​

Use an Agent when:

  • The behaviour is goal-driven — the agent decides what to do next based on user input and intermediate results.
  • You want autonomous tool selection — the agent picks which tools to call from a configured set.
  • You need built-in capabilities like memory, reflection, citations, planning, sub-agents.
  • You want a polished conversational surface out of the box.

Use a Tool when:

  • The behaviour is deterministic — you know the exact step sequence.
  • You want explicit control over inputs and outputs.
  • You're building a callable function that another agent or system invokes.
  • You need to chain it inside another Tool or Agent.

A common pattern: build deterministic capabilities as Tools, then let an Agent orchestrate them based on user intent.

Tool vs. Tool in Conversation mode​

Use a default Tool (Conversation mode OFF) when:

  • The Tool is called programmatically — by an API, another Agent, or a workflow.
  • The caller expects a structured JSON response with multiple fields.
  • The input is typed: text, number, file URL, JSON, options.

Use Conversation mode ON when:

  • You're building a copilot / chat assistant / in-product helper.
  • The input is a stream of user messages (Chat History).
  • The output is one assistant reply per turn.
  • You'd previously have built a separate AI Chain primitive (now unified into this mode).

Both modes share every intermediate node, branching, guardrail, versioning, and credits behaviour — only the Start Point and Final node differ.

Voice Agent vs. text Agent​

Use a Voice Agent when:

  • The end user speaks and listens (phone, mobile mic, web voice widget).
  • You need interruption / barge-in handling.
  • Time-to-first-speech matters more than richness of output.
  • You want telephony (inbound or outbound calling).

Use a text Agent when:

  • The surface is chat / email / SMS / any text-based UI.
  • You need features that don't translate to voice: Browser Use, Artifacts, Reflection, Follow-up Messages.

Voice Agents are a separate resource from text Agents. A voice agent never appears in the Agents list.

Sync vs. Async vs. Realtime API (Voice Agents)​

Sync — best for: low-latency interactions, conversational tools. Pipeline: STT → LLM → TTS, no queue. Tools must be in Sync mode.

Async — best for: tool-heavy or slower workflows, where waiting a beat is acceptable. Pipeline: STT → LLM → TTS routed through the dedicated voice priority queue.

Realtime API — best for: very low-latency, tool-light agents. Uses the OpenAI Realtime API instead of the STT → LLM → TTS pipeline. Constrains LLM / STT / TTS provider choice to OpenAI.

If you need the fastest possible TTFS with simple agents → Realtime API. If you need full control over providers / voices with low latency → Sync. If you have heavy orchestration that benefits from queueing → Async.

SDK vs. REST API​

Use the SDK when:

  • Your application is in Python.
  • You need built-in handling of streaming, polling, retries, backoff, scheduling, bulk runs.
  • You want typed exceptions and idiomatic interfaces.

Use the REST API when:

  • You're integrating from a non-Python language without an SDK.
  • You're doing a one-off integration or curl test.
  • You're working from a low-code platform.

Sharing options for an agent​

The three aren't exclusive — most production agents use Deployment surfaces + Export/Import for environment promotion + Marketplace for internal reuse.