--- title: "Build Agent Reference" slug: "build-agent-reference" tags: ["build-agent", "unqorkai"] status: "update" updated: 2026-11-03T17:32:47Z published: 2026-11-03T17:32:47Z canonical: "docs.unqork.io/build-agent-reference" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.unqork.io/llms.txt > Use this file to discover all available pages before exploring further. # Build Agent Reference The Build Agent is an AI assistant in the Module Builder. Creators describe what they want in plain language. The agent creates a plan, builds the components, connects the logic, and runs tests to verify the result. The Build Agent can: - Build modules and multi-module applications from plain-language descriptions. - Create, edit, and use Smart Components across modules. - Generate complex logic or data transformations. - Edit existing applications and modules. - Understand, explain, and debug module configurations. - Automate repetitive configuration tasks. - Analyze configurations for accessibility improvements. - Work across modules in the same workspace by reading any module for context and writing to modules in other applications with confirmation. ## Accessing the Build Agent The Build Agent panel displays on the left side of the Module Builder. The panel has two tabs: **Active Task** for the live conversation, and **History** for all past tasks and plans. See [Build Agent](/unqorkai/docs/build-agent-overview) for the full panel reference. ## How the Build Agent Works When a Creator sends a message, the agent: 1. **Reads the module's current state**: all components, settings, and connections. 2. **Understands the request**: interprets the natural language instruction. 3. **Creates a plan**: in Plan & Build mode (the default), the agent generates a structured plan before building anything. The Creator reviews the plan, then selects **Build Plan** to proceed. 4. **Executes**: creates components, sets configurations, and generates logic. The agent self-corrects issues it encounters during execution. 5. **Runs tests**: if Auto-test is on, tests run automatically to validate the result. 6. **Summarizes**: lists all components configured, tests passed, and tasks completed. During execution, **Reasoning** and **Tool Calls** display as collapsible items in the chat. Expand them to see the agent's internal thinking and the actions it is taking at each step. When the agent needs more information to proceed, it pauses and displays a question with selectable options in the chat. Respond to continue. ## Writing Effective Instructions Clear instructions produce better results. ### Be Specific Tell the agent exactly what is needed, beyond the general idea. **Vague**: > Add a form. **Specific**: > Create a contact form with fields for first name, last name, and email address. Make all fields required. Submit the data when the Creator clicks the button. Once the agent builds the form, use follow-up prompts to refine it incrementally: > Add validation to show an error message if the email address format is invalid. > After successful submission, navigate the Creator to a confirmation page. ### Describe the Goal, Not the Steps Let the agent figure out the implementation. Describe the outcome to accomplish instead of the steps to take. **Step-by-step**: > Create a Data Workflow component. Add a filter operator. Configure the input and output fields manually. **Goal-oriented**: > Filter the submission data to only include records where status equals 'approved'. ### Provide Context If the agent must work with existing components or data, mention them by name. Use `@` in the prompt field to mention a specific module or application from the current workspace. The mentioned item displays as a chip in the context strip and is included as context in the next message. **Without context**: > Add a filter. **With context**: > Add a Data Workflow component that filters the data in the `submissionData` Hidden component to only include records from the last 30 days. the result to `filteredData`. ### Use Examples When the result depends on specific values or formats, give examples. **Without example**: > Format the phone number. **With example**: > Format the phone number in the format (555) 123-4567. Take the raw value from `phoneInput` and output the formatted result to `formattedPhone`. ## Smart Components For many tasks, the Build Agent creates **Smart Components**: reusable component definitions. The agent chooses between a Smart Component and a standard component based on what the task requires. | Task | What the agent typically creates | | --- | --- | | Data processing, calculations, conditional logic | Logic Smart Component | | Rendered interface elements, forms, custom layouts | UI Smart Component | | Simple, well-defined operations | Standard component (Calculator, Decisions, Data Workflow) | | Any component requested by name | The requested component | **Logic Smart Components** handle data processing. They run when triggered and return output data. Logic Smart Components are Private by default; when promoted to Public, they appear in the component tray. **UI Smart Components** render interface elements: forms, displays, and custom layouts. They receive data from submission data and other components and return data to the module through their output type. UI Smart Components are Private by default. Before creating a Smart Component, the agent checks the Public Smart Components in the environment and reuses one when it matches the request. The agent edits a Public Smart Component definition only when the Creator has it open in the Smart Components Hub. Both types are created as Private components. To reuse a Build Agent-created Smart Component across modules, open it in the Module Builder. Select the Smart Component to open the Focused Smart Component View, then select **Make Public**. See [Using Smart Components in a Module](/unqorkai/docs/using-smart-components-in-a-module) for editing and promoting details. ## Common Use Cases ### Collecting User Input Describe the fields, validation requirements, and how data should be submitted. **Creator**: > Create a contact form with fields for first name, last name, and email address. Make all fields required. Add a Button component with a Submit label. **The agent will**: 1. Create three input components (Text Field components for names, Email component for email address). 2. Set each field's **Required** toggle to **ON**. 3. Add a Button component labeled **Submit**. 4. Connect the Button component to submission logic. The agent might also add an Initializer component to configure the module's initial state, following Unqork best practices. ### Connecting Components The Build Agent wires triggers between components without manual configuration. Describe the interaction and the agent sets up the trigger chain. **Creator**: > When the `btnSearch` button is clicked, trigger the `plugDataFetch` Plug-In component. After the Plug-In component completes, trigger the `dwProcessResults` Data Workflow component. **The agent will**: 1. Set `btnSearch`'s **On Click** to the Property ID of `plugDataFetch`. 2. Set `plugDataFetch`'s **Post Trigger** to the Property ID of `dwProcessResults`. ### Debugging and Explaining The Build Agent can read a module and explain what is happening. Creators can ask why a component or configuration isn't working, and the agent inspects the relevant components, identifies the issue, and suggests a fix. **Creator**: > The `btnSubmit` button has an On Click trigger set but the form isn't submitting. What's wrong? **The agent will**: 1. Read the `btnSubmit` configuration. 2. Identify that an **Event** action type only fires the trigger and bypasses form validation and submission. 3. Explain the correct configuration based on the submission method, whether saving to Unqork's database or calling an external API. 4. Offer to update the button configuration. ### Working Across Modules The Build Agent can read any module in the workspace to inform what it builds in the target module. It can also write to modules in other applications in the same workspace. **Creator**: > Read the `orderApi` module to understand the submission data structure, then build a dashboard in this module that displays and filters the order data. **The agent will**: 1. Read the referenced module to understand its structure, components, and data. 2. Use that context to build or plan in the current module. > [!WARNING] > Cross-application writes require confirmation before executing and are scoped to one application per turn. If the target module is not in Editing mode, the agent displays a lock-refusal card. The card has a one-click action to take the editing lock and retry. ## Best Practices ### Review the Agent's Changes Always preview the module after the agent makes changes. Verify the result matches the intent before continuing. ### Refine Iteratively If the agent produces a result that is close but not right, refine the prompt with more specific instructions and continue in the same task. Describe exactly what to change. ### Use Descriptive Property IDs Creators should suggest clear Property IDs when asking the agent to create components. Descriptive Property IDs make the module easier to maintain. The agent defaults to camelCase (like `firstName` or `btnSubmit`), which is the recommended convention. To use a different naming style, specify it in the prompt. Whatever convention is used, avoid the following characters, which will break formula references, logic, and grid expressions: - Periods (`.`) - Dashes (`-`) - Spaces - Brackets (`[]`, `()`) Property IDs must also begin with a letter. **Creator**: > Add a Text Field component for the user's first name. Use the Property ID `firstNameInput`. ### Ask the Agent to Explain If the agent generates logic that is unclear, ask it to explain. **Creator**: > Explain what the Data Workflow component you created does. **The agent will**: - Walk through each step of the pipeline. - Explain what data goes in and what comes out. - Describe why each transformation is needed. ## Limitations ### What the Agent Cannot Do - **Access external systems directly**: The agent cannot connect to external databases or APIs on its own. It can call services already registered in Services Administration. Configure the service there first, then ask the agent to wire up the Plug-In component that calls it. - **Build or run Workflow Builder workflows**: The agent builds modules. It cannot create or execute workflows in the Workflow Builder. To incorporate the agent's work into a workflow, build the required modules with the agent first, then attach them to the workflow manually. - **Modify styles, themes, or CSS**: The agent has no access to style or theme tools. Style changes must be made in Style Administration for standard components, or in the Smart Component Theme Builder for Smart Components. - **Deploy changes**: The agent modifies the module configuration in the Module Builder. Creators must save and publish the module manually. - **Access production data**: The agent cannot read or modify submissions from production applications. - **Set RBAC or manage roles**: The agent cannot configure role-based access control. Role management must be done through [Creator Role Administration](/unqorkai/docs/creator-role-administration) and [Express Role Administration](/unqorkai/docs/express-role-administration). ## Tasks The Build Agent organizes conversations into **tasks**. Each task begins with a prompt and contains the full conversation, plan, and build history for that piece of work. Task history is saved automatically and persists across browser sessions. Select the ![icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261103_173031_c72b7553723b47b9ae8d6f0cfb909f8a.svg?sv=2026-02-06&spr=https&st=2026-11-04T09%3A31%3A08Z&se=2026-11-04T10%3A31%3A08Z&sr=c&sp=r&sig=i6QMzBZMrPvLgPSWpzG951PsgRFklo3W7KxFj0IW%2Bxg%3D) (**New Task**) button in the Build Agent panel header to begin a new task. The **History** tab displays all tasks and plans for the current module, grouped by time (Today, This Week, and Older). Each task row displays the first message as the title and a timestamp of the last update. An active indicator on the left edge of the row marks the currently open task. Select the ![icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261103_173031_1c53a30e796b4975a4143885d141c57a.svg?sv=2026-02-06&spr=https&st=2026-11-04T09%3A31%3A08Z&se=2026-11-04T10%3A31%3A08Z&sr=c&sp=r&sig=i6QMzBZMrPvLgPSWpzG951PsgRFklo3W7KxFj0IW%2Bxg%3D) (**ellipsis**) button on a task row to open the task actions menu. | Action | Description | | --- | --- | | **Download Debug** | Downloads a zip file of the task's full activity log. Send the file when reporting issues to Unqork Support. | | **Delete Task** | Permanently removes the task and its full conversation history. A confirmation dialog warns that this action cannot be undone. | Filter the list with the **Search tasks and plans...** field, **Tasks** and **Plans** toggle pills, and **Status** drop-down at the top of the History tab. ## Plans When Mode is set to **Plan & Build**, the agent creates a plan before building. Plans display as indented rows beneath their parent task in the History tab. Each plan row displays the plan title and a status badge. When the agent finishes executing a plan, the Active Task tab displays a **Task Plan completed** message with a **New Task** button. ### Rollback A rollback returns the module to how it was at an earlier point in a task. At key stages during execution, the Active Task tab displays a **Rollback** checkpoint. Each checkpoint marks the state of the module at that stage. Selecting **Rollback** on a checkpoint rewinds all agent changes made after it, including module configuration, conversation history, plans, and tests. A confirmation dialog displays before the rollback runs. Rolling back also affects Smart Components the agent created or edited after the checkpoint. Private Smart Components roll back with their module. For Public Smart Components, the confirmation dialog lists each one that will be restored or deleted, and the modules that use it. Rolling back restores a Public Smart Component's behavior only, not renames or settings. > [!CAUTION] > Rolling back changes cannot be undone. To stop an in-progress build, select **Stop Build** in the Active Task tab. Stopping halts execution but does not remove components the agent already added. Use Rollback to fully revert the module, or remove unwanted components manually. The Build Agent has no command to undo a change. To reverse changes, use Rollback to return the module to a checkpoint, or restore an earlier version in Module History. Asking the agent to edit a component back makes a new edit instead of reversing the original one. ## Managing Tests Tests generated by the Build Agent are in the **Tests** area of the Module Builder. Select **Tests** in the area selector above the canvas. The Tests area is only available when AI is enabled in the environment. The Tests area has two panels: - **Left panel**: Lists all test cases with their name, description, and status. Use the search field, **Active/Inactive** filter, **Run All** button, and **Create Test** button to manage the list. - **Right panel**: Shows the selected test's full details and a **Test History** table of past runs, each showing the date, time, and execution time. ## Version History The Build Agent automatically saves each change as a minor version during a session. To view and restore previous versions, select **History** in the Module Builder area selector, then open the **Module History** view. ## Prompt Input Type the prompt in the input field at the bottom of the Active Task tab. Press **Enter** to send or **Shift+Enter** to add a new line. The field accepts up to 100,000 characters. Type `@` to open the mention pop-up. The pop-up lists modules and applications in the current workspace. Type to filter, then select an item to add it to the context strip above the prompt. The item is included as context in the next message sent. Select **×** on any context chip to remove it. Select the ![icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261103_173031_01dc42fbd5374104a32b1397a4755641.svg?sv=2026-02-06&spr=https&st=2026-11-04T09%3A31%3A08Z&se=2026-11-04T10%3A31%3A08Z&sr=c&sp=r&sig=i6QMzBZMrPvLgPSWpzG951PsgRFklo3W7KxFj0IW%2Bxg%3D) **Attachments** button to attach a file. The agent reads the attachment and uses it as context for the prompt. | File Type | Supported formats | Use Cases | | --- | --- | --- | | **Images** | PNG, JPG/JPEG, GIF, WEBP | Screenshots of UI mockups, existing Unqork screens, or error messages. The agent analyzes the layout to build corresponding components or visually diagnose errors. | | **Text files** | TXT, MD, MARKDOWN, JSON, LOG, XML, YAML, YML | API responses, text logs, or configuration examples. The agent uses these to configure Data Workflows, debug data mapping issues, or apply conventions. | | **Spreadsheets** | CSV, TSV, XLS, XLSX, XLSM, ODS | Data samples or reference tables. The agent uses these to configure data structures or map fields. | | **Documents** | PDF (100 pages maximum across all attached PDFs) | Requirements documents or specifications. The agent reads them to generate a plan and build the required modules. | The total size of all attachments per Task cannot exceed 10 MB. ### Agent Configuration The composer toolbar displays two configuration chips: **Mode** and **Approvals**. Select either chip to open its selector and adjust how the Build Agent behaves. **Mode** sets the agent's approach to a request. | Option | Description | | --- | --- | | **Ask** | The agent answers questions about the module and analyzes it in read-only mode. Auto-test and Auto-fix are disabled in this mode. | | **Plan & Build** | The agent creates a plan for review and approval before building. Default mode. | | **Build** | The agent builds directly without creating a plan unless explicitly requested. | The Mode selector includes two toggles. Both are disabled when Mode is set to **Ask**. | Toggle | Description | | --- | --- | | **Auto-test** | When set to **ON**, this setting runs tests after the agent makes changes to verify they work correctly. | | **Auto-fix** | When set to **ON**, this setting automatically tries to fix issues that tests report. Requires **Auto-test** to be active. | **Approvals** controls whether the Build Agent pauses for confirmation during execution. This selector is unavailable when Mode is set to **Ask**. | Option | What requires confirmation | What runs automatically | | --- | --- | --- | | **Manual** | All creates, edits, and deletes | Nothing | | **Protected** | Deletes only | Creates and edits | | **Automatic** | Nothing | All actions, including deletes | A confirmation prompt displays in the Active Task tab when the selected Approvals level requires confirmation for the agent's next action. The agent pauses until the Creator responds. The following rules apply: - In **Manual**, a prompt displays before each create, edit, and delete. - In **Protected**, a prompt displays before each delete only. - In **Automatic**, no prompts display. - In **Ask** mode, no prompts display because the agent makes no changes. When a confirmation prompt displays, **Allow** approves that action and **Deny** cancels it. **Always allow edits** approves the action and sets Approvals to **Protected**. On a delete confirmation, **Always allow (incl. deletes)** approves the action and sets Approvals to **Automatic**. An approval covers the same kind of action on the same component for the rest of the task, so the prompt does not repeat. Delete actions always display their own prompt, even after the Creator approves edits to the same component. If the Creator replies in chat instead of answering a prompt, the agent treats the reply as the next instruction. The agent displays a new prompt if the action is still needed. A Smart Component prompt also lists the modules that use the component. When some of those modules are outside the Creator's access, the prompt states how many modules and workspaces are hidden and displays only **Deny**. The agent cannot change a component when modules the Creator cannot see use it. A Smart Component prompt also includes a ![icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261103_173031_c5b6f220dfd54dcfb488323a2a35448a.svg?sv=2026-02-06&spr=https&st=2026-11-04T09%3A31%3A08Z&se=2026-11-04T10%3A31%3A08Z&sr=c&sp=r&sig=i6QMzBZMrPvLgPSWpzG951PsgRFklo3W7KxFj0IW%2Bxg%3D) **Duplicate Component** button. Select it to create a copy of the Smart Component in the Duplicate Component dialog and leave the original unchanged. The agent then makes the requested change on the copy and displays a new prompt. > [!TIP] > **Manual** is the default setting. Use **Manual** when reviewing every change matters, like when working in a production-adjacent environment. Use **Protected** to speed up builds while retaining a check before deletions. Use **Automatic** only when full autonomy is intentional, because the agent deletes components and data without confirmation. A risk caption displays below the prompt input when certain mode and approval combinations are active: | Combination | Caption | | --- | --- | | Build mode (any approval) | "Agent will build without planning." | | Build mode + Automatic approvals | "Agent will build without planning and delete without approval." | | Plan & Build mode + Automatic approvals | "Agent will delete without approval." | ## Data and Privacy When a Creator sends a message, the agent might include module configuration data from the environment for context. For data flow diagrams, retention periods, and EU AI Act roles, see [Data, Privacy, and Security for UnqorkAI](/unqorkai/docs/data-privacy-and-security-for-unqorkai). | Topic | Details | | --- | --- | | **What data the agent accesses** | Configuration data in the Unqork environment. The agent does not access end-user submission data unless the Creator explicitly provides it in the prompt. | | **Data retention** | Data sent for processing is not used to train public models. | | **Training** | Unqork does not use Creator inputs to train the Build Agent for other customers. | | **Autonomous decisions** | In Plan & Build mode, the agent creates a plan and waits for Creator approval before building. Once approved, it executes autonomously in the Approvals level selected. The agent automatically saves each change as a minor version. Save the module manually to publish changes to the production application. | ## Troubleshooting ### Tests Fail on Slow-Loading Applications The Build Agent automatically extends its wait time when it detects that an application is slow to load, up to a maximum of 15 seconds. If an application consistently takes longer, for example because of a slow external data source, the agent might take a screenshot before the data loads. The test is then marked as failed even though the application is working correctly. To work around this, tell the agent explicitly how long to wait before capturing a screenshot: > "It is normal for this application to take about 20 seconds to load. Wait at least 30 seconds before taking the screenshot." The Build Agent respects explicit wait time instructions and overrides the automatic cap. ### Build Agent Does Not Detect Manual Changes The Build Agent tracks module state through the UnqorkAI platform. Changes made outside the agent during an active session are not detected automatically. This includes a Creator manually editing a component, deleting a test, or modifying a module in a separate tab. If manual changes affect what the agent does next, tell it explicitly before continuing: > "I manually updated @MyModel. Read it again before updating the title." Providing this context prevents the agent from building on outdated module state. --- **Changelog** | Date | Change | | --- | --- | | 2026-11-02 | Added a link to Data, Privacy, and Security for UnqorkAI in the Data and Privacy section and See Also. | | 2026-10-20 | Added Smart Component reuse behavior, the absence of an undo command, the **Task Plan completed** message, and when confirmation prompts display along with their buttons. Rewrote the Rollback section to explain checkpoints and Smart Component effects. Added the Smart Component prompt details: the module usage list, the hidden-modules case that shows only Deny, and the Duplicate Component button. Corrected the History tab time groups. Revised wording for style, including third-person voice, em dashes, long sentences, toggle descriptions, and the Limitations subheading. | | 2026-09-24 | Updated attachment size limit to clarify the 10 MB limit applies per Task. | | 2026-09-16 | Full accuracy and editorial rewrite: rewrote Tasks section to reflect History tab UI; rewrote Test Case Management as Managing Tests (Module Builder Tests area, not agent panel); rewrote Plans section (plans are History tab rows, no separate dropdown); removed stale thumbs-down feedback reference; removed incorrect "Asking for Expert Help" banner description; added @mention and context strip to Prompt ; added risk captions table to Agent Configuration; updated Approvals table to show create/edit/delete behavior per level; added guidance note on Approvals selection; corrected New Task button; updated See Also links. | | 2026-09-16 | Rewrote Agent Tools section — replaced stale toggles (Ask Mode, Auto-Plan, Auto-Delete Test Data) and old Approval option names with the current Mode selector (Ask / Plan & Build / Build), Auto-test and Auto-fix toggles, and Approvals selector (Manual / Protected / Automatic). | | 2026-09-14 | Fixed Logic SC description (canvas presence, tray availability when promoted); removed broken implementing-logic link; corrected external systems limitation (agent can call services registered in Services Administration). | | 2026-09-13 | Expanded Limitations: clarified workflow constraint covers building as well as executing; added styles/themes/CSS and RBAC limitations; added chat history persistence to Tasks section. | | 2026-09-15 | Added lock-refusal behavior to Working Across Modules; expanded Auto-Plan OFF description. | | 2026-09-12 | Remove Knowledge Nuggets section (feature removed); expand capabilities list (Smart Components, multi-module, edit existing); fix file specs (10MB limit, correct formats, remove HEIC/HEIF, PDF 100-page limit); fix workspace-level reading scope; remove model name from Data and Privacy. | | 2026-09-10 | Removed incorrect "each module has its own instance / context does not transfer" claim — tasks are workspace-scoped and the Active Task persists across modules. | | 2026-09-08 | Updated "Work across applications" capability to reflect cross-application writing. | | 2026-08-27 | Added Troubleshooting section covering screenshot wait-time cap and manual-change awareness. | | — | Initial publication. | Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. Debugging is the process of finding and resolving errors or bugs in an application. To debug an application in Unqork, use UNQENG tools in Express View. Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. Elements are are what you use to build Unqork applications. Elements include modules, workflows, Data Collections, Data Schema, and Record Collections. The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application. Rendering is the process of loading components and displaying the final result on the front-end screen. A Property ID is the unique field ID used by Unqork to track and link components in your module. APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. A data structure is the design used for organizing, using, and storing data. A Property ID is the unique field ID used by Unqork to track and link components in your module. A naming convention for computer programming. Use camelCase for Property IDs, for example: newUser, lastName, & rdoButton. APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. A definition RBAC (Role-Based Access Control) is a method to control system access for authorized users. The role in RBAC refers to the levels of access employees have to a network. A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases. TXT is a file format for plain text documents with little to no formatting. JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data. Extensible Markup Language (XML) is markup language that lets you define and store data in a shareable way. A data structure is the design used for organizing, using, and storing data. PDF (Portable Document Format) is a file format that allows users to share and print documents without modifying them. End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. A functionality of a software. For example, Copy and Paste is a feature of a computer's operating system.