AI Agent Node - LLM Integration and Tool Calling in ConvyAI Agentic Flow
Overview
The AI Agent node is the primary integration point with Large Language Models (LLMs) within an Agentic Flow. When the flow reaches this node, a call is composed and sent to the configured LLM provider using a System Prompt and a User Message that can contain dynamic variable references. The model's response is made available as output to downstream nodes.
The node extends LLM capabilities with tools: external MCP Servers, JavaScript functions defined inline, and image analysis via the Visioning Tool. The agent operates in a reasoning loop - it can invoke multiple tools in sequence before producing the final response. Multiple AI Agent nodes can also be chained, each building on the output of the previous one.
The sequence below shows the reasoning loop when tools are configured:
Positioning
The AI Agent node has one input and one output. It can be placed anywhere in the flow after a trigger node.
Configuration
| Field | Description |
|---|---|
| Provider / Model | The LLM provider and model to use (e.g., OpenAI, Anthropic). Must be configured in the AI Models section of the tenant. |
| System Prompt | Instructions that define the agent's behavior. Supports $ variable references. |
| User Message | The input sent to the model. Supports $ variable references to upstream node outputs and flow context variables. |
If a referenced variable does not exist at execution time, its value is substituted with null.
Output
| Field | Type | Description |
|---|---|---|
response | string | Text generated by the LLM. |
usage.input_token | number | Tokens consumed in input. |
usage.output_token | number | Tokens generated in output. |
usage.thinking_token | number | Reasoning tokens (availability depends on the selected model). |
Tool: MCP Server
Connect one or more external MCP Servers to extend the agent with external capabilities:
- Specify the server URL and authentication method (none, Bearer token, custom header).
- After connecting, select which methods exposed by the server should be available to the agent. If no methods are selected, all methods are available.
- Each method displays its signature: name, description, input parameters with types.
The agent can only invoke methods included in the configured selection (whitelist). If a connection error occurs, the node configuration can still be saved.
Tool: JavaScript Functions
Define one or more JavaScript functions inline in the node:
| Field | Description |
|---|---|
| Description | Plain-text description used by the LLM to decide when to invoke the function. |
| Code | JavaScript body of the function. The editor supports syntax highlighting. |
| Input parameters | Parameters in JSON Schema format that the LLM must provide when calling the function. |
Access the function's input parameters inside the code via the $args object.
Functions run in an isolated sandbox with the same constraints as the Code node: 10-second timeout, 8 MB memory limit. A JavaScript function error does not stop the flow - the error is communicated to the agent, which continues reasoning.
Tool: Visioning (image analysis)
The Visioning Tool is not a standalone node - it is configured exclusively as a tool attached to an AI Agent node. It enables the agent to analyze images using a multimodal LLM.
Configuration:
Register one or more images to pass to the agent, specifying for each:
- Image URL (static URL or
$variable reference) - Processing quality level
Images registered in the Visioning Tool are visible on the node body in the canvas and can be edited or removed.
URL validation rules:
| Scenario | Behavior |
|---|---|
| Syntactically invalid URL | Save is blocked. |
URL contains a variable reference (e.g., $('MyNode').output.imageUrl) | Formal validation is skipped; save is always allowed. |
| Valid URL but unreachable at save time | Save is allowed; a warning is shown. |
| Unsupported image extension for the selected model | Error is shown. |
Runtime behavior:
- Images are downloaded by the backend before invoking the LLM - the provider does not fetch the URL directly.
- Images are sent as binary content (not as URLs), enabling visioning even in environments without direct access to the image sources.
- Images are not persisted - they are used only for the single invocation and then discarded.
- If one or more images fail to download (URL unreachable, timeout, unsupported format, excessive size), the node automatically falls back to text-only mode without interrupting the flow.
Visioning requires a multimodal LLM.
Key concepts
| Term | Definition |
|---|---|
| System Prompt | System instruction provided to the LLM that defines the agent's behavior. |
| User Message | User-level message sent to the LLM; supports dynamic variable references. |
| MCP Server | External server compatible with the MCP protocol, connectable to the AI Agent node as a tool. |
| Method whitelist | Set of MCP methods selected and authorized for a node; the agent cannot invoke methods outside this list. |
| Visioning | The AI Agent node's ability to analyze images using multimodal LLM models. |
| Reasoning loop | The agent's reasoning cycle, which may include multiple tool invocations before producing the final response. |