Agent
The Agent action node runs an AI agent inside a flow. You choose a model, describe the task, and give the agent a set of tools. The agent reasons about the task and calls those tools as needed to complete it.
Like other action nodes, the Agent node returns no value to the nodes that follow it. Its result is the side effects its tool calls produce, such as records created or updated in a data source, or emails sent. The enclosing flow can then return whatever data the agent touched.
Because it is a regular action node, it composes with the other flow primitives. Sequencing, parallel blocks, Run action, and Run flow turn it into single-agent, sequential, parallel, and hierarchical patterns without extra wiring. A single Agent node can replace a chain of primitive action nodes and conditionals that would otherwise implement the same logic by hand.
The Agent node is available in flows. It can run unattended, for example behind a webhook, a schedule, or an action button. For the chat use case, an app calls the flow with Run flow once per user turn.
Conversation modes
The first setting to choose is the Mode. It changes both the rest of the configuration and how the agent is instructed to behave.
Autonomous (default)
The node runs unattended, behind a webhook, a schedule, or an action button, with nobody available to answer questions. The agent must complete the task or fail. It is never given the ask_user tool, so a run cannot stall waiting for input.
Assistant
The node backs a chat interface and is re-invoked on every send. A user is on the other end, so the agent can ask a clarifying question with the ask_user tool, which ends the run with the user_input termination reason.
A single invocation is one run of the loop. A run is always self-contained: the node is never suspended waiting for input. You build a multi-turn conversation by invoking the node again with the earlier conversation supplied as input, which restarts the loop rather than resuming it. Whether earlier context is replayed is governed by the Messages binding alone. Bound, it continues the thread; unbound, it runs a single turn.
Key settings
This section describes the settings of the Agent action node. The configuration panel groups them into model settings, prompts, conversation (assistant mode), tools, safety limits, and outputs.
Model settings
Model
The large language model the agent uses. The available models are managed by Appfarm.
Temperature
A number between 0 and 1 that controls randomness. Default is 0.
Max tokens
The maximum number of tokens the model can generate per turn. Default is 4096. This is a per-turn generation cap, not a total budget for the run.
Prompts
System prompt is static text, which can be data-bound, that defines the agent's persona, constraints, and behavioral guidelines. It persists across every iteration of the loop. The node also composes a mode-specific block onto it automatically, such as the instruction not to ask the user in autonomous mode.
Task prompt is the specific problem to solve, typically data-bound to a flow action param or the user's latest message. It is provided once at the start of the loop and is required in both modes. In assistant mode it is the latest user turn, not a restatement of the whole conversation.
Conversation (assistant mode)
In assistant mode, the prior conversation is supplied as data. You own the object class that stores the conversation, so the node needs to know only which property holds the role and which holds the content.
Messages
A data source on the action that holds the conversation, one object per message. Binding it continues the thread; leaving it unbound runs a single turn, which can still ask a question.
Role property
The string property carrying the role, either user or assistant. Matching is case-insensitive, and unknown roles are dropped with a warning. Only string properties are supported.
Content property
The string property carrying the message text.
Sorting
The sort that puts messages in chronological order. Created Date is the natural choice and needs no extra modeling. An action data source has no inherent ordering, so this must be set, and a warning fires if it is empty.
Append messages
When on, the node writes the task prompt back as a user message, and each assistant turn, including an ask_user question, as an assistant message, as they are produced. It is visible only once Messages is bound.
Tools
Tools are what the agent can invoke during its loop. Nothing is exposed automatically: you choose exactly what the agent can touch. Every tool except ask_user is configured by you, and ask_user is supplied by the platform in assistant mode.
Data source tools
Select which of the action's data sources the agent may use, and which operations it may perform on each.
Search (always granted)
Searches objects already loaded into the data source. A contains partial match works in memory on any string property, with no setup.
Read from database (query)
Fetches objects from the database into the data source. With Enable full-text search on, a contains match on the selected search-indexed properties runs a full-text search in the database instead of an in-memory match.
Create / Update
Generated only when selected.
Remove
Removes objects from the runtime data source only. This is never a database delete.
Persist
Commits pending creates and updates from the data source to the database, the same as Persist objects. It does not propagate removals.
Action param tools
Expose selected action params as read-only inputs. Each becomes a get_param_<name> tool.
Action variable tools
Expose selected action variables. The agent can read the variable on selection, and updating is opt-in per variable, for variables that are not read-only. This is useful for the agent to store intermediate state.
Action tools
Expose an existing flow action as a tool. Its name, description, input params, and return schema become the tool definition directly.
Flow tools
Expose another flow as a tool, with its name, description, and tool filter overridable. This is especially natural for MCP flows, and it turns your flow library into a reusable set of tools.
ask_user (assistant mode)
The one platform-supplied tool, available only in assistant mode. It takes a single question string, has no side effects, and ends the run with the user_input termination reason and the question as the last message. In autonomous mode the tool is absent by construction, which is what keeps an unattended run from stalling on a question.
Best practice
In assistant mode, make the System prompt explicitly require calling the ask_user tool for any clarifying question, and forbid asking in prose. Without this instruction, the model may ask its question as plain text and end the run with completed, so the chat interface cannot tell a question apart from a finished task.
Safety limits
Max iterations
The maximum number of reasoning and tool-call loops before the agent is forced to return. Default is 10, and the value must be at least 1.
Max consecutive tool failures
The number of consecutive tool errors allowed before the agent is stopped. Default is 3.
Timeout
The maximum wall-clock time for the whole run, in seconds. Default is 120, and the value must be greater than 0 and at most 3600.
All of these are data-bindable and validated when they resolve at runtime. An invalid value raises a configuration error that names the setting, rather than failing opaquely later.
On limit reached
On limit reached governs what happens when a safety limit is hit.
Complete gracefully
The node succeeds. Side effects from tool calls that already ran are kept, and the Termination reason output indicates which limit was hit.
Fail the node
The node throws, and the flow's error paths handle it. Side effects that already ran are not rolled back.
This setting applies to safety limits only. A completed or user_input result is a successful termination and never consults it, and a fatal error always throws.
Outputs
The agent passes no business return value, but its runtime outputs can be surfaced by binding each one to an action variable, so later nodes can read or branch on them.
Agent response
The agent's text responses across the loop, as a string array with one entry per assistant turn that produced text.
Last message
The most recent assistant text turn, or the ask_user question when the run ended with user_input. It is tracked independently of the (capped) Agent response array, so it is always the true final message.
Iterations
The number of reasoning loops that ran.
Input tokens / Output tokens
Cumulative token usage, as separate bindings.
Tool call count
The total number of tool calls.
Termination reason
Why the agent stopped: completed, user_input, max_iterations, max_failures, timeout, tier_limit, aborted, or error.
Tool call log
The ordered tool calls, as an object array of { iteration, name, input, output, durationMs, error? }.
Multi-turn conversations (assistant mode)
There is no provider-side conversation thread. The model APIs are stateless, so continuing a thread means the node holds the history and replays it. The node stores reconstructed { role, content } text turns, which are portable, inspectable, renderable, and durable across restarts.
Persistence is your decision. A data source on an action is in memory for the run, and nothing is written to the database unless a Persist objects node or the agent's persist tool does so. A session-scoped chat can stay in memory and cross the flow boundary as data. A durable chat reads the thread in and persists appended messages out.
Appfarm does not ship a chat component, so you build one from existing blocks: a repeater over a conversation data source, an input, and a send action that runs the flow with the typed text as the task prompt. There are two delivery patterns:
Synchronous Run flow with return mapping. The flow returns its messages data source, and the output bindings map back into the app. This is the simplest pattern and is best for short runs.
Asynchronous Run flow with persist and live update. For long runs, running the flow asynchronously hides the return and action-variable mapping, so delivery goes through the database: persist appended messages, and enable live update on the app data source. On this path, the outcome (
user_inputversuscompleted) must be carried as data, for example a status property on the conversation, because the output bindings are not available.
A returned streamable data source or variable can deliver assistant turns as live chat bubbles as they are produced.
Multi-agent patterns
Because the Agent node is a regular action node, the standard flow primitives become orchestration patterns:
Single agent. One node, with a low configuration bar.
Sequential. Several Agent nodes back to back. They share data implicitly through the action's data sources, with no wiring.
Parallel. Agent nodes in a parallel block, working concurrently on shared data.
Hierarchical. An agent exposes a flow tool whose flow contains its own Agent node, so an agent delegates to a flow that runs another agent.
Data security
Important
An agent can only ever do what the node's tools allow and what the calling identity is permitted to do. It gains no access of its own.
Two things bound what the agent can reach, and both hold no matter what the task or the model asks for:
Tool selection is the boundary. The agent can use only the tools you explicitly configure on the node. Nothing is exposed automatically, so any data source, action, or flow you did not add as a tool is unreachable.
The agent acts as the caller. Every tool call runs with the permissions of the user or service account that invoked the flow, and object class permissions are enforced server-side. The agent can never read or write data that the caller could not reach directly.
Error handling and observability
Tool errors are fed back to the agent as a message, such as Tool X failed: reason, so it can retry or try another approach. When consecutive failures reach Max consecutive tool failures, the safety limit stops the run.
Model errors, such as a rate limit or a network error, are retried with exponential backoff up to three times. A persistent model error fails the node.
Observability has three levels. If the Agent is run in an app, the client devtools log shows everything in real time, including per-iteration model input and output, every tool call, and timing. The output bindings surface the opt-in subset described under Outputs. The Logs view records one summary per run, given that the action containing the Agent action node has logs enabled.
Last updated
Was this helpful?