AI Agents — How to combine the nodes

This page explains the usage logic: how the pieces connect and what happens in each case. If you’re coming from the overview, here we get into the practical detail.

Two kinds of connection

A modular agent has two classes of connection and it’s key not to confuse them:

1. Data flow — the normal left → right arrows. It’s the path the workflow execution follows. The AI Agent enters through its left port and exits through the right one, like any node.

2. Role connection — from a sub-node’s output (brain/tool/RAG/skill) to one of the agent’s bottom-edge ports. This does not run the sub-node in the flow: it only declares that this piece is part of the agent.

Sub-nodes don't run in the flow

A brain, a tool or a skill connected to a role port does not execute on its own. They are config providers: the orchestrator reads and uses them. That’s why they don’t need (or receive) a nextModule towards the agent.

Build an agent step by step

1. Place the orchestrator in the flow. Drag AI Agent (orchestrator) onto the canvas and connect its left input port to Start (or another node), and its right output to wherever the flow continues.

2. Connect a brain. Drag Agent: Brain (LLM), pick provider + model + credential, and drag a connection from its output to the agent’s brain port (purple). It’s mandatory: without a brain the agent can’t reason.

3. Add tools (optional). For each capability, drag Agent: Tool, fill in tool_name + tool_description + tool_schema, choose what it runs (node / workflow / registered) and connect its output to the tools port (blue). Repeat per tool.

4. Add RAG (optional). Drag Agent: RAG (retrieve), configure namespace + embeddings, and connect its output to the rag port (amber). The agent will query that base before answering.

5. Add skills (optional). Drag Agent: Skill, describe when it applies and which instructions/tools it enables, and connect its output to the skills port (pink).

6. Save. On save, Floogos converts the graph: each role connection becomes attach_to + role inside the sub-node’s config. You can now run it.

What the orchestrator does with each piece

Port	Cardinality	What the agent does
brain	exactly 1	Picks the provider/model and makes the LLM calls.
tools	0..N	Builds the function schema it offers the LLM; runs whichever the LLM requests.
rag	0..N	Before answering, retrieves relevant chunks and injects them as context.
skills	0..N	Evaluates which ones to activate based on the request; injects their prompt and enables their tools.

The execution loop

When the agent runs, it does this:

1. userInput = configured input  or  data from the previous node
2. systemPrompt = system_prompt
   + (if relevant skills)  their prompt_fragment
   + (if RAG)              the top_k retrieved chunks
3. tools = schema of the connected tools (filtered by skill gating)
4. response = LLM(systemPrompt, userInput, tools)
5. while the response requests tools and iteration < max_iterations:
       run each tool  →  return results to the LLM  →  new response
6. return response.content

Input precedence order

The agent takes as input, in this order: the input field (if you filled it in, it accepts templates like {{@PreviousNode.data.message}}); if empty it uses data.input, then data.message, and if none of those exist, the full serialized data.

Rules and best practices

• One brain and only one. The brain port replaces the previous connection if you connect another. This is by design.
• Tool descriptions that make sense. The LLM chooses which tool to use by reading its tool_description. A vague description = a tool that isn’t used (or is used wrong).
• Define the tool_schema for tools with parameters. Without a schema, the LLM doesn’t know which arguments to send.
• RAG: same model and namespace when indexing and retrieving. It’s the most common mistake (see problems).
• Skills to narrow, not for everything. Use them when you have behaviors that only apply to certain requests and you don’t want to inflate the base prompt or expose extra tools.
• max_iterations per complexity. Tasks that chain several tools need more rounds; raise it if the agent “falls short”.

Next step

Put it all together with the examples and recipes.

And if you would rather not start from scratch, use the Agent library: already-connected kits you insert into the canvas.