Agent-Native Limitations: 7 Critical Constraints Developers Must Know

Agent-native requires additive-only database migrations, supports only single-author real-time editing, and mandates TypeScript for all SDK interactions.

Agent-native is a framework that enables AI agents and UI components to share a unified data and action surface within the BuilderIO ecosystem. While the BuilderIO/agent-native repository provides powerful abstractions for building agent-driven applications, it imposes specific architectural constraints that affect collaboration patterns, data modeling, and production deployment strategies.

Real-Time Collaboration Constraints

The framework's real-time collaboration features are currently limited to basic synchronization without sophisticated conflict resolution mechanisms.

Single-Author Editing Only

As documented in packages/core/src/templates/workspace-core/.agents/skills/real-time-collab/SKILL.md, the v1 implementation supports only single-author editing. If multiple users attempt to edit a document simultaneously, the system does not merge changes automatically, resulting in conflicts or stale data. The useRealtimeCollab hook expects a single active writer per document.

No Built-in CRDT or OT Engine

Unlike dedicated collaboration platforms, agent-native lacks a conflict-free replicated data type (CRDT) or operational-transform (OT) layer. This means concurrent edits will overwrite each other rather than being intelligently merged, making the framework unsuitable for Google Docs-style multi-user editing without additional infrastructure.

Agent-Driven UI Boundaries

The UI layer operates under strict constraints regarding how it can invoke logic and what components it can render.

Actions-Only Invocation Pattern

According to the four-area checklist in AGENTS.md, the UI can only invoke behavior exposed through the actions/ surface. There is no "raw fetch" shortcut for custom endpoints; every interaction must be wrapped as a defined action. This enforces strict boundaries between the agent and UI but adds boilerplate for simple HTTP requests.

UI Primitive Restrictions

The framework enforces the use of shadcn/ui primitives and Tabler icons. Creating bespoke UI widgets requires manual integration and may break optimistic UI updates managed by the agent. Custom components must conform to the existing design system or risk incompatible state management.

Data Persistence and Schema Limitations

Data management follows strict SQL-centric rules that limit flexibility in schema evolution.

Additive-Only Schema Migrations

Per the data-lives-in-SQL contract in AGENTS.md, migrations must be additive only. You cannot drop, rename, or truncate columns without violating the architecture contract. Schema changes require creating new columns rather than altering existing ones, which can lead to data duplication over time.

SQL-First Architecture Requirements

All application state lives in a Drizzle-managed SQL database. While local-file mode exists, features like real-time sync and multi-tenant access filters assume a relational store. This constraint eliminates NoSQL or serverless database options for production deployments.

Security and Secrets Management

Hardcoded credentials are explicitly forbidden by the framework's security model.

Manual Secret Configuration

The framework never auto-injects API keys or tokens. Third-party integrations must expose credentials via Builder Vault or .env placeholders. CI lint rules will reject any commits containing secrets in source files, enforcing external secret management.

Extensibility and Language Support

Plugin architecture and language bindings impose build-time and TypeScript constraints.

Static Plugin Discovery

Plugins are discovered at build time only, as noted in the core documentation. Dynamically loading plugins at runtime is unsupported; you must add the plugin to the codebase and rebuild the application. This prevents hot-swapping functionality in production environments.

TypeScript-Only SDK

The current SDK is TypeScript-only. Using agent-native from Python, Go, or other languages requires writing a custom bridge layer. All action definitions, hooks, and components must be implemented in TypeScript.

Performance and Scaling Bottlenecks

Production scaling requires careful architecture due to process and memory constraints.

Single-Process Nitro Server

The Nitro API runs as a single Node process. High-throughput workloads require horizontal scaling via load-balanced deployments, which the framework does not handle automatically. See packages/core/docs/content/deployment.md for recommended scaling patterns.

Memory-Intensive Real-Time Sync

The useDbSync() polling mechanism stores a full snapshot of relevant rows in memory per client. For large datasets, this creates significant memory pressure on the server, potentially requiring vertical scaling or pagination workarounds.

Documentation and API Stability

Rapid evolution affects long-term maintenance.

Rapidly Evolving Public API

The public API surface—including actions, skills, and templates—changes frequently. Developers must monitor packages/core/CHANGELOG.md closely, as breaking changes occur without extended deprecation periods.

Code Examples Illustrating Key Limitations

The following examples demonstrate how these constraints manifest in actual implementation.

Defining Actions with Additive Schemas

// packages/core/src/actions/userProfile.ts
import { defineAction } from '@/actions';
import { z } from 'zod';

export const getUserProfile = defineAction({
  input: z.object({ userId: z.string() }),
  // LIMITATION: Schema must be additive only
  // Cannot remove 'legacyField' without creating new action version
  output: z.object({
    id: z.string(),
    name: z.string(),
    legacyField: z.string(), // Must keep for backward compatibility
    newField: z.string().optional(), // Additions only
  }),
  async handler({ input }) {
    return await db.select().from(users).where(eq(users.id, input.userId));
  },
});

Implementing Single-Author Real-Time Collaboration

import { useRealtimeCollab } from '@/hooks';

export function DocumentEditor({ docId }: { docId: string }) {
  const { state, sendEdit } = useRealtimeCollab(docId);
  
  // LIMITATION: Only one author can edit at a time
  // Concurrent edits will cause conflicts or data loss
  return (
    <textarea
      value={state.content}
      onChange={(e) => sendEdit(e.target.value)}
    />
  );
}

Working Within UI Primitive Constraints

import { Button } from '@/components/ui/button';
// LIMITATION: Must use shadcn/ui primitives
// Custom components require manual agent integration

export function CustomActionButton() {
  return (
    <Button
      onClick={async () => {
        // All UI interactions must go through actions surface
        await invokeAction('custom/action');
      }}
    >
      Execute Action
    </Button>
  );
}

Summary

• Single-author editing: Real-time collaboration supports only one writer per document without CRDT/OT merge capabilities.
• Additive migrations: Database schemas can only grow; dropping or renaming columns violates the architecture contract.
• Actions-only pattern: UI cannot perform raw HTTP requests; all logic must be wrapped in defined actions.
• TypeScript exclusivity: The SDK supports no other languages natively; polyglot usage requires custom bridges.
• Build-time plugins: Runtime plugin loading is impossible; all extensions require rebuilds.
• Memory-intensive sync: Real-time database synchronization stores full row snapshots in memory per client.
• Single-process server: The Nitro backend requires external load balancing for horizontal scaling.

Frequently Asked Questions

Can multiple users edit documents simultaneously in agent-native?

No. The v1 real-time collaboration implementation in packages/core/src/templates/workspace-core/.agents/skills/real-time-collab/SKILL.md explicitly supports single-author editing only. Concurrent edits will not be merged and may result in conflicts or data loss, as the framework lacks CRDT or OT engines.

How do I handle schema changes that require dropping or renaming columns?

You cannot drop or rename columns directly. Per the data-lives-in-SQL contract in AGENTS.md, all schema migrations must be additive. Create new columns with desired changes and deprecate old fields gradually, or write migration scripts that preserve the additive-only policy while duplicating data temporarily.

Is agent-native suitable for high-throughput production workloads?

Only with external scaling. The Nitro server runs as a single Node process, and useDbSync() maintains row snapshots in memory per client. High-throughput scenarios require load-balanced deployments and careful memory management, as documented in packages/core/docs/content/deployment.md.

Can I use Python or other languages with the agent-native SDK?

No. The current SDK is TypeScript-only. Using Python, Go, or other languages requires building a custom bridge that communicates with the TypeScript actions surface, as the framework provides no native bindings for other languages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}