Quickstart

Requirements

@ag2b/core
react >= 18
zod ^3.25.0 || ^4.0.0

Always import from zod/v4

The zod/v4 works on both zod@^3.25.0 (where v4 ships as a subpath) and zod@^4.0.0 (where it's equivalent to zod). Mirror this in your code so it stays portable across the range.

Getting started

Installation

npm i @ag2b/react @ag2b/core zod

Writing your first agent

Create the agent

Construct an Agent with a Provider.

agent.ts

import { Agent, OpenAiProvider } from '@ag2b/core';

export const agent = new Agent({
  provider: new OpenAiProvider({ baseURL: '/api/llm' }),
});

Connect a Tool

Build a Tool and pair with Scope to expose it to the agent.

appearance.tsx

import { useAg2bScope, useAg2bTool } from '@ag2b/react';
import { z } from 'zod/v4';

export function Appearance() {
  const setBackground = useAg2bTool({
    name: 'setBackground',
    description: 'Change the page background color.',
    parameters: z.object({
      color: z.string().describe('Any valid CSS color (name, hex, rgb, etc.)'),
    }),
    handler: ({ color }) => {
      document.body.style.backgroundColor = color;
    },
  });

  useAg2bScope({ name: 'appearance', tools: [setBackground] });

  return null;
}

Add a chat UI

Create a control that sends prompts and shows the reply.

chat.tsx

import { useAg2bChat } from '@ag2b/react';

export function Chat() {
  const { send, response, isPending } = useAg2bChat();

  return (
    <button
      disabled={isPending}
      onClick={() => send('Make the page feel like a sunset, use oklch.')}
    >
      {response?.content ?? (isPending ? 'thinking…' : 'Vibes please')}
    </button>
  );
}

Wire it together

Wrap yor components in <Ag2bProvider> so every hook reaches the agent.

App.tsx

import { Ag2bProvider } from '@ag2b/react';

import { agent } from './agent';
import { Appearance } from './appearance';
import { Chat } from './chat';

export function App() {
  return (
    <Ag2bProvider agent={agent}>
      <Appearance />
      <Chat />
    </Ag2bProvider>
  );
}

The LLM interprets the prompt, picks a color, calls setBackground — the page background changes.

Quickstart

On this page