Build an App with an agent v2

An AI coding agent can build both sides of a Flowgear App: the frontend in your local sample-App repository and the HTTP-bound Workflows that provide its backend. Builder MCP gives the agent verified Flowgear discovery, Debug, log, and save tools while the repository guidance keeps frontend calls on the Flowgear SDK.

Use a Test Environment and review each external side effect. The agent can accelerate delivery, but you remain responsible for the interface, Workflow behavior, API-key scope, and production release.

Before you start

Complete these prerequisites:

  1. Download the sample App for the intended Site and Test Environment.
  2. Extract it, open the project in an IDE or agent workspace, and run npm install.
  3. Register Builder MCP as flowgear in the agent. If you have multiple Flowgear MCP servers, use a unique MCP server name for each and update the name you intend for the current project in the AGENT.md file.
  4. Confirm that .env.local contains the intended Tenant, Site, and Test Environment keys.
  5. Confirm that you can run npm run dev and load the sample inside the Console debug route.

Ask the agent to read the project's agents.md before it changes code. That file defines the frontend architecture, SDK invocation rules, local development behavior, routing pattern, and Builder MCP dependency.

Give the agent a complete outcome

Describe the user's job rather than only naming screens. Include:

  • Who will use the App and what decision or action it supports.
  • The views, filters, fields, and validation the user needs.
  • The source systems and existing Connections that may be used.
  • The data each Workflow receives and returns.
  • Operations that create, update, or delete external data.
  • The Folder, Cluster, and naming convention for backing Workflows.
  • The Cookie-based Key or intended user and Workflow scope.

For example:

Build an exception-remediation App for finance operators.

The first vertical slice must list failed invoice integrations, let the user open one item, and retry it after confirmation. Use the existing ERP Connection and create the HTTP Workflows under Apps/Finance Remediation in the Test Environment. Return only the fields shown in the interface. Use Flowgear.Sdk.invoke for every backend call, preserve Console theme and routing, and do not put secrets in the frontend.

Discover exact contracts, build and Debug the smallest safe backend first, bind the frontend to the tested relative routes, run the local checks, and report anything that was not tested. Ask before selecting between Connections or running a mutation against the external system.

Establish the session context

At the start of work, the agent should:

  1. Load Builder Guidance once and call GetBuilderContext.
  2. Show you the connected Tenant, Site, and Environment.
  3. Inspect agents.md, the existing frontend structure, openapi.yml, and public/app.json.
  4. Identify reusable components and existing Workflow routes before creating new ones.
  5. Stop if Builder MCP points to the wrong Environment or the project targets different Tenant or Site keys.

Builder MCP changes persisted objects. Keep tool approvals visible until you understand the proposed sequence, especially for Workflow saves and Debug runs with external effects.

Build one vertical slice

Finish one end-to-end user path before expanding the App.

1. Define the frontend and API contract

Agree on the relative route, HTTP method, request payload, response shape, empty state, validation errors, and failure response. Keep the response narrow so the browser receives only fields the interface needs.

2. Build the Workflow backend

The agent should discover exact Node, Method, version, Connection, template, and schema contracts. For each new endpoint, it should:

  1. Create a matching HTTP receive/respond design.
  2. Save a blank Workflow shell to obtain a persistent key.
  3. Run candidate YAML in Debug mode under that key.
  4. Repair the latest failure and retest.
  5. Save the final tested YAML with its latest FileHash.

For an existing endpoint, the agent must fetch the current Workflow and preserve its Key and FileHash. See Build a Workflow with Builder MCP for the complete backend loop.

3. Confirm that the endpoint is invokable

The Workflow must be published in the Test Environment and permitted by a Cookie-based Key that includes the test user. The agent can ensure invokability for an existing persisted Workflow when access is uncertain, but you should still verify the key's permitted users and Workflows in the Console.

Refresh openapi.yml from the current Builder OpenAPI definition after backend routes change. Treat that file as endpoint discovery; the frontend call uses only the uppercase HTTP method and relative path.

4. Bind the frontend through the SDK

Call the endpoint with:

Flowgear.Sdk.invoke(method, relativePath, payload?, headers?, tenant?)

Do not use fetch or axios for embedded Workflow calls. Keep calls in service modules or explicit user actions, and avoid effects that can repeat a mutation because a component rendered again.

Use SDK helpers for Console alerts, confirmations, text prompts, external URLs, and parent-path synchronization. Keep client routing inside the App and send safe relative paths to the parent Console.

5. Test inside the Console

Run npm run dev, trust the local development certificate, and use the Console debug tab. Test:

  • Loading, empty, success, validation, authorization, and backend failure states.
  • The selected Environment and relative Workflow route.
  • Navigation and deep-link refresh behavior.
  • Console light and dark themes when the App uses theme context.
  • Confirmation before a consequential operation.
  • The Workflow log produced by each backend call.

Use small deterministic data. If a mutation cannot be tested safely, mock only the frontend state and report the backend path as untested; do not claim an end-to-end success.

Expand without losing the contract

After the first slice works, repeat the same loop for the next user path. Prefer several narrow Workflow endpoints over one endpoint that accepts an unrestricted action name or arbitrary system command.

When a Workflow response changes, the agent should update openapi.yml, the frontend model, its service call, and the visible error handling together. Retest existing paths so an agent-generated backend change does not silently break the interface.

Review before publishing

Ask the agent for a final report that lists:

  • Frontend files added or changed.
  • Workflows created or updated, with Console links.
  • The last successful Debug instance for each changed Workflow.
  • Relative routes and HTTP methods used by the frontend.
  • Required Cookie-based Key users and Workflows.
  • Tests, lint, and build commands that passed.
  • Untested paths, external side effects, and remaining constraints.

Then complete the App security checklist, build the package, publish the new App Version, and assign it only to the intended Sites.