Skip to content
Agentic Workflowdocs
v0.9.0Install free

nodes / builtin / ai / aiagents

Tools Agent

Generate an action plan and execute it. Can use external tools.

AI ExtensionWeb app

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

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 can ask for your approval before they run. Each tool step has Ask before a call (Every call, Only calls that change things, Skip trusted sites, Ask me anywhere, even when I’m away); calls that delete or send as you always ask. When nobody is there to answer (a scheduled run), the run waits in Runs instead of failing. See Steps as AI tools and Action approval.

Tools you can connect include the dedicated tools (HTTP Request Tool, MCP Client Tool, Workflow Tool, Calculator, Web Search…), the Browser block, and app and page steps used as tools (Slack, Gmail, Google Sheets, Notion…). Add them from the agent’s Building blocks at the top of Setup. What tools return from outside (pages, API answers) reaches the model fenced as data.

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.

Connect a second chat model to Fallback. When the main model fails before writing anything with an error worth retrying elsewhere (rate limit 429, payment or key problems 401/402/403, a 5xx, a network error), the same call goes to the fallback. The run log names the switch, and the output gets usedFallback: true.

With an output parser and a model that can use tools, new Tools Agent steps get the answer back as a tool call with typed fields, checked against the parser’s schema. A wrong answer is asked again once; then the step fails and lists the missing fields. Models that can’t use tools still read the answer from the text. Steps saved before 0.9 keep reading the text.

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). With a Chat Trigger, the agent’s answer streams into the chat as the reply; a Chat Trigger saved before 0.9 needs the same memory connected to the trigger and to this agent.

  • 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.

SettingTypeWhat it does
What should the agent do? (required)Long textUse data from earlier steps with Use data.
Options GroupThe options for the step.
Options › System message Long textThe system message to use.
Options › Max iterations NumberHow many times the agent may call tools before it must answer with what it has. Default: 10
Options › Knowledge documents (k) NumberHow many documents to retrieve from the connected knowledge base. Default: 4
Options › Max knowledge context length NumberMaximum characters of retrieved knowledge to inject into the prompt. Default: 4000
Options › Fail on knowledge error ToggleIf enabled, the step fails when knowledge retrieval errors instead of answering without context. Default: Off
Options › Knowledge search ChoiceHow 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 ChoiceHow passages are picked from the connected knowledge base. Options: Most similar, Diverse (MMR). Default: Most similar
Options › Match by ChoiceHow 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 NumberDrop passages less similar to the question than this (0 to 1). 0 keeps every passage. Default: 0
Options › Metadata filter Key-value pairsOnly 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 ChoiceA knowledge base marked "Device only" is never sent to a cloud model. Choose what the step 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.

  • Output

Each output item has these fields:

FieldTypeWhat it holds
response AnyThe model reply; the parsed result when an output parser is connected
steps List of entriesThe tool calls the agent made, in order
usage ObjectTokens the model used, as reported by the provider
sources List of entriesThe knowledge base sources used for the answer
usedFallback Text
Shape of an output item
{
"response": null,
"steps": [],
"usage": {},
"sources": [],
"usedFallback": "…"
}
  • 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.
SlotAcceptsConnections
Model (required)chat modelOne node.
Memory chat memoryOne node.
Knowledge vector storeOne node.
Tools toolsSeveral nodes can plug in.
Output Parser output parserOne node.
Fallback chat modelOne node.
  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.

  • “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 tool is waiting for your approval. Open Runs 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.
Edit page

Last updated:

Was this page useful?
Ask Aria about Tools Agent