> For the complete documentation index, see [llms.txt](https://docs.nected.ai/nected-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nected.ai/nected-docs/workflow/add-node/action-nodes/ai-agent-node/custom-ai-agent.md).

# Custom AI Agent

Previously known as: AI Response Node

The **Custom AI Agent** node is Nected's general-purpose AI step: it sends a prompt (built from static text, workflow data, or both) to a connected AI provider and returns text back into your workflow. It's the node you reach for anywhere a workflow needs an LLM to read something and produce language back - a summary, a classification, a recommendation, a drafted reply, an extracted value - without you writing or hosting any model-calling code yourself.

It's one of three AI Agent node types in Nected (the other two are **Text Analysis Agent** and **Document Classifier Agent**, for more specialized text/document tasks). Custom AI Agent is the flexible, general one - you define the task yourself through prompts rather than picking a fixed built-in task. It appears on the workflow canvas labeled **CustomAIAgent**.

### What you can actually build with it

Because the prompt is dynamic and the node can read live workflow data, the same node type covers a wide range of jobs depending only on what you write into the prompt:

* **Summarization** - condense a support ticket, a document, or a batch of records pulled earlier in the workflow into a short summary.
* **Classification / triage** - read incoming data (a ticket, a form submission, an email body) and output a category, priority, or sentiment your workflow then branches on with a Switch node.
* **Drafting** - generate a reply, notification message, or report section using data from earlier nodes, ready to send via an email/Slack step further down the workflow.
* **Extraction** - pull specific fields out of unstructured text (e.g. "extract the order ID and complaint reason from this message") and pass them on as structured output.
* **Decisioning with reasoning** - ask for a recommendation and a short justification, optionally with a confidence score, so downstream logic (or a human review step) can act on it.
* **Tool-using agent tasks** (Claude only) - go beyond "read prompt, return text": let the model call out to Notion, an internal system, or any other connected MCP server, and/or search the live web, mid-response. See Tools & MCP Connectors below - this is what turns the node from a text generator into an agent that can look things up and act.

The common thread: anywhere you'd otherwise write a small custom script to call an LLM API and parse the response, this node does that in a few form fields instead, with the result available as workflow data to any node after it.

### Prerequisites

Before adding a Custom AI Agent node, you need an **AI Provider connector** already set up under **Integrations → AI Providers**. Nected currently supports:

| Provider           | Connector name shown in the dropdown |
| ------------------ | ------------------------------------ |
| OpenAI             | e.g. `openAi`                        |
| Anthropic (Claude) | e.g. `AnthropicAi`                   |
| GoogleAI (Gemini)  | e.g. `googleAi` / `googleAI2`        |
| Vertex AI          | your Vertex connector                |

You can have multiple connectors for the same provider (e.g. two separate Anthropic connectors with different API keys) - the node just asks you to pick one by name.

<a href="/nected-docs/integrations/integrations-libraries/ai-providers.md" class="button primary">Read More: AI Provider Connector</a>

### How to add the node

1. Open a **Workflow** (new or existing) in the Workflow Editor.
2. Click the **+** on the canvas to add a step, and choose **AI Agents**.

   <figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FKRrGZWjleWRf9mjJ1m9f%2Fimage.png?alt=media&amp;token=c06b7400-b12d-486b-912a-34719e44c2ef" alt=""><figcaption></figcaption></figure>
3. Pick **Custom AI Agent** from the three options (Custom AI Agent / Text Analysis Agent / Document Classifier Agent).

   &#x20;

   <figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FjBaqRAkrkZD4HtmWsbH8%2Fimage.png?alt=media&amp;token=fea06f53-d108-4727-826f-654f83c15037" alt=""><figcaption></figcaption></figure>

The node appears on the canvas as **CustomAIAgent**, and its config panel has three tabs: **Input Params**, **Test Results**, and **Settings**.

### **Tabs Overview**

Like all other nodes, our AI Agent node also has these 3 tabs. You can jump on any tab to read in detail about that specific tab:

{% tabs %}
{% tab title="Input Params" %}

#### Model Configuration

* **Connector** - which AI Provider connector to use. Switching this changes what else is available further down the form (see Tools and Advance Settings below - both are connector-specific).<br>

  <figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2Fpsjnheu7wSuHmO1GtZIE%2Fimage.png?alt=media&amp;token=566076ac-8616-442d-b3a4-76f87cd088d1" alt=""><figcaption></figcaption></figure>
* **Model Name** - the exact model identifier to call, e.g. `claude-sonnet-4-5-20250929`, `gpt-4`, `gemini-3.1-pro-preview`. This is a free-text field, not a fixed dropdown, so it accepts any model string your provider account has access to.

  <figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FqEOLhPTwZwTi6z24nTsW%2Fimage.png?alt=media&amp;token=c8d3fe98-afb0-4297-8c65-facb5903c888" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To Change the model name either you can directly change from the [Connector settings](/nected-docs/integrations/integrations-libraries/ai-providers.md). Or can edit the model name here as well.
{% endhint %}

* **Assistant ID** - shown in place of (or alongside) Model Name when the selected connector is configured against an OpenAI **Assistant** (i.e. the connector itself points at a pre-built Assistant rather than a bare model). This is a connector-level configuration choice made when the AI Provider connector was set up, not a per-node toggle.

#### Task Instructions

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FPUAfBhR3qvNvpOZ451yA%2Fimage.png?alt=media&amp;token=2fca3a53-1a43-497f-ad69-7ec750362feb" alt=""><figcaption></figcaption></figure>

* **User Prompt** - the instruction sent to the model. Supports **dynamic tokens** so you can pull in data from earlier in the workflow, e.g. `Summarize this ticket: {{.LoopBlock.output[1].ruleId}}`. See [Use Tokens in the Editor](https://docs.nected.ai/nected-docs/references/pre-configured-tokens/use-tokens-in-the-editor). Clicking into the field opens a token picker (Global Attributes / System Attributes) alongside it for inserting references without typing them by hand.
* **System Prompt** *(optional)* - sets the model's behavior/role for this call, e.g. `You are a helpful AI assistant. Provide accurate, concise, and helpful responses.` (this is also the default value if you leave it untouched).
* **Add Confidence** - when on, the model appends a confidence line to the end of its own response text, e.g. a response ending in `*Confidence: 0.8*`. This is the model self-reporting confidence in Markdown, not a separate structured field in the JSON output - if you need to parse it programmatically downstream, you'll need to extract it from the response string.
* **Format Markdown** - when on, asks the model to format its response as Markdown (headings, bold, lists, etc.) rather than plain text.

#### Tools (Anthropic/Claude connectors only)

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FUdIIMM6yPByWrtVOJLtt%2Fimage.png?alt=media&amp;token=5571ce9b-f253-4429-a68e-edac5286c48e" alt=""><figcaption></figcaption></figure>

When **Connector** is set to an [**Anthropic** connector](/nected-docs/integrations/integrations-libraries/ai-providers.md#anthropic-claude), a **Tools** section appears that isn't available for OpenAI, GoogleAI, or Vertex connectors. This is the capability that turns the node from a closed text-in/text-out block into an agent that can reach outside the conversation:

| Tool               | What it does                                                                                                                                                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **MCP Connectors** | A multi-select dropdown listing every **published** [MCP Server connector](https://docs.nected.ai/nected-docs/integrations/integrations-libraries/mcp-server) in the current environment. Select one or more to let Claude call that server's tools as part of answering the prompt. |
| **Web Search**     | A simple on/off toggle. No connector needed - when on, Claude can search the live web and ground its answer in current results.                                                                                                                                                      |

Read how you can [**setup MCP Server within the AI Node**](#how-to-setup-mcp-server-within-the-ai-node).

See why [**the tools matters**](#why-the-tools-matters-so-much).

#### Advance Settings

An expandable section under Input Params for provider-level generation parameters. **The available fields depend on which connector is selected** - this isn't a fixed list:

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FSgSdWjHkw5mpgSSgoVgO%2Fimage.png?alt=media&amp;token=5b8d24e8-dd80-4d5f-91a0-89656d61ab01" alt=""><figcaption></figcaption></figure>

**Anthropic connectors:**

* *API & Request Settings:* Base URL, Default Headers, Extra Headers, Metadata, Stop Sequence
* *Model Behavior:* Top K, Top P

**OpenAI connectors:**

* *API & Request Settings:* Stop Sequence
* *Model Behavior:* Frequency Penalty, Log Probs (toggle), Presence Penalty, Top P
* *Additional Settings:* Seed, Top Log Probs, User Identifier

**GoogleAI (Gemini) connectors:**

* *API & Request Settings:* Stop Sequence
* *Model Behavior:* Candidate Count, Frequency Penalty, Log Probs (toggle), Presence Penalty, Include log probabilities (toggle), Top K, Top P
* *Response Format:* Response Mime Type, Response Schema (JSON) - lets you ask Gemini to return structured JSON matching a schema you define here.

All of these are optional - leave them blank to use the provider's defaults.
{% endtab %}

{% tab title="Test Result" %}
Click **Test** (bottom of the Input Params panel) to run the node with its current configuration - this makes a real call to the provider (and, if Tools are attached, real tool calls), so treat it like any other live invocation.

The result is shown in three interchangeable views:

* **Raw** - the response as JSON text.
* **Pretty** - a collapsible tree view (`root` → `error`, `executionTime`, `output` → `processing_time`, `ref_id`, `response`).
* **Table** - a navigable breadcrumb table (`Root → output`) with one row per response.

The response shape, confirmed live:

```json
{
  "error": "",
  "executionTime": "1.96s",
  "output": {
    "processing_time": 1.915,
    "ref_id": "a3fb62ec-05d3-4d4b-b6f2-5d2c8fdfc285",
    "response": "The model's actual text response goes here."
  }
}
```

like this:

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FvQV7IItHK9HgxfwsNYjs%2Fimage.png?alt=media&amp;token=e30e5cbb-b245-4bab-817f-36515dc1a9f0" alt=""><figcaption></figcaption></figure>

On failure, `output` is `null` and `error` carries the provider's raw error message (see the model-name and MCP-auth examples above) - useful for debugging since it's the underlying API's own error text, not a generic Nected wrapper message.

A successful **Test** also marks the node as tested for this environment, which matters because Nected requires every node earlier in a path to have been tested at least once before a later node in that path can be tested or the workflow run - if Test tells you a previous node hasn't been tested, that's a workflow-level rule, not specific to this node.
{% endtab %}

{% tab title="Settings" %}
A second tab, separate from Advance Settings, covering execution behavior rather than model generation parameters:

<table data-search="false"><thead><tr><th width="225.609375">Setting</th><th width="125.6953125">Default</th><th>Purpose</th></tr></thead><tbody><tr><td>Timeout for API (s)</td><td>50</td><td>Max time to wait for the provider's API response.</td></tr><tr><td>Timeout for Webhook/Cron (s)</td><td>50</td><td>Time limit specifically for webhook- or cron-triggered runs.</td></tr><tr><td>Continue on error?</td><td>Off</td><td>If on, the workflow continues past this node even if it fails, instead of halting the run.</td></tr><tr><td>Cache</td><td>Off</td><td>Reuse a previously generated result instead of calling the model again for the same input.</td></tr><tr><td>Time to expire</td><td>5 (Minutes)</td><td>How long a cached result stays valid before the node calls the model again.</td></tr><tr><td><strong>AI Settings</strong></td><td></td><td></td></tr><tr><td>Max Tokens</td><td>1000</td><td>Upper bound on response length.</td></tr><tr><td>Temperature</td><td>1</td><td>Randomness - lower is more deterministic/consistent, higher is more varied/creative.</td></tr><tr><td>Max Retries</td><td>0</td><td>Automatic retry attempts if the call fails.</td></tr><tr><td>Metadata Required</td><td>Off</td><td>Include additional response metadata beyond the core <code>response</code> text.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### Why the Tools matters so much?

Without either of these, the model only ever reasons over the prompt text and whatever workflow data you explicitly fed it - it has no way to check current facts or touch another system. With them on, the model decides *at run time*, based on your prompt, whether and what to call - you describe the outcome, not the API calls.

This was tested live end-to-end. With an Anthropic connector, a published Notion MCP connector attached, and the prompt *"Search my Notion workspace for any pages related to 'roadmap' and list their titles"*, the node returned:

```json
{
  "error": "",
  "executionTime": "14.17s",
  "output": {
    "processing_time": 13.263,
    "ref_id": "b1cee439-92e8-4ee7-9379-0b5df9b946c1",
    "response": "...Based on my search of your Notion workspace for pages related to \"roadmap\", I found **1 page**:\n\n**Page Title:** Review research results\n- **URL:** https://app.notion.com/p/...\n- **Location:** Tasks\n- **Highlight:** \"Recommend changes to product **roadmap**\"..."
  }
}
```

Claude called Notion's search tool through the connector, got real results back, and wrote a natural-language answer from them - all inside one node. With **Web Search** on instead, the same pattern applies to open-web facts: a prompt asking for the current stable Node.js version returned a real, current version number pulled from a live search, not from the model's training data.

Realistic use patterns beyond the tested example:

* **Knowledge lookups** across Notion, Confluence, a wiki, or any documentation MCP server, summarized or answered on demand.
* **Ticketing/CRM context** - look up a customer's history or open tickets from a connected system before drafting a response.
* **Cross-system tasks in one node** - e.g. "check if this customer has an open ticket, and if not, summarize their last few orders," reasoning over two systems in a single call instead of a chain of REST nodes and branching logic.
* **Current-events grounding** via Web Search, for anything that needs to be accurate as of *today* rather than the model's training cutoff.

### How to setup MCP Server within the AI Node?

Follow these simple steps to setup your MCP Server within the workflow:

1. Open (or create) a **Workflow**, and add a **CustomAIAgent** node (found under the Control step types).

   <figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FDik6hY64iyhxshWshD12%2FClipboard-20260907-112307-710.gif?alt=media&amp;token=729c773b-f2a2-4479-b5a0-0def2fd5e3dc" alt=""><figcaption></figcaption></figure>
2. Under **Model Configuration**:
   * Set **Connector** to an Anthropic connector (a Claude model connector you've already set up under **Integrations → AI Providers → Anthropic**).
   * Set **Model Name** to the Claude model you want (e.g. `claude-sonnet-4-5-20250929`).
3. Under **Task Instructions**, fill in your **User Prompt** and (optionally) customize the **System Prompt**. Toggle **Add Confidence** / **Format Markdown** as needed.<br>

   <figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FfOHZJvpBTkrw1PdRxxeE%2Fimage.png?alt=media&amp;token=a8892f2f-d0f4-4304-8888-bb7a8df2e773" alt=""><figcaption></figcaption></figure>
4. Under **Tools → MCP Connectors**, click the dropdown - it lists every **published** MCP Server connector in the current environment. Select one or more to attach to this agent.
5. Optionally expand **Advance Settings** for further tuning.
6. Save the node, then use **Test Run** on the workflow to verify the agent can successfully call the MCP server's tools as part of its response.
7. **Publish** the workflow once testing looks good.

{% hint style="warning" %}
**Note:** The **MCP Connectors** field only appears when the node's **Connector** is set to Claude/Anthropic; MCP tool use is currently supported for Claude models only. If you switch the node to a non-Anthropic connector, the MCP Connectors selection has no effect for that run.
{% endhint %}

{% hint style="info" %}
**Tip:** You can attach more than one MCP connector to the same AI Agent node. Claude decides, per turn, which tool(s) from which connector(s) it needs to call based on your prompt - so it's fine to attach every MCP server the agent might plausibly need, rather than building a separate node per server.
{% endhint %}

### Wrap-up

Custom AI Agent is deliberately general: the same node type does summarization, classification, extraction, and drafting purely through what you put in the prompt, using dynamic tokens to weave in live workflow data. What changes its ceiling is the **Connector** you pick - switch to Anthropic and the node gains **Tools** (MCP Connectors and Web Search), which is the difference between a model that only knows what you told it and one that can go look something up or take action in another system before answering. Everything else - Test Results, Settings, Advance Settings - follows the same pattern as the rest of Nected's node library, just adapted per AI provider where the underlying APIs differ.