An engineering look at how platform architecture, domain contracts, and context lifecycle management enable AI agents to build complete, cross-domain business workflows.
When a merchant asks for a restrained UK product launch with an opening offer, generating a standalone, visually attractive UI component is a hollow victory. A working launch requires orchestrating deterministic business realities—products, inventory, promotional pricing, shipping policies, and return terms—alongside open-ended interaction design.
Creating valid database records and writing valid source code in isolation does not ensure the end-to-end experience works. For an AI agent to complete this unpredictable, cross-domain business goal, the environment itself must be legible. The central architectural challenge is organizing existing business capabilities and creative resources so an agent can discover, compose, and verify them within finite context and execution budgets.
Agents armed with tool calling often struggle when handed a monolithic OpenAPI specification. Dumping hundreds of endpoints into the prompt rapidly exhausts execution budgets and degrades focus. Instead, the environment must support progressive discovery.
The task begins with createBusinessClient(baseUrl). An agent calls client.catalog() to list domain purposes, contract paths, and dependsOn graphs. This allows the model to selectively call client.read(domain) only for the necessary data. Crucially, these domain reads carry a revision. If the agent performs multiple reads, it can observe versions and maintain stable references.
Consistent domain modeling prevents the model from hallucinating translations. If a record uses priceMinor, it strictly means integer GBP pence; a destination is explicitly country: 'GB'. Explicit IDs let the agent create and relate objects safely.
If the generated page code were responsible for fetching and joining product, offer, shipping, return, and media data, it would force the agent to reproduce complex calculations in every view. This bloats the code and invites errors.
Instead, the host implements a task-oriented read model, campaignView, exposed publicly as client.campaign(id). This composite view trades the purity of normalized data for a bounded, task-specific projection that drastically reduces the agent's cognitive load.
Writing to the system is handled through a unified batch operation. The apply mechanism creates or fully replaces objects by ID. It collects all operations and validates the candidate state. A new entity can reference another created in that same batch. If a product or promotion reference is broken, the batch rejects entirely.
However, a structurally valid schema does not guarantee business readiness.
Consider a concrete complication from the reference's scripted walkthrough. The initial plan creates a gb-standard shipping record but intentionally saves a campaign draft (quiet-mornings) that incorrectly references an ie-standard policy.
The apply operation saves this incomplete draft because the platform separates structural persistence from business readiness. An agent or script must verify the result:
const readiness = await client.check('quiet-mornings');
// Returns: { revision: 142, issues: [{ code: 'shipping_coverage', message: 'Select a shipping policy covering GB.' }] }Because the campaign has a readiness gap, client.campaign('quiet-mornings') and checkout ordering are blocked. The caller doesn't guess why the checkout failed; it reads the explicit shippingcoverage error and repairs the relationship using the current revision:
const { revision, rows } = await client.read('campaigns');
const campaign = rows.find(row => row.id === 'quiet-mornings');
await client.apply({
expectedRevision: revision,
operations: [
{ domain: 'campaigns', value: { ...campaign, shippingPolicyId: 'gb-standard' } }
]
});
const result = await client.check('quiet-mornings');
// Issues are now empty; the campaign is ready.Passing one check cannot replace the others. A syntax or build failure requires code repair; a shippingcoverage failure requires business relationship repair. An agent can use this exact feedback loop to navigate the domain, but the design shifts the burden of validation from the agent's predictive capabilities to the platform's deterministic rules.
Business validation cannot settle design decisions. Suppose the merchant's media library contains a synthetic product cup with a handle extending to the right, and a top-down, wider serving tray.
If the platform forces the agent to merely replace labels in a rigid template, the CSS will likely crop the cup's handle or misalign the tray. Fixed crops fail when asset geometries differ.
To solve this, the environment preserves ordinary-code creative freedom. SDK docs and ordinary React/TypeScript/CSS files act as shared authoring surfaces. Template briefs are provided not as restrictive boilerplates, but to communicate the shopper journey and adaptation intent. Media metadata narrows the asset choice by describing subjects and transparency, while actual pixel observation helps the agent resolve the final composition. If the handle overlaps text, the visual feedback drives a layout repair or a different asset choice.
When a merchant changes a requirement or a source file is revised, earlier screenshots and API reads become descriptions of obsolete states. Context is not a monotonically expanding log; it is a lifecycle.
An effective environment distinguishes between the current goal, confirmed facts, unresolved gaps, the active source version, and the latest relevant observation. Recoverable raw history is maintained, but the model-facing context uses a bounded projection. Designing an agent involves deciding when to retrieve more information dynamically versus when to carry it explicitly each turn. Rechecking changed inputs is vastly more efficient than repeating identical screenshots of a broken layout.
These patterns are materialized in a public, runnable teaching reference at foundax/agent-native-business-environments.
It features a single-shop Node host with JSON persistence and an SDK usable from Node or the browser. Running npm run demo executes a deterministic, scripted example with synthetic data. It intentionally creates the interrelated records, demonstrates the GB/IE shipping failure, repairs it, and serves the template.
The reference package provides the necessary environment to explore this architecture: a runnable single-shop host, SDK, CLI, and template guidance. While broader concepts like automated context-lifecycle management and model orchestration are discussed via design and pseudocode, the environment itself is fully operational. The included TASK.md provides an entry point for engineers to attach their own agents, bringing custom browser, vision, and computer-use tools. This open sandbox allows teams to evaluate how well their agents perform—measuring latency, context usage, and turn counts alongside the actual business, interaction, and visual quality of the final launch—against explicit, shared contracts.
Exploring how coding agents operate within business software. While agents reason about workflows and use code to compose tasks, the host platform manages data permissions, durable project state, gated writes, and continuous human editing.
For bounded actions, standard tool calling works well. But for multi-step e-commerce workflows, code execution provides a cleaner path for composition. We share our architecture evolution across sandboxing, authorized views, immutable snapshots, watermarks, and approval gates.
While AI can quickly generate functional React components, fine-tuning layout details and validating dynamic business data directly in raw code creates friction during product iteration. Pairing generated code with an interactive canvas allows teams to inspect and refine interfaces in context. In this post, we share our architectural lessons on bridging the two: using provenance tracking to trace rendered UI back to originating source expressions, instance scoping to apply visual adjustments without corrupting shared component definitions, and version reconciliation to preserve layout changes across iterative updates and concurrent edits.