# Agent-Native Runtime Architecture: How BuilderIO/agent-native Unifies UI, AI, and State

> Explore the Agent-Native runtime architecture by BuilderIO/agent-native. Learn how it unifies React UI, AI, and state with a SQL layer and Run Manager for durable background execution and real-time events.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: architecture
- Published: 2026-06-28

---

**The Agent-Native runtime architecture synchronizes a React UI, AI agent, and backend through a shared SQL state layer, using a Run Manager to orchestrate long-running turns with durable background execution and real-time event streaming.**

The BuilderIO/agent-native repository provides a framework for building AI-native applications where users and language models collaborate on the same state. The Agent-Native runtime architecture achieves this through a carefully designed system of primitives that manage actions, state persistence, and execution lifecycles across foreground and background environments.

## Core Components of the Agent-Native Runtime

The runtime is built around a small set of primitives that manage actions, state, and long-running turns. Each component serves a specific responsibility in maintaining the unified state model.

### Agent-Native UI

The **Agent-Native UI** is a React front-end located in applications under `app/` that renders the chat interface, tool-specific UI components, and real-time presence indicators. According to [`packages/core/README.md`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/README.md), this layer communicates with the backend through the same action primitives that the AI agent uses, ensuring both human users and models operate on identical state.

### Action Registry

The **Action Registry** declares server-side functions via `defineAction` in [`packages/core/src/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/action.ts). These functions are automatically exposed as:

- **HTTP endpoints** for UI interactions
- **Agent tools** with JSON Schema generated from Zod validation schemas
- **CLI commands** for development and automation

This unified exposure mechanism ensures that any business logic written once becomes available to all consumers of the Agent-Native runtime architecture.

### Run Manager

Located in [`packages/core/src/agent/run-manager.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/agent/run-manager.ts), the **Run Manager** coordinates the lifecycle of agent executions. It handles:

- Starting runs via `startRun`
- Persisting events to the SQL database
- Managing soft-timeouts and heartbeats
- Handling auto-continuations for long-running operations

The Run Manager creates an in-memory `ActiveRun` instance for each execution while maintaining durable state in the database.

### Production Agent

The **Production Agent** serves as the HTTP entry point at `/api/agent-chat`, implemented in [`packages/core/src/agent/production-agent.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/agent/production-agent.ts). This component:

- Validates incoming requests
- Resolves resource ownership
- Builds system prompts for the AI model
- Drives the main agent execution loop
- Handles background dispatch via `fireInternalDispatch`

The Production Agent implements the **Background-Aware Grace** mechanism through `resolveBackgroundDispatchOutcome`, which waits 15 seconds for a background worker to claim the run before atomically claiming it in the foreground.

### Durable Background and Self-Dispatch Worker

For operations exceeding the 40-second foreground soft-timeout, the architecture supports **Durable Background** execution through Netlify background functions (or similar platforms). As documented in [`packages/core/docs/design/durable-agent-runs.md`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/docs/design/durable-agent-runs.md), this system extends the execution budget to approximately 13 minutes (`BACKGROUND_SOFT_TIMEOUT_CEILING_MS`).

The **Self-Dispatch / Worker** mechanism operates as follows:

1. The foreground handler inserts a run row into the database
2. Fires an internal HMAC-signed dispatch to `/_agent-native/agent-chat/_process-run`
3. The background worker claims the run via `claimBackgroundRun`
4. Executes the full agent loop
5. Streams events back through the SQL event log

If the background worker never claims the run, the foreground reclaims it atomically, guaranteeing exactly-one execution semantics.

### SQL Event Log and State Layer

The **SQL Event Log** in [`packages/core/src/agent/run-store.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/agent/run-store.ts) stores every chat event in the `agent_run_events` table, including types: `data`, `done`, `error`, and `auto_continue`. Clients reconnect via `/runs/:id/events?after=N`, which polls against this table for real-time updates.

The **State Layer** uses a single Drizzle-compatible SQL database to hold:
- Application state
- Agent memory
- Action results
- Run metadata

This shared database approach enables instant synchronization and multi-user collaboration, as all parties read and write the same rows.

## Data Flow in the Agent-Native Runtime

The execution flow follows a precise sequence to maintain consistency across the distributed components:

1. **Client initiates** a POST request to `/api/agent-chat` from the React front-end
2. **Production Agent** validates the request, resolves the owner, builds the system prompt, and calls `startRun`
3. **Run Manager** inserts a `run` row, creates an in-memory `ActiveRun`, and begins streaming Server-Sent Events (SSE) to the client
4. **Conditional dispatch**: If `AGENT_CHAT_DURABLE_BACKGROUND` is enabled, the handler fires an internal dispatch to the background route
5. **Background execution**: The worker at `_process-run` claims the run and executes the full agent loop, writing each event to `agent_run_events`
6. **Client streaming**: The client receives events either from the in-memory stream (foreground) or via SQL-polling stream (`subscribeFromSQL`)
7. **Completion**: When the turn finishes, the run status updates to `completed` or `errored`, the heartbeat stops, and the in-memory run cleans up after a delay

## Defining Actions in Agent-Native

Actions represent the fundamental unit of work in the Agent-Native runtime architecture. The `defineAction` function in [`packages/core/src/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/action.ts) bridges the gap between UI components and AI capabilities.

```typescript
// packages/core/src/actions/email.ts
import { defineAction } from "@builder.io/agent-native/core";

export default defineAction({
  // Zod schema is compiled to JSON-Schema for the agent tool surface
  schema: z.object({
    emailId: z.string(),
    body: z.string(),
  }),
  // The function runs once per turn (or per auto-continue chunk)
  run: async ({ emailId, body }) => {
    await db.insert(replies).values({ emailId, body });
  },
});

```

Once defined, the action becomes automatically available:
- **To the UI** as a button triggering `POST /api/email`
- **To the agent** as a tool named `email` with the compiled JSON Schema

When the agent invokes this tool, the Run Manager persists the `tool-call` and `done` events, and the UI receives updates instantly through the shared SQL state layer.

## Durable Background Execution

Long-running operations require special handling to avoid foreground timeout limits. The Agent-Native runtime architecture supports extended execution through background functions.

```typescript
import { startRun } from "@builder.io/agent-native/core";

async function runLongTask(send, signal) {
  // Example: batch insert 10,000 rows, checkpoint every 1,000
  for (let i = 0; i < 10000 && !signal.aborted; i++) {
    await db.insert(items).values({ id: i });
    if (i % 1000 === 0) send({ type: "progress", detail: `${i} rows` });
  }
}

// In a production-agent handler (simplified)
const runId = generateRunId();
startRun(runId, threadId, runLongTask, undefined, {
  backgroundFunction: true,   // opt-in to the ~13min soft timeout
});

```

Setting `backgroundFunction: true` lifts the 40-second ceiling, allowing the worker to complete extensive operations within a Netlify background function or similar async execution environment.

## Summary

The Agent-Native runtime architecture from BuilderIO/agent-native delivers several critical capabilities:

- **Unified state management**: All actions, UI changes, and agent tool calls read and write the same SQL rows, eliminating synchronization complexities
- **Real-time collaboration**: SSE and poll-based reconnection via `subscribeFromSQL` enable multiple users to edit the same document simultaneously
- **Durable execution**: Background functions extend the run budget to approximately 13 minutes while maintaining foreground safety with 40-second soft timeouts
- **Exactly-one execution**: The grace period and atomic claiming mechanism in `resolveBackgroundDispatchOutcome` ensure runs complete precisely once, even when background workers fail

## Frequently Asked Questions

### How does the Agent-Native runtime handle long-running agent turns?

The runtime implements a durable background execution model where the Production Agent in [`packages/core/src/agent/production-agent.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/agent/production-agent.ts) can dispatch long-running work to background functions. When `backgroundFunction: true` is passed to `startRun`, the system extends the soft-timeout ceiling from 40 seconds to approximately 13 minutes (`BACKGROUND_SOFT_TIMEOUT_CEILING_MS`), allowing complex operations to complete without interruption.

### What happens if the background worker fails to claim a run?

The foreground handler implements a **Background-Aware Grace** mechanism through `resolveBackgroundDispatchOutcome` in [`packages/core/src/agent/run-manager.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/agent/run-manager.ts). It waits 15 seconds for the background worker to claim the run via `claimBackgroundRun`. If the worker never claims it, the foreground atomically reclaims the run and streams the turn inline, guaranteeing exactly-one execution regardless of background function availability.

### How does the SQL event log enable real-time collaboration?

The `agent_run_events` table in [`packages/core/src/agent/run-store.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/agent/run-store.ts) serves as the single source of truth for all execution events. Clients reconnect via `/runs/:id/events?after=N`, polling for events after a specific sequence number. Because all UI instances and the agent read from the same database rows, changes made by one user instantly propagate to others, creating a collaborative environment where both humans and AI models operate on synchronized state.

### What is the role of `defineAction` in the architecture?

The `defineAction` function in [`packages/core/src/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/action.ts) serves as the central registry for executable capabilities. It transforms Zod schemas into JSON-Schema for agent consumption while simultaneously exposing the same function as HTTP endpoints for UI integration. This design ensures that business logic remains consistent across all interfaces, whether invoked by a human clicking a button or an AI model calling a tool during its reasoning loop.