Using Connector Nodes in Agent Mode

Let AI decide which tools to use by running connector nodes in Agent Mode.

Overview

A Connector node calls an external service via one of your Connections. It has two execution modes. In Agent Mode, you give the node a natural-language prompt and an LLM agent decides which tools on the connection to call, in what order, and with what arguments. The agent loops through tool calls until it has accomplished the task, then returns a result.

Agent Mode is the right choice when the task involves judgement, multiple steps against the same service, or input shapes the workflow author cannot pin down at design time ("find any unpaid invoices older than 30 days and chase them"). For deterministic, single-tool calls, use Direct Mode instead - it is faster, cheaper, and easier to reason about.

Before You Start

You need an active connection to the service the agent should use.
An LLM provider must be configured for your workspace.

Configuration

Add a Connector node to the canvas and wire it into the flow.
In the properties panel, set the mode to Agent.
Pick the connection the agent should act on.
Pick the LLM model to power the agent.
Write a prompt describing the task. Use {{ }} templates to inject data from upstream steps.
Optionally restrict the tools available to the agent and configure structured output and retries.

Settings

Connection - Which configured connection the agent calls tools on.
Model - The LLM that drives the agent loop.
Prompt - Natural-language task description. Templates resolve before the prompt is sent.
Tool filtering - When enabled, lets you pick the exact subset of the connection's tools the agent may call. Cuts input tokens and improves accuracy.
Structured output - When enabled, the agent must return JSON matching a schema you provide, so downstream nodes get predictable data.
Max retries - 1 to 5. Number of attempts in the face of transient errors.

Writing Good Prompts

Be specific about inputs, the operation, and the expected output:

Specific: "List all Shopify orders from the last 24 hours with total greater than $100, then update each one's tags to include 'high-value'. Return the count of orders updated."
Vague: "Do something with orders."

Reference upstream data directly: "Send a Slack message to {{ input.channel }} summarising the order {{ getOrder.id }}."

Tool Filtering

By default the agent sees every tool on the selected connection. Each tool description costs input tokens on every step of the agent loop, so an unrestricted connection with dozens of tools is expensive and gives the agent more ways to go wrong. Enable tool filtering and pick only the tools that are actually relevant to the task.

Structured Output

Turn on Structured Output when downstream nodes need a predictable shape. Provide a JSON schema; the agent is constrained to return data that conforms to it. The result is then addressable as {{ thisNode.fieldName }} with no further parsing.

Tips

Start with Direct Mode if you can. Reach for Agent Mode only when the task genuinely needs reasoning.
Filter tools aggressively. The fewer the better, both for cost and accuracy.
Use Structured Output whenever a downstream node needs the result. Free-form text is hard to parse reliably.
Inspect the execution log to see every tool call the agent made. It is the fastest way to understand and improve a prompt.

Common Pitfalls

Underspecified prompts - Vague prompts produce vague results, or the agent loops indefinitely trying to interpret the task.
Too many tools - An agent given fifty tools spends a lot of tokens deciding which to use and is more likely to pick the wrong one.
Expecting determinism - The agent may take different paths on different runs. If you need the same output every time for the same input, Direct Mode is the right choice.
Free-form output downstream - Without Structured Output, downstream nodes have to parse natural language. Brittle and often wrong.

Learn More

Connector node documentation