Agent Nodes

Agent nodes are the AI-powered building blocks of FlowTrux workflows. They send prompts to an LLM, can call MCP tools iteratively, and return structured output for downstream nodes.

Adding an Agent Node

1. Open a workflow in the editor.
2. Drag an Agent node from the node palette onto the canvas (purple icon).
3. Click the node to open the Inspector panel on the right.

Configuration Fields

AI Model

Select the model from the dropdown. Only models from providers assigned to your current workspace are shown. If the dropdown is empty, ask your organization admin to configure AI providers in Settings.

System Prompt

The system prompt defines the agent's role and behavior. This is sent as the system message to the LLM.

You are a data analyst. Analyze the provided data and return insights as structured JSON with keys: summary, trends, and recommendations.

User Prompt

The user prompt is the actual task or question sent to the agent. Template variables are supported:

Analyze this data: {{steps.action-1.output.data}}

Focus on: {{trigger.data.focus_area}}

Supported template variables:

Temperature

Controls randomness in the model's output. Range: 0.0 to 1.0.

• 0.0 -- Deterministic, consistent outputs. Best for data extraction, classification.
• 0.5 -- Balanced. Good default for most tasks.
• 1.0 -- Creative, varied outputs. Best for brainstorming, content generation.

Max Tokens

Maximum number of tokens in the model's response. Leave empty to use the model's default. Set a limit when you want to control response length or cost.

Adding MCP Tools

Agent nodes can call external tools via MCP (Model Context Protocol). Tools give the agent the ability to search databases, send messages, query APIs, and more.

1. In the Inspector, scroll to the Tools section.
2. Click Add Tool.
3. Select a tool from the dropdown. Tools are grouped by MCP server (e.g., slack:send_message, stocks:get_stock_quotes).
4. The agent will see the tool's name, description, and parameter schema during execution.

Only MCP servers assigned to your workspace appear in the tool list.

How Tool Calling Works

During execution, the agent operates in a loop:

1. The LLM receives the system prompt, user prompt, and definitions of all configured tools.
2. The LLM decides whether to call a tool or return a final response.
3. If the LLM calls a tool, FlowTrux executes it and sends the result back to the LLM.
4. Steps 2-3 repeat until the LLM returns a final text response (no more tool calls).

This means an agent can chain multiple tool calls in a single execution -- for example, searching for data, processing it, and then sending a notification.

Agent Output

The agent's final response is available to downstream nodes as:

{{steps.<agentNodeId>.output.response}}

If the response is valid JSON, it is automatically parsed so you can access nested fields:

{{steps.<agentNodeId>.output.response.summary}}

Best Practices

Write specific system prompts

Vague prompts lead to unpredictable outputs. Be explicit about the format, constraints, and role:

You are a JSON-only responder. Never include explanatory text outside the JSON object.
Return: { "sentiment": "positive"|"negative"|"neutral", "confidence": 0.0-1.0, "keywords": [] }

Choose the right model

• Opus -- Complex multi-step reasoning, long documents, nuanced analysis
• Sonnet -- General-purpose tasks, good balance of quality and speed
• Haiku / GPT-5-mini / Gemini Flash -- Simple extraction, classification, formatting, high-volume tasks

Use templates for dynamic data

Instead of hardcoding values, reference previous node outputs:

Summarize these customer reviews: {{steps.fetch-reviews.output.data}}

Limit tool scope

Only add tools the agent actually needs. More tools increase prompt size and can confuse the model about which tool to use.

Handle structured output downstream

When you need the agent to produce structured data, instruct it in the system prompt and use a Transform action node after the agent to validate or reshape the output.