> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spojit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connector (Action)

> Execute tools from your connectors: directly or with an AI agent.

The **Connector** node (also called an Action node) is how your workflow interacts with external services and processes data. It executes tools from your connectors, and you choose *how* it runs: let an AI agent figure things out, or specify the exact tool and parameters yourself.

## Execution modes

Every connector node runs in one of two modes. You select the mode in the properties panel when configuring the node.

### Agent mode

In agent mode, you write a **prompt** describing what you want to accomplish. The AI reads your prompt, reasons about which tools to use, calls them, and returns a result.

You describe *what* you want; the AI figures out *how*.

**Configuration:**

| Field               | Required | Description                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| **Connector**       | Yes      | The service or utility to use                                                                                 |
| **Connection**      | Depends  | For integration connectors, the connection to use                                                             |
| **Prompt**          | Yes      | A natural-language description of what you want the AI to do                                                  |
| **Model**           | No       | Which AI model to use (see [Models](/platform/models) for options; uses default if not set)                   |
| **Allowed Tools**   | No       | Filter which tools the AI can see; uncheck tools that aren't relevant to keep the AI focused                  |
| **Response Schema** | No       | Define a JSON schema to force the AI to return structured data. See [Response Schema](#response-schema) below |

**Best for:**

* Tasks that require reasoning or analysis
* Multi-step operations where the AI chains several tools together
* Flexible logic (for example, "summarise these orders", "find the best match", "clean up this data")
* Situations where you're not sure which exact tool or parameters to use

### Direct mode

In direct mode, you pick the **exact tool** and fill in its **parameters** yourself. No AI is involved; the tool runs immediately with exactly the inputs you provide.

**Configuration:**

| Field          | Description                                                               |
| -------------- | ------------------------------------------------------------------------- |
| **Connector**  | The service or utility to use                                             |
| **Tool**       | The specific operation to perform (e.g., `send-message`, `parse`, `case`) |
| **Connection** | For integration connectors, the connection to use                         |
| **Parameters** | Tool-specific inputs (these change depending on the selected tool)        |

**Best for:**

* Known, repeatable operations (for example, "always send this Slack message", "always convert to uppercase")
* When you need predictable, consistent results every time
* Simple tasks where you already know the tool and parameters
* High-throughput workflows where speed matters

### When to use which

| Scenario                                          | Recommended mode |
| ------------------------------------------------- | ---------------- |
| You know exactly which tool and parameters to use | Direct           |
| You need the AI to decide how to approach a task  | Agent            |
| The task is simple and repeatable                 | Direct           |
| The task requires analysis or judgement           | Agent            |
| You want the fastest possible execution           | Direct           |
| You want to chain multiple tools in a single step | Agent            |

## Tool selection

When a connector node runs in agent mode, the AI has access to the tools provided by the selected connector. If the connector has many tools, you can **filter which tools the AI can see** using the checkbox list in the properties panel.

This keeps the AI focused on the tools that are relevant to the task, which leads to:

* **Faster execution**: the AI spends less time considering irrelevant tools
* **More accurate results**: fewer choices means the AI is more likely to pick the right tool
* **Clearer behaviour**: you know exactly which tools the AI might use

<Tip>
  If your connector has dozens of tools but you only need two or three for a particular step, uncheck the rest. The AI will work better with a focused set of tools.
</Tip>

## Using integration connectors

Integration connectors like Shopify, Slack, and Resend require a **connection** with valid credentials. Select the connection in the node configuration.

<Snippet file="connection-note.mdx" />

## Using utility connectors

Utility connectors (Text, JSON, Math, CSV, etc.) don't require a connection. Select the connector and tool, then fill in the parameters.

## Referencing previous outputs

You can reference the output of any previous node as input to a connector node. Use the variable picker to select outputs from upstream nodes.

## Response Schema

In agent mode, you can define a **response schema** to force the AI to return structured data instead of free-form text. This is useful when downstream nodes (Condition, Transform, Loop) need to work with specific fields.

Click **Response Schema** in the properties panel to expand the schema editor. It has two modes:

* **Visual**: add properties with a name, type, description, and required flag. Supports nested objects and typed arrays.
* **JSON**: paste or edit raw JSON schema directly.

**Example:** Extract order summary as structured data:

```json theme={null}
{
  "type": "object",
  "description": "Order summary",
  "properties": {
    "orderCount": {
      "type": "number",
      "description": "Total number of orders"
    },
    "totalRevenue": {
      "type": "number",
      "description": "Combined revenue across all orders"
    },
    "topProducts": {
      "type": "array",
      "description": "Top selling products",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "quantity": { "type": "number" }
        }
      }
    }
  },
  "required": ["orderCount", "totalRevenue"]
}
```

When a response schema is defined, the AI is forced to return data matching exactly that structure: no extra fields, no missing required fields. The output is a parsed object, not a string.

<Tip>
  Response schema is also available on [Knowledge](/workflow-editor/nodes/knowledge) nodes in query mode.
</Tip>

## Retry

Connector nodes can automatically retry on transient failures (timeouts, server errors, rate limits). Configure in the **Retry** section of the properties panel:

* **Max attempts** (1–5; default 1, no retry). When set above 1, the node retries on transient failures with backoff between attempts.
* **Retry on tool errors** (off by default). Also retries connector errors that aren't clearly transient. **May create duplicate side effects** for write operations, so only enable this on tools you're sure are safe to retry.

Retry scope is per-tool-call in agent mode and per-step in direct mode. See [Retry behaviour](/workflow-editor/retry) for the full classification rules and per-mode semantics.

## Output

The connector node binds the result of the tool execution to its output variable. The shape depends on the runner mode:

* **Direct mode**: `{{ step }}` is the parsed tool payload. The shape is tool-specific; check the connector page for details. For HTTP tools that's typically `{ data, status, headers, statusText }`; address the response body with `{{ step.data }}` and the status code with `{{ step.status }}`.
* **Agent mode without a Response Schema**: `{{ step }}` is the LLM's prose answer (a string).
* **Agent mode with a Response Schema**: `{{ step }}` is the structured schema object; address fields directly: `{{ step.<schemaField> }}`.

See [Passing Data Between Nodes](/workflow-editor/passing-data) for the full template reference.

## Examples

### Agent mode: Analyse Shopify orders

* **Connector**: Shopify
* **Mode**: Agent
* **Prompt**: `Get all orders from the last 7 days and summarise the total revenue by product category`

The AI decides which Shopify tools to call (e.g., listing orders, fetching product details) and assembles the summary for you.

### Direct mode: Send a Slack message

* **Connector**: Slack
* **Mode**: Direct
* **Tool**: `send-message`
* **channel**: `C01234567`
* **text**: `New order received!`

### Direct mode: Convert text to uppercase

* **Connector**: Text Tools
* **Mode**: Direct
* **Tool**: `case`
* **text**: `hello world`
* **to**: `upper`

### Direct mode: Query JSON data

* **Connector**: JSON Tools
* **Mode**: Direct
* **Tool**: `query`
* **data**: (reference previous node output)
* **path**: `$.orders[*].total`