Common Use Cases for Agent-Native: Building Agent-First Applications with Shared State

Agent-Native is a framework for building agent-first applications where AI agents share the same data, actions, and UI as human users, making it ideal for SaaS products, internal tools, chat apps, and self-improving systems.

Agent-Native is an open-source framework from BuilderIO/agent-native that treats AI agents as first-class citizens of your application. Unlike traditional architectures where AI is bolted on as an afterthought, Agent-Native ensures your agents access the same actions, database state, and UI components as human users. This design pattern enables several distinct common use cases for agent-native development, from rapid template-driven prototyping to autonomous, self-improving systems.

SaaS Products with AI-Augmented Features

The most common use case for agent-native development is building SaaS applications where AI augments existing workflows. Email assistants, calendar schedulers, content editors, slide creators, and analytics dashboards all benefit from the framework's unified action layer.

In README.md (lines 7‑18), the framework demonstrates how actions are defined once and callable from multiple surfaces:

// Actions are defined with Zod validation and business logic
export const createTask = defineAction({
  input: z.object({ title: z.string(), dueDate: z.date() }),
  handler: async ({ title, dueDate }) => {
    // Insert into shared SQL database
    return await db.insert(tasks).values({ title, dueDate });
  }
});

This single definition in packages/frame/src/server.ts registers the action for use by the UI, the agent, HTTP endpoints, or CLI commands. This ensures a single source of truth for business logic across all interfaces.

Template-Driven Rapid Application Development

Agent-Native ships with fully-featured templates that accelerate development for specific verticals. According to README.md (lines 44‑107), available templates include Calendar, Content, Slides, Analytics, and Clips.

Each template provides:

• Pre-wired database schemas and authentication
• Ready-made action definitions for CRUD operations
• UI components that connect to the shared SQL state
• Agent skills configured for the domain

When you scaffold a new app from a template, the agent can immediately read and write the same application_state that the UI uses, eliminating integration overhead.

Internal Tools and Collaborative Dashboards

Data-driven internal tools represent a core use case where humans and AI agents collaborate in real-time. The framework's shared SQL state (application_state) and real-time sync capabilities allow both the agent and the user to see updates instantly.

As documented in README.md (lines 24‑34), the "Agents and UIs, Fully Connected" architecture enables collaborative scenarios such as:

• Exploring datasets together with the agent suggesting filters
• Generating charts where the agent writes the query and the user refines visualization
• Writing reports where both parties edit the same document state

Chat and Headless-Only Applications

For teams building minimal interfaces or API-first services, Agent-Native supports Chat and Headless scaffolding modes. The create command generates either a minimal chat-box UI with the agent pre-wired, or a pure headless application with actions exposed via API but no frontend.

From README.md (lines 33‑41), quick-start commands include:

# Scaffold a chat-first app

npx create-agent-native@latest my-app --template chat

# Scaffold a headless API service

npx create-agent-native@latest my-app --template headless

These patterns suit conversational interfaces, Slack bots, or microservices where an AI agent is the primary consumer of your API.

Extending Existing Apps with Agent Capabilities

Agent-Native supports incremental adoption, allowing you to add AI capabilities to existing products without rewriting the entire frontend. By exposing actions via hooks like useActionMutation, any existing React component can invoke agent-backed functions.

The bidirectional connectivity described in README.md (lines 24‑34) means the agent can also call back into the UI through the same action surface. This enables "agent-Augmented" features in legacy applications where the AI and user take turns manipulating the same state.

Agent-to-Agent (A2A) Orchestration

Complex workflows often require multiple specialized agents working together. Agent-Native supports Agent-to-Agent (A2A) orchestration where agents invoke each other through the shared action surface.

As noted in README.md (line 33), the "Agents call agents" capability enables composable pipelines. For example:

1. A Planner agent drafts a project structure
2. A Coder agent generates implementation files
3. A Reviewer agent checks for bugs
4. A Deployer agent pushes to production

Each agent acts as a peer, calling the same actions that human users would trigger from the UI.

Self-Improving Applications

Perhaps the most advanced use case involves self-improving applications where agents modify their own codebase. Since actions, UI, and agent runtime share the same repository, agents can programmatically update source files via the skills system.

Documented in README.md (line 34), this capability allows agents to:

• Add new features by writing action definitions
• Fix bugs by editing handler functions
• Refine UI components based on user feedback

Changes made via the skills system in templates/*/.agents/skills/*/SKILL.md are immediately reflected in the running application, creating a feedback loop where the product improves itself.

Code Examples: Actions in Practice

To implement these use cases, you define actions using the core utilities from packages/frame/src/server.ts. Here is a complete pattern showing definition, UI invocation, and agent triggering:

Define the action (as shown in README.md lines 7‑18):

import { defineAction } from '@agent-native/core';
import { z } from 'zod';

export const generateReport = defineAction({
  input: z.object({ 
    startDate: z.date(), 
    endDate: z.date() 
  }),
  handler: async ({ startDate, endDate }) => {
    const data = await db.query.analytics.findMany({
      where: between(analytics.date, startDate, endDate)
    });
    return aggregateData(data);
  }
});

Call from the UI using the shared mutation hook:

import { useActionMutation } from '@agent-native/frame';

function AnalyticsDashboard() {
  const generateReport = useActionMutation('generateReport');
  
  return (
    <Button onClick={() => generateReport.mutate({ 
      startDate: new Date(), 
      endDate: new Date() 
    })}>
      Generate Report
    </Button>
  );
}

Trigger the agent from the same UI (see packages/frame/src/oauth-state.ts for frame integration):

import { AgentComposerFrame } from '@agent-native/frame';

function App() {
  return (
    <div>
      <AgentComposerFrame />
      <AnalyticsDashboard />
    </div>
  );
}

Summary

• Agent-Native enables building applications where AI agents share the same actions, database, and UI as human users.
• SaaS augmentation benefits from unified action definitions that work across UI, API, and agent contexts.
• Template-driven development accelerates creation of calendar, content, slide, and analytics apps with pre-wired agent capabilities.
• Internal tools leverage real-time shared SQL state (application_state) for human-AI collaboration.
• Chat and headless modes support minimal UI or pure API-first architectures.
• A2A orchestration allows multiple specialized agents to compose complex workflows through the same action surface.
• Self-improving apps can modify their own source code via the skills system, with changes immediately reflected in the running application.

Frequently Asked Questions

What is Agent-Native?

Agent-Native is an open-source framework from BuilderIO that treats AI agents as first-class citizens of web applications. Unlike traditional AI integrations that rely on separate APIs, Agent-Native stores application state in a shared SQL database (application_state) and defines actions that are callable from both the UI and the agent, ensuring perfect synchronization between human and AI interactions.

How does Agent-Native differ from traditional AI integration?

Traditional approaches typically bolt AI onto existing apps via external API calls, creating data silos between the AI and the UI. Agent-Native inverts this model by making the agent a core participant in the application architecture. As implemented in packages/frame/src/server.ts, actions are defined once and registered for use by humans, agents, HTTP endpoints, and CLI tools simultaneously, eliminating the need to sync state between separate systems.

Can Agent-Native work with existing codebases?

Yes. Agent-Native supports incremental adoption through its useAction hooks and AgentComposerFrame component. You can expose existing business logic as actions and mount the agent composer in specific parts of your application. The framework's bidirectional connectivity (described in README.md lines 24‑34) allows the agent to call back into existing UI components without requiring a full rewrite.

What templates are available in Agent-Native?

According to the repository documentation (README.md lines 44‑107), Agent-Native provides templates for Calendar, Content, Slides, Analytics, and Clips (screen recording). Each template includes pre-configured database schemas, authentication, UI components, and agent skills specific to the domain, allowing you to scaffold a production-ready application in minutes rather than weeks.

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