🇬🇧 EN

🤖 Agent

The most powerful node in Flusso. The Agent node sends a prompt to a large language model and returns its response. It supports RAG context injection, tool use via MCP, persistent memory, structured JSON output, and schema validation — making it the foundation of almost every AI-powered workflow.

Category: AI & Agents · Type identifier: agent

Overview

At its core, the Agent node takes a prompt, sends it to a configured AI model, and returns the model's response as output you can use in later steps. However, there is much more you can add on top of that basic flow:

RAG context — automatically inject relevant document excerpts from a Knowledge Base so the model can answer questions about your private data.
Memory — maintain a conversation history across multiple workflow runs, letting the agent remember what was said in previous sessions.
Tools (MCP) — in graph mode, connect MCP Tool nodes so the agent can call external services, APIs, and scripts as part of its reasoning loop.
JSON Mode + Schema — force the model to output structured JSON and validate it against a schema you define, so downstream steps always receive reliably shaped data.

The Agent node operates in two modes. In linear mode, you configure the provider, model, memory, and tools directly in the node's settings panel. In graph mode, you connect separate Model Config, Memory, and MCP Tool nodes to the agent's typed input ports, giving you a clear visual picture of how the agent is assembled.

Configuration

Field	Status	Description
Provider	Required (linear)	The AI Provider to use. In graph mode, connect a Model Config node to the `model_in` port instead.
Model	Required	The model identifier, for example `gpt-4o`, `claude-sonnet-4-6`, or `llama3.2`. Must be a model available through your selected provider.
System Prompt	Optional	Instructions that define the agent's behaviour, persona, constraints, or output format. This text is sent as the system role before the user message. Supports `{{ variable }}` references.
User Prompt	Required	The input message for the agent to act on. This is the main text the model sees and responds to. Supports `{{ variable }}` references — typically populated with data from an earlier step or the trigger payload.
Temperature	Optional	Controls how random or creative the model's responses are. Range is 0–2. A value of `0` produces highly deterministic, consistent output. A value of `0.7` (the default) gives a balanced mix. Values above `1.0` produce more varied, creative responses.
Max Tokens	Optional	The maximum length of the model's response, measured in tokens (roughly ¾ of a word each). Leave blank to use the model's default. Set a limit if you need short, concise responses or are managing API costs.
JSON Mode	Optional	When enabled, instructs the model to output valid JSON only. The response is automatically parsed and made available as `output.json`. Use this together with the Output Schema field to enforce a specific structure.
Output Schema	Optional	A JSON Schema object defining the expected structure of the model's JSON output. Flusso validates the response against this schema after receiving it. If validation fails, the step is marked as failed.
Context Sources	Optional	Select one or more RAG steps earlier in the workflow. Flusso automatically prepends the retrieved document excerpts from those steps to the agent's context before sending the prompt. The most direct way to give the agent access to your knowledge base.
History Source	Optional	Select a previous step whose output contains conversation history to inject into this agent's context. Useful when passing history between steps manually.
Max History Turns	Optional	The number of past conversation turns to read from the connected Memory Provider and inject into the prompt. Range is 1–50. Default is 10. Older turns beyond this limit are dropped.
Memory Provider	Optional (linear)	Select a Memory Provider configured in Settings to enable persistent memory across runs. In graph mode, connect a Memory node to the `memory_in` port instead.
Tools	Optional (linear)	In linear mode, select MCP Tool definitions to make available to this agent. In graph mode, connect MCP Tool nodes to the `tool_in` port instead.
Mode	Optional	`single` — the model produces one response and the step completes. `graph` — the agent enters a tool-calling loop, calling tools as needed until it produces a final answer.

Output Data

The Agent node produces the following output fields, accessible in any later step using variable references:

Field	Type	Description
`text`	string	The raw text response from the model. Always present.
`json`	object	The parsed JSON object. Only present when JSON Mode is enabled and the model returns valid JSON.
`usage.input_tokens`	number	Number of tokens consumed by the prompt (including system prompt and context).
`usage.output_tokens`	number	Number of tokens in the model's response.
`tool_calls`	array	Details of any tool calls the agent made. Only present when tools are connected and the agent used them.

// Reference the agent's plain text response {{ my_agent.output.text }} // Reference a field from a JSON Mode response {{ my_agent.output.json.customer_name }} {{ my_agent.output.json.total_amount }} // Check token usage {{ my_agent.output.usage.input_tokens }} {{ my_agent.output.usage.output_tokens }}

Example Usage

Basic question-answering agent with RAG

This example builds a customer support agent that answers questions about your product using a knowledge base. The user's question arrives via a webhook trigger.

Add a RAG node before the Agent. Set its Knowledge Base to your product documentation. Set Query to {{ trigger.output.question }}. Set Limit to 5 and leave Threshold at the default 0.7.
Add an Agent node. Set Provider and Model. In the System Prompt, define the persona:
You are a helpful customer support agent for Acme Corp. Answer the user's question clearly and concisely. Use only the provided context. If the answer is not in the context, say so.
Set the User Prompt.
{{ trigger.output.question }}
Add the RAG step to Context Sources. Select the RAG step from the Context Sources dropdown. Flusso will automatically inject the retrieved excerpts into the agent's context.
Use the response in a later step. Reference {{ my_agent.output.text }} in a Webhook Response node to send the answer back to the caller.

Structured data extraction with JSON Mode

This example extracts a structured summary from a long article. The agent is forced to return JSON matching a defined schema.

// System Prompt Extract a structured summary from the provided article. Return only valid JSON matching the schema exactly. // User Prompt Article: {{ fetch_article.output.body }} // Output Schema (paste into the Output Schema field as JSON) { "type": "object", "properties": { "title": { "type": "string" }, "summary": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative"] } }, "required": ["title", "summary", "topics", "sentiment"] } // Accessing the result in a later step {{ summarise.output.json.title }} {{ summarise.output.json.topics }}

Tips & Notes

Temperature guidance. Use 0.0–0.3 for tasks requiring consistent, factual output (data extraction, classification, summarisation). Use 0.7 for general-purpose assistants. Use 1.0+ only for creative writing or brainstorming where variety is desirable.
Always use JSON Mode with an Output Schema. JSON Mode alone tells the model to produce JSON, but does not guarantee the keys or structure you need. Adding a schema catches malformed responses before they cause failures in downstream steps.
Context Sources vs. manual injection. Using Context Sources is the recommended approach for RAG because Flusso handles formatting and token budgeting automatically. Only manually inject context via the User Prompt if you need precise control over how the context is presented.
Memory in linear mode. When using a Memory Provider in linear mode, each run reads prior turns and writes the new turn automatically. Set Max History Turns carefully — injecting too many turns increases prompt length and API costs.
Graph mode requires a Model Config node. In graph mode, every Agent node must have exactly one Model Config node connected to its model_in port. The workflow will fail pre-run validation if this connection is missing.

Related Nodes

Model Config — specifies the AI model for an Agent node in graph mode.
Memory — connects a memory backend to an Agent node in graph mode.
MCP Tool — defines an external tool the agent can call in graph mode.
RAG — semantic search node whose results can be injected as agent context.
Schema Extractor — a specialised alternative for structured data extraction from text.