Agents and tools

The AI agent — the ai_agent node — is not a “smarter node”. It is a loop: the model receives a message and the list of tools available to it, decides whether to call any of them, gets the call results and goes back to the model — until it replies with text. Each pass through that loop is called a round.

The agent itself works on the free plan with no caveats. The limits apply to individual tools: telegram_tools is only useful on a published Telegram bot, and that is a paid channel; bring-your-own models (BYO) are not allowed on Free; and Free permits three connections to external services. Everything else — search, files, knowledge bases, sub-workflows — is available right away.

Agent versus a single model call

The other way to talk to a model is the llm_response node. It makes exactly one call and returns whatever the model produced. The difference is not about quality — it is about who makes the decisions.

The rule of thumb is simple: if you already know the sequence of steps, build it out of graph nodes and use llm_response. You need an agent where the steps depend on what the model learns along the way: “look it up in the knowledge base, and if you find nothing, search the web, then answer”.

How a tool is attached

A tool is a node with a tool_out (or output) port carrying a link_extension wire. It runs into the agent’s Extensions input. That port accepts any number of edges: five tools means five wires into one port.

Look at the card: it has no execution input. That is not an oversight, it is the whole mechanism. A tool does not sit in the graph’s execution queue and does not run when its turn comes — it is called by the model, from inside a round, as many times as it sees fit and with whatever arguments it invents. The graph scheduler knows nothing about those calls. That is also why a link_extension wire does not affect execution order — more on the Wires page.

What the agent tells the model about each tool is a name, a description and an argument schema. The description comes from the node’s settings and is part of the prompt: the model picks a tool by reading it. A vague “works with files” is the single most common reason an agent never calls the tool you meant.

A tool may have inputs of its own — but configuration inputs, not execution ones: file_tool takes a storage on the file_store port, calendar_tool takes a calendar, email_tool a mail account. That is “which one to use”, not “when to fire”.

What happens inside a round

Each round shows up in the run history as its own row — on the Node Executions (4) tab the agent gets #call_1, #call_2 and so on, with the arguments and the result of every call. That is the first place to look when the agent “answered the wrong thing”: almost always you can see that it called the wrong tool or passed the wrong arguments.

Which tools exist

The Tool badge in the palette sits on eighteen nodes. By purpose they group like this:

Exact port and field lists live in the node reference; details about external services are on the Integrations page.

A node that can be both a step and a tool

Three nodes declare both interfaces at once: image_generate, text_to_speech and openrouter_web_search. The switch in their settings is the “Node mode” field, with two values:

• Executable — an ordinary graph step: it has an execution input and a Success output, and the tool_out port is hidden. You decide when the node fires.
• As Tool — an agent extension: only tool_out remains, while the execution ports and the error-branch toggle disappear. The model decides when it fires.

The ports on the card change the moment you flip the switch, so a wire leading into a port that just vanished becomes a validation error. That is expected: one node cannot be both a step in your scenario and a tool in the model’s hands, otherwise the graph does the work twice.

Toolsets, sub-workflows and sub-agents

Many tools on one port. You can run wires into the Extensions port one by one, but once there are more than five or six the canvas stops being readable. The toolset node collects a set: the tools plug into it, and a single wire goes from it to the agent. Behaviour is unchanged — the model sees the same list.

A slice of the graph as a tool. wf_tool wraps a subgraph: it has a Data output (the start of the chain) and a Result input (the end), and in between you build ordinary nodes. The model calls it by name, the chain runs, and the result comes back into the conversation. This is how reusable operations are built: “create a ticket”, “calculate shipping” — things that must be executed identically rather than paraphrased by the model each time.

An agent inside an agent. Turn on the “Expose as Tool (Subagent)” flag on a second ai_agent — it gains a tool_out port and can be attached to the first one. By default a sub-agent takes its model from the parent (you can switch it to its own LLM port), it requires a tool name, and like every tool it is invoked at the model’s discretion. This makes sense where a subtask has its own tool set and its own system prompt: an “invoicing agent” with its own database access, a “scheduling agent” with its own calendar.

Agent state

Three nodes give the model tools for working with its own state. It lives separately from the conversation history and separately from graph variables:

The difference between conversation memory and agent memory is practical: history is what was said and it grows on its own; agent_memory is what the model decided was worth remembering, and it writes there with an explicit call. If you need the value in the graph (a condition, a filter, a query field), use a variable, not agent memory. All three mechanisms are covered in detail on the Variables and memory page.

agent_skills has a distinct role: each “skill” is a chunk of the system prompt that the model switches on and off itself. That way a whole rule book does not sit in the context on every turn.

The round budget

The “Max Tool Iterations” field in the Advanced section of the agent’s settings is a number of rounds, not a number of calls. The default is 10, the allowed range is 1 to 50. Forty tool calls inside one model reply are still one round.

The work itself is capped by a second field, “Max Tool Calls”: how many calls this agent may make. An empty value means “as many as the overall run budget allows”, and that budget is shared by every agent inside the run.

The key property of both ceilings: running out does not abort the turn. The allowed prefix of the call batch is executed, the rest get back “budget exhausted, this call was not performed”, and the next round is declared final — with an explicit instruction to answer with what is already there. A turn always ends with a model reply, never with silence or a failed run: otherwise the user would pay for ten rounds and get nothing.

When a tool fails

A tool error does not fail the run. It is turned into text and returned to the model as the call result — roughly like this: Error executing tool 'fs_read': File not found. This is deliberate: the model is often able to recover on its own — try another path, another query, another tool — and that recovery is the error handling. The run status stays successful.

The text that goes to the model passes through the same sanitisation as any other error message: internal details, keys and tracebacks never reach it, because the model happily retells a tool result in its answer to the user. The details are on the Errors page.

A failed call is visible in the run history: the broken tool has a row with an error status even when the answer to the user looks fine.

What it costs

Each round is a new model call carrying the whole accumulated history: the system prompt, the conversation, every past tool call and every result. So input tokens grow with each round, and an agent that went to the model five times costs noticeably more than a single llm_response call.

The fixed part of the tariff, however, is charged per node, not per round: five rounds are still one agent that the platform ran. It is the tokens that grow. Paid tools are metered as separate lines: image generation, speech synthesis, paid web search. The full formula is on the Credits and pricing page.

The practical takeaway: the length of the system prompt and the size of what tools return affect the bill more than it seems — because both are re-sent on every round. A tool that hands the model the full text of ten documents gets expensive quadratically.

What next