AI Agent Node — BizFirstAI

What this node does: The FlowAiAgent node embeds a full agentic reasoning loop inside your workflow. You describe a goal in natural language, hand the agent a set of available tools, and the agent autonomously decides which tools to call, in what order, how many times — iterating until the goal is achieved or the maximum turn limit is reached. The agent maintains memory across all turns within a single invocation, produces a chain-of-thought trace, and records every tool call for observability.

How the Reasoning Loop Works

The agent operates a multi-turn think-act-observe cycle. Each turn the model reads the goal, all accumulated context, and the list of available tools, then either calls a tool or declares the goal complete.

Receive Goal → Think → Choose Tool / Done → Execute Tool → Observe Result → Think (next turn) → … until done

The loop terminates when either the model outputs a final answer (early termination) or the max_turns limit is reached. On early termination the node routes to the success port. On max-turns exhaustion without a final answer the node routes to the error port.

Supported Models

Model ID	Provider	Recommended Use
`claude-opus-4`	Anthropic	Complex multi-step reasoning, high-stakes decisions, long tool chains
`claude-sonnet-4`	Anthropic	Balanced capability and speed — default for most business agents
`claude-haiku-3-5`	Anthropic	High-volume, low-latency simple routing tasks
`gpt-4o`	OpenAI	GPT-based workflows, vision-augmented agents
`gpt-4o-mini`	OpenAI	Cost-efficient OpenAI alternative for simpler tasks

Key Capabilities

Multi-turn reasoning — the agent retains full conversation context across all turns in one invocation
Structured tool use — tools are declared by name; the agent receives structured input/output at every step
Chain-of-thought trace — every reasoning step is recorded and returned as reasoning output for debugging
Memory across turns — tool outputs are fed back into context so the agent builds on prior results
Early termination — the agent stops as soon as it achieves the goal, saving tokens and latency
Configurable temperature — set creativity vs. determinism to suit your use case
Custom system prompt — inject domain knowledge, persona, or constraints beyond the goal
Full observability — tool_calls output records every tool invoked with inputs and outputs

Business Benefits

Autonomous Customer Query Resolution

Instead of building a rigid branching workflow to handle every possible customer question, deploy an AI agent with tools to look up account data, check order status, query the knowledge base, and send emails. The agent decides which tools are needed for each unique query and composes a coherent response — handling rare combinations of questions without any workflow changes.

Intelligent Document Processing

Give the agent tools to read files, call classification APIs, extract fields, and route to queues. The agent reads an incoming document, classifies its type, extracts relevant fields based on that type, validates them, and routes to the correct downstream process — all in one agentic pass without hand-coded document-type branching.

Multi-Step Data Enrichment

Enrich a lead record by letting the agent call LinkedIn lookup, CRM search, company data APIs, and news feeds — synthesising all results into a single structured enrichment record. The agent handles partial failures gracefully, using whatever data it could retrieve.

Automated Report Generation

Provide tools for querying databases, calling analytics APIs, and writing files. The agent collects the data it needs, runs calculations, and produces a formatted report — adapting its data-gathering strategy dynamically based on what each API returns.

Use Cases at a Glance

Use Case	Tools Given to Agent	Goal Description
Customer support resolution	lookupAccount, checkOrderStatus, sendEmail	"Resolve this customer query: {@ $var.query }"
Lead enrichment	searchLinkedIn, lookupCRM, updateRecord	"Enrich this lead with company and role data"
Intelligent routing	classifyText, lookupQueue, routeRequest	"Classify this request and route it to the right queue"
Report generation	queryDB, callAnalyticsAPI, writeReport	"Generate the weekly sales summary for region {@ $var.region }"
Exception handling	getRecord, checkRules, escalate, sendAlert	"Handle this payment exception according to company policy"
NL parameter extraction	parseIntent, lookupProduct, buildParams	"Extract workflow parameters from this user instruction"

In This Guide

Configuration

Full property reference — goal, context, tools, model, max_turns, temperature, system_prompt.

Input & Output

Output ports, data schemas, and example agent responses with tool call traces.

Examples

Four complete examples: customer support, data enrichment, intelligent routing, and report generation.

Token and cost management: Each agent turn consumes tokens proportional to the accumulated context. Set max_turns conservatively (5–10) for production workflows and monitor token usage during testing. Use claude-haiku-3-5 or gpt-4o-mini for high-volume, simpler tasks to control costs. The turns_used output field helps you identify agents that are consistently hitting the turn limit.

How FlowAiAgent Differs from Chat and Prompt Nodes

Feature	FlowAiAgent	Chat Node	Prompt Node
Multi-turn reasoning	Yes — up to max_turns	Single prompt-response	Single prompt-response
Tool invocation	Yes — full tool use loop	No	No
Chain-of-thought trace	Yes — full reasoning log	No	No
Autonomous decision making	Yes	No	No
Suitable for	Complex multi-step goals	Simple Q&A, chat history	Text generation, classification
Cost per invocation	Higher (multiple turns)	Lower	Lowest

Use the FlowAiAgent node when the task requires the AI to make decisions, call multiple tools, or adapt its plan based on intermediate results. For fixed, single-step text generation or classification, use the Chat or Prompt node instead.

Tool Registry Integration

Tools available to the FlowAiAgent are defined in the BizFirst Tool Registry. Each tool is registered with:

Name — the identifier listed in available_tools
Description — what the tool does (the agent reads this to decide when to use the tool)
Input schema — JSON Schema defining required and optional parameters
Action — the HTTP endpoint, BizFirst sub-workflow, or built-in action to execute

The agent receives all tool descriptions automatically at the start of each invocation. You never need to describe tools inside the system_prompt — doing so wastes tokens and may cause confusion.

Observability tip: The tool_calls output array provides a complete audit trail of everything the agent did. Log this array to your monitoring system on every invocation. When an agent produces unexpected results, the reasoning trace and tool calls are the primary debugging tool — they show exactly what the agent concluded at each step and what data it received.

Production Readiness Checklist

Set max_turns to a conservative value — start at 5, increase only if needed
Set temperature to 0.0–0.2 for data-processing and routing agents; higher for summarisation agents
Always connect a handler to the error port — do not leave it unconnected in production
Instruct the agent to produce structured JSON output via system_prompt for reliable downstream processing
Log tool_calls, turns_used, tokens_input, and tokens_output to your monitoring system on every run
Set up an alert if turns_used == max_turns — this indicates the agent is struggling to complete the goal
Validate tool definitions — ensure all tools in available_tools are registered and have clear, accurate descriptions
Test with real workflow data before deploying — agent behaviour can vary with different input patterns