AI Agent Node

Run an AI agent that can reason, use tools, and produce text or structured output.

The AI Agent node sends a prompt to a large language model (LLM) and optionally equips it with tools so it can take actions autonomously. The agent loops — calling tools and reasoning over results — until it has enough information to produce a final answer. This makes it suitable for tasks that require multi-step reasoning, data retrieval, or interaction with external services.

Parameters

Parameter	Type	Required	Default	Description
`prompt`	string	✅		Prompt sent to the AI agent (evaluated as a template)
`model`	string	✅	`gpt-4.1`	LLM model to use
`temperature`	number	✅	`0`	Sampling temperature between 0 and 1
`tools`	array	❌	`[]`	Tools the agent is allowed to use
`outputMode`	string	❌	`text`	Output mode: `text` or `structured`
`structuredOutputSchema`	array	❌	`[]`	Schema definition for structured output
`extractSchemaFromInput`	boolean	❌	`false`	Dynamically extract the output schema from the input data
`runMode`	string	✅	`item`	Run mode: `item` (per array element) or `input` (entire input)
`continueOnError`	boolean	❌		If true, the workflow continues even when this node errors

prompt

Type: string | Required: ✅

The user prompt sent to the AI agent. This parameter is always evaluated in template mode, so it can contain JavaScript template literal placeholders using the ${...} syntax.

Examples:

Static: Summarize the following text in 3 bullet points.
Dynamic (input mode): Classify the following email and suggest labels:\n${input.emailBody}
Dynamic (item mode): Extract the company name from: ${item.text}

Note: When run mode is input, use the input variable inside ${...} placeholders. When run mode is item, use the item variable instead. Workflow variables are also accessible.

model

Type: string | Required: ✅ | Default: gpt-4.1

The LLM model to use for the agent. Supported models:

Provider	Models
Google	`gemini-3-flash-preview`
Anthropic	`claude-sonnet-4-5`, `claude-sonnet-4-6`, `claude-haiku-4-5`
OpenAI	`gpt-5.3`, `gpt-5.2`, `gpt-5.1`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-4o`, `gpt-4o-mini`

Choose based on the complexity and cost requirements of your task. Larger models are more capable but slower and more expensive; smaller models (e.g. gpt-4.1-nano, gpt-5-nano) are fast and cost-effective for simpler tasks.

temperature

Type: number | Required: ✅ | Default: 0

Sampling temperature between 0 and 1.

0 — Deterministic, consistent output. Best for classification, extraction, and structured tasks.
0.5 — Balanced creativity and consistency.
1 — Maximum creativity. Best for brainstorming and content generation.

Note: Temperature is ignored for reasoning models, which manage their own sampling.

tools

Type: array | Required: ❌ | Default: []

The set of tools the agent is allowed to call during execution. The agent can call tools multiple times in a loop (up to 40 steps) to gather information or perform actions before producing its final output.

Tools fall into three categories:

1. Common Tools (always available)

These tools are built in and do not require any connector or collection:

Tool	Description
`needle_get_time_now`	Get the current date and time
`needle_browse_web_page`	Browse and retrieve a web page
`needle_search_internet`	Search the internet
`needle_create_file`	Create a file and get a download URL
`needle_run_code`	Execute JavaScript or Python code

2. Collection Tools (require a collection)

These tools operate on a specific Needle collection. When you add a collection tool, you must also select which collection it targets.

Tool	Description
`needle_search_collection`	Semantic search across collection documents
`needle_list_files`	List files in the collection
`needle_list_file_labels`	List available file labels
`needle_list_file_label_values`	List values for a specific file label
`needle_search_files_by_name`	Search files by name
`needle_search_file_contents`	Search within file contents
`needle_get_file_contents`	Retrieve the full contents of a file
`needle_get_file_view_url`	Get a viewable URL for a file
`needle_add_files_to_collection`	Upload files to the collection
`needle_delete_files_from_collection`	Delete files from the collection
`needle_add_labels_to_file`	Add labels to a file
`needle_remove_labels_from_file`	Remove labels from a file

3. Connector Tools (require a connector)

These tools interact with external services (e.g. Gmail, Slack, Google Sheets, Notion) through connectors attached to your workflow. The available tools depend on which connectors you have configured. When you add a connector tool, you must also select which connector it targets.

Note: You can manage connectors for your workflow in the Connectors page or directly from the node configuration.

outputMode

Type: string | Required: ❌ | Default: text

Controls the format of the agent's output:

text — The agent returns a free-form text response.
structured — The agent returns a JSON object conforming to the schema defined by structuredOutputSchema (or extracted from input if extractSchemaFromInput is enabled).

structuredOutputSchema

Type: array | Required: ❌ | Default: []

Defines the schema for structured output. Only used when outputMode is structured. Each entry in the array describes one property:

Field	Type	Description
`name`	string	Property name
`type`	string	Property type: `string`, `number`, `boolean`, or `array`
`isRequired`	boolean	Whether the property is required in the output

Example schema:

[
  { "name": "summary", "type": "string", "isRequired": true },
  { "name": "sentiment", "type": "string", "isRequired": true },
  { "name": "confidence", "type": "number", "isRequired": true },
  { "name": "keywords", "type": "array", "isRequired": false }
]

extractSchemaFromInput

Type: boolean | Required: ❌ | Default: false

When enabled and outputMode is structured, the output schema is dynamically derived from the shape of the input data instead of using structuredOutputSchema. This is useful when you want the agent to return data in the same shape as the input.

runMode

Type: string | Required: ✅ | Default: item

Controls how the node processes input data:

item — If the input is an array, the node runs once per array element in parallel. Use item inside ${...} placeholders to reference the current element.
input — The node runs once for the entire input. Use input inside ${...} placeholders to reference the full data.

Note: If run mode is item but the input is not an array, the entire input is treated as a single item.

Examples

1. Simple Text Summarization

Summarize a piece of text with no tools.

Parameters:

{
  "runMode": "input",
  "model": "gpt-4.1-mini",
  "temperature": 0,
  "prompt": "Summarize the following text in 3 concise bullet points:\n\n${input.text}",
  "outputMode": "text",
  "tools": []
}

2. Email Classification with Structured Output

Classify incoming emails and return structured labels.

Parameters:

{
  "runMode": "item",
  "model": "gpt-4.1",
  "temperature": 0,
  "prompt": "Classify the following email. Determine the category, urgency, and whether it requires a reply.\n\nSubject: ${item.subject}\nBody: ${item.body}",
  "outputMode": "structured",
  "structuredOutputSchema": [
    { "name": "category", "type": "string", "isRequired": true },
    { "name": "urgency", "type": "string", "isRequired": true },
    { "name": "requiresReply", "type": "boolean", "isRequired": true },
    { "name": "suggestedLabels", "type": "array", "isRequired": false }
  ],
  "tools": []
}

Output (per item):

{
  "category": "support",
  "urgency": "high",
  "requiresReply": true,
  "suggestedLabels": ["bug-report", "urgent"]
}

3. RAG — Answer Questions from a Collection

Use a Needle collection to answer questions grounded in your documents.

Parameters:

{
  "runMode": "input",
  "model": "claude-sonnet-4-6",
  "temperature": 0,
  "prompt": "Answer the following question based on the documents in the collection. Cite your sources.\n\nQuestion: ${input.question}",
  "outputMode": "text",
  "tools": [
    {
      "provider": "needle",
      "toolName": "needle_search_collection",
      "requiresCollection": true,
      "collectionId": "<your-collection-id>"
    },
    {
      "provider": "needle",
      "toolName": "needle_get_file_contents",
      "requiresCollection": true,
      "collectionId": "<your-collection-id>"
    }
  ]
}

The agent will search the collection, retrieve relevant documents, and compose an answer.

4. Web Research Agent

Equip the agent with internet search and web browsing to research a topic.

Parameters:

{
  "runMode": "input",
  "model": "gpt-5",
  "temperature": 0.3,
  "prompt": "Research the topic below and write a comprehensive summary with key findings and sources.\n\nTopic: ${input.topic}",
  "outputMode": "text",
  "tools": [
    { "provider": "needle", "toolName": "needle_search_internet" },
    { "provider": "needle", "toolName": "needle_browse_web_page" }
  ]
}

5. Data Enrichment with Connector Tools

Use a connector tool (e.g. Google Sheets) to enrich leads.

Parameters:

{
  "runMode": "item",
  "model": "gpt-4.1",
  "temperature": 0,
  "prompt": "Look up the company '${item.companyName}' on the internet and fill in the missing fields: website, industry, and employee count.",
  "outputMode": "structured",
  "structuredOutputSchema": [
    { "name": "companyName", "type": "string", "isRequired": true },
    { "name": "website", "type": "string", "isRequired": true },
    { "name": "industry", "type": "string", "isRequired": true },
    { "name": "employeeCount", "type": "number", "isRequired": false }
  ],
  "tools": [
    { "provider": "needle", "toolName": "needle_search_internet" },
    { "provider": "needle", "toolName": "needle_browse_web_page" }
  ]
}

Output Structure

Text Mode

When outputMode is text, the node outputs the agent's response as a plain string.

"The document discusses three main themes: ..."

Structured Mode

When outputMode is structured, the node outputs a JSON object matching the defined schema, with an additional _meta field containing reasoning traces and tool call steps.

{
  "summary": "...",
  "sentiment": "positive",
  "confidence": 0.92,
  "keywords": ["ai", "workflow", "automation"],
  "_meta": {
    "reasoningText": "...",
    "steps": [
      {
        "content": [
          { "type": "text", "text": "Let me search for..." },
          {
            "type": "tool-call",
            "toolName": "needle_search_collection",
            "input": { "query": "..." }
          }
        ],
        "finishReason": "tool-calls"
      }
    ]
  }
}

Important Notes

Tool loop limit: The agent can take up to 40 tool-call steps per run. If the agent exceeds this limit it will stop and return whatever it has so far.
Error handling in tools: Tool call failures inside the AI Agent node do not immediately stop execution. The agent can recover by retrying or choosing a different approach.
Template evaluation: The prompt parameter is always evaluated as a template. Use ${...} syntax to inject dynamic values from the input.
Reasoning models: For reasoning models, the temperature parameter is ignored — the model manages its own sampling strategy.
Run mode: When processing arrays of data (e.g. a list of emails), use item run mode to process each element in parallel. Use input run mode when you need access to the full dataset at once.

Parameters​

prompt​

model​

temperature​

tools​

1. Common Tools (always available)​

2. Collection Tools (require a collection)​

3. Connector Tools (require a connector)​

outputMode​

structuredOutputSchema​

extractSchemaFromInput​

runMode​

Examples​

1. Simple Text Summarization​

2. Email Classification with Structured Output​

3. RAG — Answer Questions from a Collection​

4. Web Research Agent​

5. Data Enrichment with Connector Tools​

Output Structure​

Text Mode​

Structured Mode​

Important Notes​

Parameters

prompt

model

temperature

tools

1. Common Tools (always available)

2. Collection Tools (require a collection)

3. Connector Tools (require a connector)

outputMode

structuredOutputSchema

extractSchemaFromInput

runMode

Examples

1. Simple Text Summarization

2. Email Classification with Structured Output

3. RAG — Answer Questions from a Collection

4. Web Research Agent

5. Data Enrichment with Connector Tools

Output Structure

Text Mode

Structured Mode

Important Notes