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

{% hint style="info" %}
Showroom: [Merch shop assistant example](https://showroom.appfarm.app/use-cases/merch-shop-assistant), [Document extraction example](https://showroom.appfarm.app/use-cases/document-extraction) and [Translator example](https://showroom.appfarm.app/use-cases/translator), with their setup in Appfarm Create ([register](https://showroom.appfarm.app/sign-up) for access).
{% endhint %}

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 sequencing, parallel blocks, [Run action](/library/action-nodes/run-action.md), and [Run flow](/library/action-nodes/run-flow.md). See [Multi-agent patterns](#multi-agent-patterns). 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` stop 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.

## Key settings

### Model settings

| Property        | Description                                                                                                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Model**       | The large language model the agent uses: Claude Sonnet 5, Claude Sonnet 4.6, Claude Haiku 4.5, Mistral Large, Mistral Medium, or Mistral Small. Default is Claude Sonnet 4.6. |
| **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)

The **Conversation** section is shown only when **Mode** is **Assistant**. 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**            | 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**         | The string property carrying the message text. Empty messages are skipped unless they carry files.                                                                                                                                                                              |
| **Attachments**     | A reference or multi-reference property to a file object class, holding the files that arrived with each message. Only file references are listed. Use a multi-reference unless a turn can only carry one file.                                                                 |
| **Message files**   | *Displayed once **Attachments** is set.* The data source holding the file objects that **Attachments** points to.                                                                                                                                                               |
| **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. It is visible only once **Messages** is bound. |
| **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, and clearing **Messages** also clears it.         |

{% 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.

All tools are in one **Tools** list. Add a tool with **+**, then select its **Type**. The type decides what the tool grants and which settings it has:

| Type                 | What the agent gets                                                                                                                      |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Data source**      | Search, read, create, update, remove, persist or aggregate objects in one of the action's data sources. See [Data source](#data-source). |
| **File data source** | List, read, create, update, remove or persist files in one of the action's file data sources. See [File data source](#file-data-source). |
| **Action param**     | Read the value of an action param. See [Action param](#action-param).                                                                    |
| **Action variable**  | Read, and optionally update, an action variable. See [Action variable](#action-variable).                                                |
| **Action**           | Run another action in the flow. See [Action](#action).                                                                                   |
| **Flow**             | Run another flow. See [Flow](#flow).                                                                                                     |

Every tool except `ask_user` is configured by you. `ask_user` is supplied by the platform in assistant mode. See [ask\_user](#ask_user-assistant-mode).

### Tool types

#### Data source

Select which of the action's data sources the agent may use, which operations it may perform on it, 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.                                                                                            |
| **Aggregate**                    | Counts objects in the database and computes sums, averages, minimums, and maximums over the selected properties, optionally grouped. Nothing is loaded into the data source.                                                                                                  |

In assistant mode, a data source tool on the **Messages** data source is search only. No operations can be selected for it, and the tool is labeled **Search only (conversation)**. This keeps the agent from writing to its own conversation.

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 %}

**Aggregate.** With the **Aggregate** operation, the agent can count the objects that match a filter. It can also compute sums and averages over integer and float properties, and minimums and maximums over integer, float, and date properties. Results can be grouped by a boolean, string, integer, enum, reference, or date property. A date is grouped by year, month, week number, day of month, day of week, hour, minute, or second, in UTC. A grouped result holds at most 200 groups. Only selected properties stored in the database can be used, so runtime properties and function properties are left out.

{% hint style="warning" %}
**Important**

**Aggregate** requires aggregate permission on the object class, not read permission. Grouping and minimum and maximum values return the values of the selected properties, so the agent can get those values from objects that the caller isn't allowed to read. See [Permissions](/reference/security/permissions.md).
{% endhint %}

**Semantic search.** Semantic search is available when [semantic search](/library/action-nodes/semantic-search.md) is enabled for the solution. Select **Enable semantic search** to let the agent search the database by meaning rather than exact words, for example to find the articles that answer a question. Then select the properties to search in **Semantic search properties**. Only String and Rich Text properties that the tool has access to and that have **Enable semantic search** selected in the data model are listed, and each search runs on one property. Semantic search requires the **Read from database** operation.

The objects found are added to the data source, and the agent gets each one with a score from 0 to 1 based on similarity. A semantic search can't be combined with a filter. If the search index isn't ready, the agent gets an error and can use **Read from database** instead.

#### File data source

Select which of the action's file data sources the agent may work with, which operations it may perform on it, 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, including attached files. A PDF must be at most 10 MB and under 100 pages.                                                       |
| Size of an image           | 12 MB. An image over 1568 px on its longest edge is scaled down to that size, and must be at most 3.75 MB after scaling.                         |
| Share of the model's input | All files in the run together can use at most a quarter of the model's context window. For large PDFs, this limit is often reached before 10 MB. |

{% 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.
* When opening a file would exceed a limit, the agent is told why and can continue with the files it already has.
* If the agent opens a PDF of 100 pages or more, the model refuses it and the run fails.
  {% endhint %}

#### Action param

Expose selected [action params](/reference/actions/action-params.md) as read-only inputs. Each becomes a `get_param_<name>` tool.

#### Action variable

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

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

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.

#### ask\_user (assistant mode)

The one platform-supplied tool, available only in assistant mode. It isn't in the **Tools** list. It takes a single `question` string, has no side effects, and ends the run with the `user_input` stop reason and the question as the last message.

{% 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 %}

### Files

Files the agent reads as images or documents rather than as text. Every attached file is re-sent on every iteration of the loop, so attach what the task is about rather than everything available. The description of the **Files** section states which file types the selected model can read, for example "Claude Sonnet 5 can read images and PDF documents." Attached files count toward the same limits as files the agent opens with [file tools](#file-data-source).

| Property            | Description                                                                                                                                                                                                |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Reference files** | Material that doesn't change from run to run, such as a price list, a style guide, or the form the agent is filling in. Sent ahead of the conversation, so the agent has it before it reads anything else. |
| **Prompt files**    | The files this run is about, for example what the user attached to the message the flow was called with. Sent with the task prompt, so the prompt can refer to them.                                       |

### 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 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 **Stop reason** output indicates which limit was hit. |
| **Fail the node** (default) | 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`. Unlike the capped **Agent response** array, it always holds the final message. |
| **Stop reason**                  | Why the agent stopped: `completed`, `user_input`, `max_iterations`, `max_failures`, `timeout`, `tier_limit`, `aborted`, or `error`.                                                  |
| **Iterations**                   | The number of iterations that reached the model, including one that a timeout or an error ended early.                                                                               |
| **Input tokens / Output tokens** | Cumulative token usage, as separate bindings.                                                                                                                                        |
| **Tool call count**              | The total number of tool calls.                                                                                                                                                      |
| **Tool call log**                | The ordered tool calls, as an object array of `{ iteration, name, input, output, durationMs, error? }`.                                                                              |

**Agent response** and **Tool call log** bind to action variables with a [schema](/reference/platform-concepts/schemas.md) data type: an array of strings for **Agent response**, and an array of objects for **Tool call log**. The **Tool call log** schema can declare only the keys you need, such as `name` and `output`. The other outputs bind to string or integer action variables.

{% 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 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=<question>&goal=<user_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.
