Getting Started

Agent-Native is an open-source TypeScript framework for building autonomous agents with intuitive UIs. You define each capability once as an action—a typed function the agent uses as a tool and the UI calls from code.

In this guide, you'll create an agent with a chat UI and call its included hello action from the agent and the UI.

Prerequisites

• Node.js 22.22 or later
• pnpm installed and available on your PATH
• An LLM connection for the agent: Builder.io, an Anthropic or OpenAI API key, or a local Ollama model

Create an agent

In a new directory, start from the Chat template:

npx --yes @agent-native/core@latest create my-app --standalone --template chat
cd my-app
pnpm install

The template gives your agent a browser UI, authentication, durable conversations, live sync, application context, and an actions/ directory. It also includes a small hello action that you'll use throughout this guide.

Start the development server

Start the development server:

pnpm dev

The browser UI opens automatically. If it does not, open the local URL printed by pnpm dev; the port increments when another app is already using 8080.

Connect an LLM

Next, connect an LLM. Select Connect Builder.io to use free credits, or select Custom keys, choose a provider, and enter the requested connection details.

Run the action from the agent

An action is a typed function that your React UI can call from code and agents can use as a tool. The Chat template includes a simple hello action so you can try the pattern before writing one yourself.

In the agent panel, ask:

Call the hello action for Alex.

The agent finds hello from its description and input schema, passes Alex as the name input, and responds:

Hello, Alex!

Inspect the action

In your local my-app directory, open actions/hello.ts in your code editor:

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

export default defineAction({
  description: "Return a friendly greeting.",
  schema: z.object({
    name: z.string().default("world").describe("Name to greet"),
  }),
  http: { method: "GET" },
  run: async ({ name }) => {
    return { message: `Hello, ${name}!` };
  },
});

For now, focus on four parts:

• description tells the agent when to use the action.
• schema validates the input and gives the agent a typed tool definition.
• http exposes this read-only action through GET, which lets useActionQuery call it from React.
• run contains the application logic shared by the agent and the UI.

Read Defining Actions for the complete API.

Call the action from React

The template includes actions/hello.ts, but not a page for it. Create app/routes/hello.tsx:

import { useActionQuery } from "@agent-native/core/client/hooks";
import { useState } from "react";

import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";

export default function HelloRoute() {
  const [name, setName] = useState("Alex");
  const { data } = useActionQuery("hello", { name });

  return (
    <main className="mx-auto grid w-full max-w-xl gap-6 p-6">
      <h1 className="text-2xl font-semibold">Hello action</h1>
      <div className="grid gap-2">
        <Label htmlFor="name">Name</Label>
        <Input
          id="name"
          value={name}
          onChange={(event) => setName(event.target.value)}
        />
      </div>
      <p className="text-xl font-medium">{data?.message}</p>
    </main>
  );
}

As you type a name, useActionQuery calls hello and renders the result. It infers the action's input and result types, so the page doesn't need a custom API route or a second implementation of the greeting.

Change the action

In actions/hello.ts, change the return value:

return { message: `Welcome, ${name}.` };

Refresh /hello, then ask the agent to call hello again. Both return the updated greeting because they call the same action.

Call actions in other ways

You called the same action from the agent and UI. The same action can also be called from:

Every caller uses the same action definition. You do not need a separate implementation for each one. This shared action model is central to Agent-Native: behavior, validation, and permissions stay aligned across the UI, agents, and integrations as you add capabilities.

What you built

You created an agent with a chat UI, called the same hello action from the agent and a React UI, then changed the greeting once and watched both update. Every action you write from here follows that same pattern.

Next steps