Tools Agent

An AI agent that can call tools (search, calculate, browse, call APIs) step by step until it can answer.

What it does

Tools Agent sends Prompt to the chat model on Model, together with the tools connected to Tools. The model decides which tool to call and with what; the agent runs it, sends the result back, and repeats until the model gives a final answer or Max iterations is reached.

Some tools only read or compute. Others take real actions on your behalf, and those are gated: the model can call them, but each call pauses for your approval before it runs. You approve or reject each action in the Executions pane. This is automatic and cannot be turned off; see Action Approval. The gated tools are:

• Browser Tool: click, fill, type, select, submit or navigate on the active page.
• HTTP Request Tool: send HTTP requests to APIs.
• MCP Client Tool: call the tools of a remote MCP server.

While it runs:

• Each tool call appears in the run log as it happens (Agent calls tool …, then Tool … finished in 840 ms, or a warning when it failed or timed out).
• Stop interrupts the agent mid-reply: the model call and any running tool are cancelled, and the log says Agent stopped before it finished.
• When the model asks for a tool in a malformed way, the error is sent back to the model so it can correct the call, instead of failing the node.

With a chat memory on Memory, the agent has a conversation: it loads the earlier messages as chat history, saves the prompt as a user message, and saves the reply as an assistant message (a structured reply from an output parser is saved as JSON text). This is how a Chat Trigger gets its replies: connect the same memory to the trigger and to this agent.

When to use it

• A chatbot that can look things up on the web, do maths or query an API before it answers.
• A task in several steps, such as “find the price on this page, convert it to euros, and fill it into the form”.
• An assistant that searches your knowledge base and also uses tools.

For a single prompt with no tools, use Basic LLM Chain. To answer only from your documents, RAG Agent is simpler.

Inputs and settings

Setting	Type	What it does
Prompt REQ(required)	Text
Options	Group	The options for the node.
Options › System message	Long text	The system message to use.
Options › Max iterations	Number	How many times the agent may call tools before it must answer with what it has. Default: 10
Options › Knowledge documents (k)	Number	How many documents to retrieve from the connected knowledge base. Default: 4
Options › Max knowledge context length	Number	Maximum characters of retrieved knowledge to inject into the prompt. Default: 4000
Options › Fail on knowledge error	Toggle	If enabled, the node fails when knowledge retrieval errors instead of answering without context. Default: Off
Options › Knowledge search	Choice	How the agent uses the connected knowledge base. Options: Search before answering, Let the agent search the knowledge base on its own, Both. Default: Search before answering
Options › Search type	Choice	How passages are picked from the connected knowledge base. Options: Most similar, Diverse (MMR). Default: Most similar
Options › Match by	Choice	How a knowledge base is searched with "Most similar". Diverse (MMR) and other vector stores always match by meaning. Options: Keywords and meaning, Meaning only. Default: Keywords and meaning
Options › Minimum relevance	Number	Drop passages less similar to the question than this (0 to 1). 0 keeps every passage. Default: 0
Options › Metadata filter	Key-value pairs	Only search passages whose metadata matches every key = value (e.g. sourceType = web). Keys use letters, numbers and _; numbers and true/false are matched as such.
Options › Device-only knowledge with a cloud model	Choice	A knowledge base marked "Device only" is never sent to a cloud model. Choose what the node does when its model is a cloud model. Options: Stop with an error, Answer without it. Default: Stop with an error

Behind a Chat Trigger, set Prompt to {{ $input.chatInput }}. Use System message to tell the agent its role and when to use which tool.

When the agent reaches Max iterations, it stops calling tools and is asked for a final answer with what it has; the run log says Agent reached its max iterations and answered with what it had.

When a Local Knowledge is connected to Knowledge, Knowledge search decides how the agent uses it:

• Search before answering (default): the knowledge base is searched with the prompt and the passages are given to the agent up front. Best for small and on-device models.
• Let the agent search the knowledge base on its own: the agent gets a knowledge search tool and decides when and what to search, for example several searches with better questions. Best for capable models.
• Both: passages up front, and the tool to search again.

The search tool returns passages numbered [S1], [S2]… (the numbering continues across calls), fenced as reference data. It only reads, so it does not need your approval. Its calls appear in steps like any other tool, and the sources it found are added to sources.

The other knowledge options work as on the RAG Agent: see Knowledge base options. A Device only knowledge base is never sent to a cloud model.

Outputs

• Output

Each output item has these fields:

Field	Type	What it holds
response	Any	The model reply; the parsed result when an output parser is connected
steps	List of entries	The tool calls the agent made, in order
usage	Object	Tokens the model used, as reported by the provider
sources	List of entries	The knowledge base sources used for the answer

Shape of an output item

{
  "response": null,
  "steps": [],
  "usage": {},
  "sources": []
}

• response: the agent’s final answer.
• steps: present when tools are connected. Each entry has name, args, status (ok, error, timeout, aborted or skipped), durationMs, result (shortened) and truncated.
• sources: present when a knowledge base is connected (it may be empty). Each entry has title, url (when there is one), knowledgeId, sourceId and score.
• usage: tokens used over every model call of the run: inputTokens, outputTokens, cachedTokens (served from the provider’s prompt cache) and totalTokens. Present when the provider reports usage.

Dependencies and credentials

Slot	Accepts	Connections
Model REQ(required)	chat model	One node.
Memory	chat memory	One node.
Knowledge	vector store	One node.
Tools	tools	Several nodes can plug in.
Output Parser	output parser	One node.

• Model: a chat model that supports tool calling. Cloud models do, and so do the on-device Transformers Chat and Web LLM models (prompt-based tool calling). The model node holds the API key.
• Tools: any number of tool nodes, such as Calculator, Web Search, Wikipedia Query or Workflow as Tool.
• Memory: a Chat Memory, to remember the conversation. It can keep tool results so later turns can use them.
• Knowledge: a Local Knowledge node.
• Output Parser: shapes the final answer.

Example workflow

1. Chat Trigger opens a chat window.
2. Tools Agent with Prompt {{ $input.chatInput }} and System message You are a research assistant. Search the web for recent facts and use the calculator for any maths.
3. Connect an Chat OpenAI model to Model, Web Search and Calculator to Tools, and one Chat Memory to both Memory and the Chat Trigger.

Ask “What is the population of Lyon divided by 12?” and watch the run log: the agent searches, then calculates, then answers.

Common issues

• “This agent requires that the bind_tools() method be implemented on the input model”. The connected chat model cannot call tools. Use a cloud model, or Transformers Chat or Web LLM on-device, and check that it is connected to Model.
• The run pauses and nothing happens. A gated tool (Browser, HTTP Request, MCP Client) is waiting for your approval. Open the Executions pane and approve or reject the action.
• “Agent reached its max iterations and answered with what it had”. The agent needed more tool calls. Raise Max iterations, or make the prompt and System message more precise so it needs fewer steps.
• The agent never uses a tool. Say in System message when each tool should be used. Small models often skip tools; try a more capable model.
• “Model not found”. The connected model node is not set up: open it and choose a model and its credential.

Related nodes

• Chat Trigger: turn the workflow into a chatbot.
• Workflow as Tool: let the agent run another workflow.
• RAG Agent: answer from your documents, no tools.
• Run agent: run one of your saved agents.