> For the complete documentation index, see [llms.txt](https://docs.appfarm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appfarm.io/library/action-nodes/agent.md). # Agent {% hint style="info" %} **Beta feature** The Agent action node is not generally available yet. Get in touch with your Appfarm contact to discuss early access, and read the [Agent action node pilot terms](https://policies.appfarm.io/service-and-usage/agent-action-node-pilot-terms). {% endhint %} The Agent action node runs an AI agent inside a [flow](/reference/flows.md). 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](/reference/apps/data/data-sources.md), 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](/library/action-nodes/run-action.md), and [Run flow](/library/action-nodes/run-flow.md) 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. | Mode | When to use it | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **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 | Property | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **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. Not available for models that set their own sampling, such as Claude Sonnet 5. | | **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](/reference/actions/action-params.md) 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. | Property | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **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. | {% hint style="info" %} **Good to know** The latest user turn must appear in either **Task prompt** or **Messages**, never both. With **Append messages** on, the node is the only writer of the user turn, so the chat interface must not create it first. Render the pending message from input state instead. {% endhint %} ### 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, which operations it may perform on each, and which properties it may see. | Operation | Effect | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **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](/library/action-nodes/full-text-search.md) 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](/library/action-nodes/persist-objects.md). It does not propagate removals. | Use **Properties** to choose the object class properties the agent can read, filter on, and write through the data source. Properties that aren't selected are hidden from the agent: they're left out of the tool definitions and removed from the objects it reads. Clearing a property also removes it from the searchable properties used for full-text search. When you pick a data source, all its properties are selected except built-in properties and properties with a [GDPR classification](/reference/data-model/object-class-properties.md#gdpr) of **Personal** or **Sensitive**. These are marked in the list, so you can add them if the task needs them. {% hint style="warning" %} **Important** Data source tools set up before Appfarm Create version 162 have no properties selected, so the agent only sees object IDs on them. Open each data source tool and select the properties the agent needs. {% endhint %} #### File tools Select which of the action's file data sources the agent may work with, which operations it may perform on each, and which properties it may see. A file data source is an action data source on a [file object class](/reference/data-model/object-classes.md#file-object-class). File tools suit tasks where the agent has to find or produce files, for example, to pick the relevant documents from a larger set, or when the result is itself a file. A file the agent opens stays in the conversation and counts toward the model's input on every later iteration of the run. No operations are selected by default. Select at least one. | Operation | Effect | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **List files** | Lists the files in the data source with their name, type, size, and selected properties, up to 50 at a time. Never includes content. The agent can filter the list on the selected properties. | | **Read file** | Opens a file for the model to read. Images (JPEG, PNG, GIF, WebP) and PDF documents are supported. | | **Create file** | Writes a new text file to the data source, such as a Markdown, CSV, or JSON file, and sets the selected properties on it. | | **Replace file content** | Replaces the whole content of a file the agent created in the same run. | | **Update file** | Sets the selected properties on any file in the data source. It can't change a file's name or content. | | **Remove file** | Removes a file from the runtime data source only. This is never a database delete. | | **Persist files** | Commits new and changed files in the data source to the database. | Files the agent creates or changes exist only for the run until they're persisted, either by the agent with **Persist files** or by a [Persist objects node](/library/action-nodes/persist-objects.md) after the Agent node. **Properties** work the same way as for data source tools. The agent sees the selected properties when it lists files, can filter on them, and can set the writable ones with **Create file** and **Update file**. A file's name, type, and size are always visible. If no reference property is selected, files the agent creates aren't related to any other object. These limits apply to a single run: | Limit | Value | | ---------------------- | ---------------------------------------------------------------- | | Size of a written file | 1 MB | | Files created | 25 | | Data written | 8 MB | | Data persisted | 32 MB, 60 files | | Files opened | 10 MB in total. A PDF must be at most 10 MB and under 100 pages. | {% hint style="info" %} **Good to know** * Created files must be text, such as `.txt`, `.md`, `.csv`, or `.json`. Files that would render as a web page, such as `.html` or `.svg`, can't be written. * Mistral models can't read file content. With **Read file**, they get only the file's name and type. * If the agent opens a PDF of 100 pages or more, the model refuses it and the run fails. {% endhint %} #### Action param tools Expose selected [action params](/reference/actions/action-params.md) as read-only inputs. Each becomes a `get_param_` tool. #### Action variable tools Expose selected [action variables](/reference/actions/action-variables.md). 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](/reference/actions.md) 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](/reference/flows/mcp-servers.md) 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. {% hint style="success" %} **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. {% endhint %} ### Safety limits | Property | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **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. | Option | Behavior | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **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](/reference/actions/action-variables.md), so later nodes can read or branch on them. | Output | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **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? }`. | {% hint style="info" %} **Good to know** The node clears the bound output variables at the start of every run, so a chat interface never renders stale values from a previous run. {% endhint %} ## 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](/library/action-nodes/persist-objects.md) 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_input` versus `completed`) must be carried as data, for example a status property on the conversation, because the output bindings are not available. A returned [streamable](/reference/actions/action-variables.md) 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 {% hint style="warning" %} **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. {% endhint %} Three things bound what the agent can reach, and all 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](/reference/security/permissions/designing-secure-permissions.md) are enforced server-side. The agent can never read or write data that the caller could not reach directly. * **Property selection narrows each tool.** On data source and file tools, the agent can't see properties you didn't select, either in the tool definitions or in the data it reads. ## 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](#outputs). The [Logs view](/reference/operations/logs.md) records one summary per run, given that the action containing the Agent action node has [logs enabled](/reference/actions.md#debugging). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.appfarm.io/library/action-nodes/agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.