> 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/reference/appfarm-ai/build.md).

# Build

Build enables conversational development inside Appfarm Create. Describe the desired app or functionality and follow along as the agent goes through the implementation tasks.

Build mode has a few limitations (see [#current-limitations](#current-limitations "mention")), but in general, it supports building full-stack [apps](https://docs.appfarm.io/reference/apps.md) and [flows](https://docs.appfarm.io/reference/flows.md).

{% hint style="info" %}
For a practical guideline, see the [Practical Guide to Appfarm AI](https://docs.appfarm.io/reference/appfarm-ai/practical-guide-to-appfarm-ai.md) section.
{% endhint %}

## Getting started

Describe the app you want Appfarm AI to build in the **What will you build today?** prompt on the **Home** page. The **Create app** dialog on the [Apps](https://docs.appfarm.io/reference/apps.md) page has the same prompt, labeled **What can I help you build today?**

<figure><img src="https://29237295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MiLU-xcHu0eLZiTxcmZ%2Fuploads%2FsgnlP6WZQcdMqCMK37tB%2Fimage.png?alt=media&amp;token=6af930ab-9272-4e91-8849-4ec8a6a063db" alt=""><figcaption><p>Screenshot of the Apps page in Appfarm Create with a prompt to build a new app.</p></figcaption></figure>

Once a prompt has been submitted, the orchestrator agent will ask questions, and once the scope is clear, create a plan for building the app. A plan is built by breaking the request down into implementation *tasks*. You can refine the plan by asking the agent to add, revise, or remove tasks.

<div align="center"><figure><img src="https://29237295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MiLU-xcHu0eLZiTxcmZ%2Fuploads%2FyZjrZE49gvmlkal5BxF7%2Fimage.png?alt=media&amp;token=060352d0-e469-4fa6-ab9a-3c45be479c4d" alt=""><figcaption></figcaption></figure></div>

<figure><img src="https://29237295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MiLU-xcHu0eLZiTxcmZ%2Fuploads%2FWTMnYFRURLdXDUiN5fFZ%2Fimage.png?alt=media&amp;token=58bf19a9-da68-4280-a044-37ecf5a92c70" alt=""><figcaption></figcaption></figure>

The plan is shown as a card with **Review plan**, **Skip**, and **Approve** buttons. Once you're satisfied with the plan, click **Approve**. The Appfarm AI sidebar shows the **Tasks** list, and the builder agents start working on the first task.

## Working with the builder

### Multi-agent architecture

The App Builder consists of multiple agents. The orchestrator is the main agent, with full knowledge of Appfarm Create and all subagents. It plans and delegates, asks questions, and ships tasks to subagents. It also validates the implementation of the subagents.

The subagents are the specialists and the builders. They can work in parallel, and the orchestrator tries to achieve parallelism if possible. Each subagent has differentiated instructions, tools, and metadata, allowing for lower token/credit usage.

The orchestrator hands tasks to these subagents:

* **Design**: UI and themes, connecting data to UI, and connecting actions to UI.
* **Logic & data**: App data (data sources and app variables), actions, business logic, and integrations.
* **Data model**: Object classes, enumerated types, and their properties.
* **Flows**: Flows, including Flow actions, endpoints, and params.
* **Code**: Code-only changes, such as editing a function you send from the [function editor](#function-editor-ai).
* **Explorer**: Reads the Solution and searches the web, then reports back. It never changes anything.
* **Utility**: Languages and translations of texts.
* **Data generation**: Creates records in the Development environment for testing.

If you want to work directly with one of the subagents, e.g. if you are only doing UI work, you can select them directly through the [Agent Focus](#agent-focus) mode.

### **Tasks and changes**

When building an app or making big changes to existing apps, subagents work on **Tasks**.

<figure><img src="https://29237295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MiLU-xcHu0eLZiTxcmZ%2Fuploads%2FVDBX8ZFHn3KQANXIvDVa%2Fimage.png?alt=media&amp;token=41cfd3ec-bc7d-48e7-a925-b03e746de53f" alt=""><figcaption></figcaption></figure>

After you approve the plan, the orchestrator runs the tasks one after another without pausing between them. The **Tasks** list shows how many tasks are done, for example **1/2**.

To stop the build process, click the Stop icon in the bottom-right of the AI Panel. A **Continue** button will appear. In the AI panel, each task has its own tile with timers. Each tile represents a subthread. Click the tile/task to see details of the subagent work.

The **Change history** panel lists all components created or touched by the agents. Click any item in the list to jump to its location in Appfarm Create. You may also **adjust anything visually** (e.g. change the order of input fields in a Dialog, or add an action node to an Action) while the agents are running (or after).

You can also view and **Undo** all changes done by the agents in the top-right Undo/Redo menu. You can only Undo when the agents are *not* running:

<p align="center"><br><img src="https://29237295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MiLU-xcHu0eLZiTxcmZ%2Fuploads%2FmotuFzRYFJmz3J9jNNWn%2Fimage.png?alt=media&amp;token=ce39ac35-b76b-4127-8571-5d3c5634b350" alt=""></p>

### **Error handling**

The agents can make mistakes, such as faulty logic in an action or suboptimal UI. Fix them by prompting the agent (see the [Practical guide to Appfarm AI](https://docs.appfarm.io/reference/appfarm-ai/practical-guide-to-appfarm-ai.md) section) or manually.

The agents may also make changes to your models that aren't technically valid in Appfarm Create. When the agent completes an operation, all changes pass through a validation layer. If any errors are detected, these are automatically sent back to the agents, which will then attempt to fix them. If the agents can't resolve the errors after several attempts, it will pause and ask whether you'd like it to continue.

When you hit an issue, give [feedback](https://docs.appfarm.io/reference/appfarm-ai.md#feedback) with the <i class="fa-thumbs-up">:thumbs-up:</i> or <i class="fa-thumbs-down">:thumbs-down:</i> button after the agent's response.

{% hint style="success" %}
Suppose Appfarm AI builds an app or functionality that does not seem to work during testing: try explaining to Appfarm AI *what* does not work in clear terms. If there are error messages in the [developer tools](https://docs.appfarm.io/reference/appfarm-client/developer-tools-for-apps.md), also copy this error message and add it to your prompt. In many cases, the AI will be able to fix the error or incorrect logic. *Example: If a Save button does not work, mark it inside Appfarm Create and type "Nothing happens when I click this Save button".*
{% endhint %}

### **Threads**

A thread is a conversation with the agent that may include a list of tasks. When you send a message to the agents, the entire thread is sent as context along with the status of all associated tasks. By default, Appfarm Create starts a new thread on a fresh reload of Appfarm Create.

* **Start new thread:** Click the <i class="fa-plus">:plus:</i> icon in the top right corner of the Appfarm AI sidebar.
* **Show thread history:** Click the thread name in the top left corner of the Appfarm AI sidebar to view your ten most recent threads in the current Solution. Type in **Search threads** at the top of the list to filter the threads by name. Select any thread to continue the conversation and complete unfinished tasks.

**When a build thread grows long, Appfarm AI offers to continue in a new thread.** A **Continue in a new thread?** card appears in the thread. Click **Start new thread** to go on in a new thread that starts from a short brief of what is built and what is next, or **Continue here** to keep building in the current thread. Once the new thread has started, **Open thread** on the card takes you to it.

{% hint style="success" %}
A long thread is slower and costs more per message, so start a new, clean thread once in a while. If the AI gets stuck, try to create a new thread or refresh Appfarm Create.
{% endhint %}

### Agent Focus

When using build mode, you can actively choose one of the available subagents. We call this **Agent Focus**. You may select, e.g., the Frontend agent directly, meaning you will talk directly to a specialized subagent for design and UI work.

<figure><img src="https://29237295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MiLU-xcHu0eLZiTxcmZ%2Fuploads%2F0K8OBm0XreduiPAxJQS0%2Fimage.png?alt=media&amp;token=78812bbf-760c-43e0-aaab-9d6924aa08b0" alt=""><figcaption></figcaption></figure>

The subagents/agent focus are:

* **Frontend**: All UI work, including connecting data to UI and connecting actions to UI. It can not add app data or build actions or data model, but it can build or extend themes.
* **Logic & data**: Can build actions and add app data to the app
* **Data model**: Build or extend object classes or enums.
* **Flows**: All work related to building Flows.

## Solution memory

The agent is instructed to follow a defined "best practices" for building Appfarm apps. For example:

* Apps should use Dialogs for input (New/Edit records), Drawers for details pane (read-only details), both using the same runtime-only single cardinality data source.
* Datasources: Use database-connected for listing (plural tense naming) and single-cardinality runtime-only for Dialogs/Drawers (create/edit/display details, with `" (temp)"` as naming postfix).
* Actions naming: Use the main entity as a prefix (e.g., prefix `"Projects - "` for all project-related actions).

You may override these instructions or add other preferences (naming, UI/layout, colours etc) in **Solution memory**. Solution memory is located in the Settings in Appfarm Create, under **Appfarm AI** (open Settings from the solution name in the top-left menu). It holds facts the agent keeps about the Solution, such as a naming rule or a customer constraint. *Solution memory is shared by every developer in the same solution.* Each new thread reads all of it, so a change reaches threads started after it.

* Add a fact in the text field and click **Add entry**. Solution memory holds up to 4,000 characters in total.
* Appfarm AI can also save facts to Solution memory while you work. Changes it suggests but doesn't make on its own are listed under **Awaiting review** for a developer to approve or reject.
* Only roles that can update private files can edit Solution memory.

The older **Agent knowledge (deprecated)** field is still shown below Solution memory. The agent still reads these guidelines, but add new ones to Solution memory instead.

<figure><img src="https://29237295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MiLU-xcHu0eLZiTxcmZ%2Fuploads%2F4wt4lqyELJoqFxWING0O%2Fimage.png?alt=media&amp;token=87217445-da57-4777-b8fc-da9ee10c339a" alt=""><figcaption></figcaption></figure>

## How the agent works

When you give Appfarm AI a task or prompt, your application metadata (the views, actions etc) is sent as [context](https://docs.appfarm.io/reference/appfarm-ai/context-handling.md) .

By default (i.e. no Agent Focus has been selected), you talk to the orchestrator agent. It can not build. Based on the [Solution memory](#solution-memory) and the current location/selected component in Appfarm Create, it determines the intent and asks questions or delegates clear tasks to the subagents.

A subagent is activated when it receives a task from the orchestrator, or when Agent Focus is selected by the user. Each has its own system instruction and tools set. Based on its system instructions, the [Solution memory](#solution-memory), and the current location/selected component in Appfarm Create - the subagent determines the intent, identifies the available tools, and determines which ones to use. Through these tools, the agent learns how the building blocks work in Appfarm Create. It then issues commands to insert, update, or delete parts of the application model. These commands function identically to actions performed by a human user, so the same guardrails and rules apply.

**Appfarm AI has access to web search.** In other words, you may refer to URLs. For example: 1) You may ask Appfarm AI to use colours and fonts from your homepage, or 2) you may provide a link to the documentation of an integration, in order to help Appfarm AI do better.

**Appfarm AI can read your development data.** It looks up record IDs in the Development environment when it generates records or references existing ones. If [**Development data access**](https://docs.appfarm.io/reference/appfarm-create/settings.md#appfarm-ai) is turned on, it can also read record values to answer questions about your data, for example why a list shows no records. Read more in [Context handling](https://docs.appfarm.io/reference/appfarm-ai/context-handling.md#development-data).

Read more about our [approach to AI](https://www.appfarm.io/ai/our-approach).

## Function Editor AI

To get help with a function, click the chat icon in the Function editor, **Continue in Appfarm AI chat**. Create saves the function, closes the editor and starts a message about that function in the Appfarm AI sidebar. Describe what you need and send it as a normal Build message.

## Current limitations

The agent is currently able to work with the following concepts in Appfarm Create:

* [Apps](https://docs.appfarm.io/reference/apps.md)
* [App data sources](https://docs.appfarm.io/reference/apps/data/data-sources.md)
* [App actions](https://docs.appfarm.io/reference/actions.md)
* [UI](https://docs.appfarm.io/reference/apps/ui.md)
* [Functions](https://docs.appfarm.io/reference/platform-concepts/functions.md)
* [Conditions](https://docs.appfarm.io/reference/platform-concepts/conditions.md)
* [Themes](https://docs.appfarm.io/reference/resources/themes.md)
* [Object classes](https://docs.appfarm.io/reference/data-model/object-classes.md)
* [Enumerated types](https://docs.appfarm.io/reference/data-model/enumerated-types.md)
* [Flows](https://docs.appfarm.io/reference/flows.md)
* Translations of texts into the languages in your Solution

Appfarm AI has **not** yet been instructed to build

* Advanced charts / Gantt
* Offline support
* Performance analysis/improvements
* [Services](https://docs.appfarm.io/reference/services.md)
* Permissions and environment/login config
* Complex deletions for large solutions (requiring a chain of deletions in correct order)

Services are read-only for Appfarm AI, but it can read a Service and build a Flow that does the same. It can't create, edit, move, or delete a Service or anything inside one. It also can't change what a service depends on, such as the object class properties, enum values, secrets, and action params the service uses. If a service uses an optional built-in property of an object class, the whole object class is read-only. Appfarm AI can still add new properties to an object class that a service uses. Make other changes manually in Appfarm Create.


---

# 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/reference/appfarm-ai/build.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.
