Agent Loop

Overview

The Agent Loop node runs a multi-turn AI agent that can call MCP tools and other Falcon nodes you expose to it, looping until the task is done. It runs on the provider of your choice — OpenAI, Anthropic, Google, or Ollama — with tool-calling on all four. Use it when a task needs runtime decision-making, multi-step tool use, or iterative refinement — for deterministic single-shot work, prefer the AI Prompt node instead.

When to use Agent Loop vs. AI Prompt

• AI Prompt — one request, one response. Predictable cost, no tool use. Best for classification, transformation, single-shot generation.
• Agent Loop — multi-turn with tools. The model can call MCP servers or sibling Falcon nodes (HTTP, Postgres, send-email, send-SMS, Outlook, Google Sheets, set), receive results, and decide what to do next. Best for triage, research with tools, self-critique-and-revise, agentic workflows.

Configuration

• LLM Provider — choose OpenAI, Anthropic, Google, or Ollama. Defaults to Anthropic. Switching the provider resets the model and credential to that provider's defaults.
• API Credential — optional, filtered to the selected provider. If set, the workspace pays the provider directly (BYOK, zero AI credit consumption). If unset, the platform key is used and tokens are deducted from the workspace AI credit bucket. (Ollama is self-hosted and always runs BYOK.)
• Model — the list is filtered to the selected provider (e.g. Claude Sonnet/Opus/Haiku, GPT-5/GPT-4o, Gemini 2.5/3, or a local Ollama model). Defaults to that provider's default model.
• Temperature — 0 (deterministic) to 2 (creative); defaults to 0.7. Lower values are usually better for reliable tool use.
• System Prompt — optional. Supports {{variables}}.
• User Prompt — required. Supports {{variables}}.
• Max Turns — defaults to 10. Hard ceiling: 25.
• Max Tokens — defaults to 1024. Hard ceiling: 8192.
• MCP Servers — multi-select of workspace MCP servers the agent can call.
• Tools — wire a sibling node into the agent's 🔧 Tools port to expose it as a callable tool. Action types: http-request, postgres, send-email, send-sms, set, microsoft-outlook, google-sheets. You can also wire ai-prompt and agent-loop nodes in as sub-agents (see below).
• Output Variable — defaults to agent_result. The agent's final response, turn count, stop reason, token usage, and tool-call log are stored here.
• Conversation Memory — same shape as AI Prompt's memory options. Only the final user prompt + final assistant response are persisted between runs (intermediate critique/revision turns are kept in-process).

Providers & tool support

The agent runs on the selected provider, and tool-calling works on all four. Each provider's native tool protocol is normalized internally, so MCP tools, exposed sibling nodes, and sub-agents behave the same regardless of provider.

• Anthropic — tool use on all modern Claude models.
• OpenAI — function calling on all modern models.
• Google (Gemini) — function calling on all modern Gemini models.
• Ollama — tool use is model-dependent. Use a tool-capable local model (e.g. llama3.1, qwen2.5, mistral-nemo).

If you wire tools into the agent but pick a model that can't use them, the node fails with a clear message naming the model and suggesting a tool-capable one — it never silently ignores the tools.

Sub-agents (orchestrator pattern)

Wire an ai-prompt or agent-loop node into the Tools port to turn this Agent Loop into an orchestrator that delegates to specialized sub-agents and combines their results — and it can fan out to several.

• AI Prompt sub-agent — a single-shot specialist on any provider (OpenAI, Anthropic, Google, Ollama). Best for classification, extraction, or summarization where you want a specific model. No tools of its own.
• Agent Loop sub-agent — a full specialist that runs its own multi-turn loop with its own provider, tools, and knowledge (e.g. a “CRM agent” with HubSpot tools). Each sub-agent can run on a different provider than the orchestrator.

The orchestrator calls each sub-agent as a tool, passing a natural-language task; the sub-agent runs with its own configured prompt/model/tools and returns its result. Nesting is allowed (a sub-agent can have its own sub-agents) up to a depth of 3. Each Agent Loop in the tree runs its own credit check.

Operation-multiplexed nodes

For Microsoft Outlook and Google Sheets, the source node MUST have its operation configured before exposing it. Set the operation in the source node's config panel first; the agent then fills only the runtime input, not the operation.

• Outlook operations: message.send, message.reply, message.getMany, message.get, calendarEvent.create, calendarEvent.getMany, calendarEvent.update
• Google Sheets operations: getRange, appendRows, updateRange

Output

The output variable contains:

• response — the agent's final text response
• turns — number of turns consumed
• stopReason — normalized across providers: stop, tool_use, max_tokens, or other
• inputTokens / outputTokens
• toolCalls — array of every tool the agent invoked, with input, result, and error flag

Plan availability

Agent Loop requires PRO or higher on the platform-credit path. FREE tier workspaces can still use Agent Loop by attaching their own provider credential to the node (BYOK) — the workspace pays the provider directly with zero AI credit consumption. (Ollama is self-hosted and always runs BYOK.)

Security

• Each tool call runs in an isolated execution context — the agent cannot read or pollute the parent workflow's variable bag.
• Credentials on exposed sibling nodes are fixed at config time. The agent cannot substitute a different credential at runtime.
• MCP servers are scoped to the workspace. Only servers the workspace owns can be referenced.
• Hard ceilings on turns and tokens cap worst-case cost per run regardless of node config.

Required Credentials