How to Choose Between Agent Mode and Direct Mode

Understand when to use AI Agent Mode versus Direct Mode for optimal cost and reliability.

What This Integration Does

Spojit lets you call MCP connectors in two very different ways. In Direct Mode, a Connector node calls one specific tool (for example shopify / list-orders) with arguments you supply. In Agent Mode, a Connector node hands a prompt and a filtered set of tools to a ReAct-style AI Agent, which decides which tools to call and in what order. Picking the right mode for each step controls both your spend (Agent Mode burns LLM tokens, Direct Mode does not) and your reliability (Direct Mode is deterministic, Agent Mode can vary run to run).

This article is a decision guide rather than a single workflow. The pattern most teams land on is a hybrid: Direct Mode plus Transform and Condition nodes for everything mechanical, with a small number of Agent Mode steps reserved for places where reasoning over fuzzy input is genuinely worth it.

Prerequisites

• At least one MCP connection configured (e.g. shopify, mongodb, netsuite) so you can compare the two modes side by side.
• A workspace LLM provider configured (Vertex AI, OpenAI, or Anthropic) for Agent Mode steps.
• Familiarity with the basic Spojit canvas: Trigger, Connector, Condition, Loop, Transform.

Step 1: Identify the Decision Points in Your Workflow

Sketch the workflow on paper or the canvas first. For every step, ask: "given the input, is there exactly one correct action?" If yes, that step belongs in Direct Mode. If the right tool call depends on interpreting natural language, classifying unstructured content, or chaining a variable number of actions, that step is a candidate for Agent Mode.

Step 2: Use Direct Mode for Known Tool Calls

For deterministic operations, drop a Connector node onto the canvas, pick the connector, and pick the exact tool. Examples:

• shopify / list-orders with a date range.
• mongodb / update-documents to upsert a record.
• stripe / create-customer with fields straight from the input.
• slack / send-message for a notification with a templated body.

Direct Mode runs are cheap (no tokens), fast (no model latency), and produce the same result every time for the same input.

Step 3: Use Agent Mode for Reasoning Tasks

Configure the Connector node in Agent Mode when the workflow needs to decide what to do. Provide a prompt, a model, and an allowedTools list scoped to just the tools the agent actually needs (Spojit's tool filter passes only those tool definitions to the model, cutting input tokens significantly). Good fits:

• Classifying a free-text support email and then calling monday / create-item on the right board.
• Reading a PDF invoice (via pdf / extract-text) and deciding which fields to write to netsuite / upsert-record.
• Comparing two customer records and deciding whether they're the same person.

Step 4: Use Structured Output to Tame Agent Mode

Most production Agent Mode steps should return JSON, not prose. Define a JSON schema for the output so downstream Transform, Condition, and Connector nodes can read fields like {{ aiResult.category }} reliably. Example schema for a classification step:

{
  "type": "object",
  "properties": {
    "category": { "type": "string", "enum": ["billing", "technical", "feature"] },
    "priority": { "type": "string", "enum": ["low", "medium", "high"] },
    "summary":  { "type": "string" }
  },
  "required": ["category", "priority", "summary"]
}

Step 5: Hybrid Pattern - Agent Decides, Direct Acts

The cheapest reliable pattern is: one short Agent Mode step at the top of the workflow returns a structured decision, then a Condition node routes to a series of Connector nodes in Direct Mode. For example, a ticket-routing flow might use an Agent step to produce { category, priority } from the message body, then Direct Mode slack / send-message calls per branch. The agent never touches the side-effecting tools directly.

Step 6: Decision Reference Table

Use this table when you're unsure which mode to pick:

Tips

• Filter tools aggressively. An Agent Mode step with 80 tools in scope wastes input tokens. Use allowedTools to expose just the 3-5 tools the agent might need.
• Pin a smaller model for narrow tasks. Classification and field extraction usually don't need your top-tier model; switch to a faster model on those nodes.
• Always log the agent's tool calls. Spojit captures intermediate tool calls in the execution log so you can review what the agent actually did.

Common Pitfalls

• Agent Mode for everything. The biggest cost surprise is leaving every step in Agent Mode. Reserve it for the steps that genuinely need reasoning.
• Free-form output downstream. If you don't enforce Structured Output, downstream nodes will sometimes fail because the model returned prose instead of JSON.
• Hidden side effects. Don't put delete or payment tools in allowedTools unless you're sure. Prefer routing destructive actions through Direct Mode after the agent returns its decision.
• Prompt drift. When you broaden a prompt to handle a new edge case, retest the old ones - small wording changes can flip the agent's tool choice.

Testing

Build two versions of the same step - one Direct, one Agent - and run both against the same 5-10 sample inputs. Compare results, token usage, and latency. Keep whichever passes correctness checks with the lower cost. For Agent Mode steps, expand the test set to include the awkward edge cases (empty fields, multi-language input, ambiguous wording) before turning the trigger on.

Learn More

• Connector node documentation
• Transform node documentation