betteragent-react

npm i betteragent-react

ESM only. This package ships no CommonJS build — it renders React components and is always consumed through a bundler. require() will fail. If you need to import BetterAgent from a CJS script (a tsx one-off, Jest without ESM configured, a build script), use betteragent-next, which ships both formats.

Quick start

The recommended way to use the provider is via the AgentProvider component generated by betteragent init. It wires server actions internally so your layout stays clean:

// app/(dashboard)/layout.tsx — Server Component
import { cookies } from "next/headers";
import { AgentProvider } from "@/components/betteragent-provider";

export default async function Layout({ children }) {
  const user = await requireUser();
  const sessionToken = (await cookies()).get("session")?.value;

  return (
    <AgentProvider
      clientKey={process.env.NEXT_PUBLIC_BETTERAGENT_CLIENT_KEY!}
      apiUrl={process.env.NEXT_PUBLIC_BETTERAGENT_API_URL}
      endUserId={user.id}
      authToken={{ Authorization: `Bearer ${sessionToken}` }}
    >
      {children}
    </AgentProvider>
  );
}

authToken

Forwarded to your route tools so they can authenticate requests as the logged-in user. Accepts three forms:

// String → Authorization: Bearer <token>
authToken={token}

// Object → forwarded verbatim (any header name/format)
authToken={{ Authorization: `Bearer ${sessionToken}` }}
authToken={{ "X-Api-Key": apiKey }}

// Function (Client Component only — cannot be passed from a Server Component)
authToken={() => getToken()}
authToken={async () => ({ Authorization: `Bearer ${await getToken()}` })}

Using BetterAgentProvider directly

If you need manual control, wire the provider yourself. Because Next.js strips custom properties from server action references at the server/client boundary, you must call buildServerActionMap in a Server Component before passing actions to BetterAgentProvider:

// components/my-provider.tsx  — Server Component (no "use client")
import { buildServerActionMap } from "betteragent-next";
import { BetterAgentProvider } from "betteragent-react";
import * as serverActions from "@/server-actions.betteragent";

export function MyProvider({ children, ...props }) {
  return (
    <BetterAgentProvider
      {...props}
      serverActions={buildServerActionMap(serverActions)}
    >
      {children}
    </BetterAgentProvider>
  );
}

buildServerActionMap reads the name field from each defineServerAction result and returns a { [toolName]: handler } map. This must happen server-side while the metadata symbols are still present.

useChatStream

"use client";

import { useChatStream } from "betteragent-react";

export function Chat() {
  const { messages, send, isStreaming } = useChatStream();

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          <b>{m.role}</b>: {m.content}
        </div>
      ))}
      <button disabled={isStreaming} onClick={() => send("Hello!")}>
        Send
      </button>
    </div>
  );
}

What the SDK does NOT do

It does not render chat UI. Run npx betteragent add <variant> to install one of the registry components (sidebar, chat-popup, cmd-k, inline-bar) into your project. They're shadcn-style — copied into your codebase, fully editable.