AI Agent node

The AI Agent node is the intelligence engine of your workflows: it understands a business objective, reasons on the execution context, then acts by mobilizing the right tools at the right time. Without code, it allows going from an "automated" workflow to an "intelligent" workflow: understand a business objective described in natural language, reason on the available context (trigger data, workflow variables), act by calling internal tools (another node of the workflow) or MCP servers, and return an exploitable response for the following nodes, text or structured JSON.

Parameters

Parameter	Type	Required	Default	Description
App	App	❌	—	Application associated with the node.
System message	Text	❌	—	Global framework of the agent: tone, role, decision rules.
User message	Text	❌	—	Business instruction to execute at each run.
Model parameters	Object	✅	—	AI model to use: provider (`Gemini`, `OpenAI`, `Mistral`, `Anthropic`), model name, API key, temperature, token limits.
Custom model URL	String	❌	—	Alternative API endpoint (self-hosted model, proxy or gateway). Leave empty to use the provider's default endpoints.
Tools	List	❌	—	Action capabilities: associates a tool with a workflow node that the agent can call.
MCP servers	List	❌	—	External tools exposed to the agent via an MCP server (HTTP or SSE).
Structured output	JSON string	❌	—	JSON Schema that forces the agent to return a structured and validated response.
Output key	String	❌	`agentOutput`	Location of the response in the context.
Step limit	Number	❌	`25`	Maximum number of tool calls and agent iterations.

System message and User message

The System message sets up the agent's behavior ("You are an assistant who writes incident responses in French, in less than 3 sentences.").
The User message is the execution instruction, with the workflow variables:

Summarize this ticket in 5 points maximum: {{context.ticket}}

Model parameters

The provider must be supported by the platform: Gemini, OpenAI, Mistral and Anthropic (Claude models) are available.

API key: fill it in the model parameters, or leave it empty if an authentication method provides the token.
Temperature: the lower it is, the more deterministic the response (useful for a structured output).

Tools (workflow nodes)

In advanced cases, the real value comes from the Tools: they are what turns the agent into an operational actor (look up a customer, check stock, trigger an action), not just a reader.

A tool connects the agent to an existing workflow node. When the agent decides to act, the workflow executes this node then comes back to the agent with the result.

Tool field	Description
Name	Tool identifier (lowercase, digits and `_` only).
Description	Explains to the agent when and how to use the tool — the quality of this description directly influences the performance.
Input schema	JSON Schema (as a string) describing the parameters expected by the tool.
Target node	Workflow node to execute when the tool is called.

Tool example

A get_customer tool with the description "Retrieves a customer by email" and an input schema {"type":"object","required":["email"],"properties":{"email":{"type":"string"}}}. When the agent needs the customer, it calls the tool, the workflow executes the target node (for example a SQL request), and the agent receives the result.

MCP servers

Connect an MCP server (Model Context Protocol) to expose tools hosted outside the workflow to the agent:

Name: server identifier;
Transport: HTTP or SSE;
URL: MCP server address;
Headers: possible headers (e.g. authentication).

Structured output

Paste a JSON Schema (as a string) to constrain the response: the agent must return an object that respects this schema, otherwise the node fails. It is the reliable way to feed the following nodes with an object with guaranteed keys.

Example — classify a support request:

{"type":"object","required":["category","priority"],"properties":{"category":{"type":"string"},"priority":{"type":"string","enum":["LOW","MEDIUM","HIGH"]}}}

Points of attention

tip

Structured output and Input schema are pasted as valid JSON strings, not as objects.
Without a Structured output, the output is the agent's last message (text) — less reliable to automate a processing.
A Tool whose target node is absent or invalid causes an error at execution.
If the Step limit is reached, the node returns an explicit error: increase the limit if the agent must chain many actions.
Without tools, the agent remains mostly conversational: to make it act, give it well-described tools.

Input

The node receives the execution context (trigger data, workflow variables) as well as the business instruction from the User message, which can use the Handlebars variables of the context:

Summarize this ticket in 5 points maximum: {{context.ticket}}

Output

The agent's response is injected into context.<outputKey> (default: context.agentOutput):

{
  "agentOutput": {
    "answer": "Here is the analysis of the requested text…",
    "model": "gpt-4-turbo",
    "usage": {
      "promptTokens": 150,
      "completionTokens": 300,
      "totalTokens": 450
    },
    "stopReason": "stop"
  }
}

Property	Description
`answer`	Agent's response: text of the last message, or structured object if a Structured output is configured.
`model`	Model used for the generation.
`usage`	Token consumption (`promptTokens`, `completionTokens`, `totalTokens`).
`stopReason`	Generation end reason (`stop`, `length`, `tool_calls`, …).

In the following nodes, access the response via {{agentOutput.answer}} (node fields) or context.agentOutput.answer (Code node). If you customized the Output key, replace agentOutput with your key.

Errors

Invalid tool — a tool whose target node is absent or invalid causes an error at execution.
Step limit reached — the node returns an explicit error; increase the limit if the agent must chain many actions.
Non-compliant output — if a Structured output is configured and the agent's response does not respect the schema, the node fails.

In case of failure, add an On Error node to the workflow to handle the failure cleanly.

Limits

The Step limit (default 25) caps the number of tool calls and agent iterations; once reached, the node returns an explicit error.
The model provider must be supported by the platform (see Model parameters).

Example

Retrieve a customer with the get_customer tool:

In the Tools, add a get_customer tool with the description "Retrieves a customer by email" and the input schema {"type":"object","required":["email"],"properties":{"email":{"type":"string"}}}.
Connect the tool to an existing workflow node (for example a SQL request).
When the agent needs the customer, it calls the tool: the workflow executes the target node then comes back to the agent with the result.
The agent's response is available in context.agentOutput for the following nodes.

Parameters​

System message and User message​

Model parameters​

Tools (workflow nodes)​

MCP servers​

Structured output​

Points of attention​

Input​

Output​

Errors​

Limits​

Example​

See also​