Next.js

Build a Better Agent app in Next.js App Router with a typed client, useAgent(...), durable conversations, approvals, client tools, and stream recovery.

Create the app

Start with a normal Better Agent server module.

src/better-agent/server.ts

import { betterAgent, defineAgent } from "@better-agent/core";
import { createOpenAI } from "@better-agent/providers/openai";

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const assistant = defineAgent({
  name: "assistant",
  model: openai.text("gpt-5-mini"),
  instruction: "You are a concise assistant. Keep replies short and natural.",
});

const app = betterAgent({
  agents: [assistant],
  baseURL: "/agents",
  secret: "dev-secret",
});

export default app;

Mount the route

Create a catch-all App Router route and forward the request to Better Agent.

src/app/agents/[...path]/route.ts

import app from "@/better-agent/server";

export const dynamic = "force-dynamic";

const handle = async (request: Request): Promise<Response> => {
  return app.handler(request);
};

export const GET = handle;
export const POST = handle;
export const PUT = handle;
export const PATCH = handle;
export const DELETE = handle;
export const OPTIONS = handle;
export const HEAD = handle;

Keep baseURL and the route path aligned. If the app uses baseURL: "/agents", the route should live under /agents.

Create the typed client

Import the server app type so agent names, context, tools, and output stay aligned.

src/better-agent/client.ts

import { createClient } from "@better-agent/client";
import type app from "./server";

export const client = createClient<typeof app>({
  baseURL: "/agents",
  secret: "dev-secret",
});

Build a basic chat

Start with the normal chat loop: messages, status, error, sendMessage, and stop.

src/app/page.tsx

"use client";

import { useState } from "react";
import { useAgent } from "@better-agent/client/react";
import { client } from "@/better-agent/client";

export default function Page() {
  const [input, setInput] = useState("");
  const { messages, status, error, sendMessage, stop } = useAgent(client, {
    agent: "assistant",
  });

  return (
    <div>
      <form
        onSubmit={async (event) => {
          event.preventDefault();
          const value = input.trim();
          if (!value) return;
          setInput("");
          await sendMessage(value);
        }}
      >
        <input
          value={input}
          onChange={(event) => setInput(event.target.value)}
          placeholder="Ask something..."
        />
        <button type="submit" disabled={status !== "ready"}>
          Send
        </button>
        <button
          type="button"
          onClick={() => stop()}
          disabled={status !== "submitted" && status !== "streaming"}
        >
          Stop
        </button>
      </form>

      <p>Status: {status}</p>
      {error && <p>{error.message}</p>}

      <ul>
        {messages.map((message) => (
          <li key={message.localId}>
            {message.role}: {message.parts.map((part) => part.type === "text" ? part.text : "").join("")}
          </li>
        ))}
      </ul>
    </div>
  );
}

Keep one conversation across refreshes

When you use server-managed persistence, give the chat a conversationId, hydrate the saved transcript, and resume the active stream on page load.

src/app/page.tsx

"use client";

import { useAgent } from "@better-agent/client/react";
import { client } from "@/better-agent/client";

export default function ChatPage() {
  const agent = useAgent(client, {
    agent: "assistant",
    conversationId: "support-demo",
    hydrateFromServer: true,
    resume: true,
  });

  return (
    <div>
      <p>Status: {agent.status}</p>
      <p>Conversation: {agent.conversationId}</p>
      <p>Messages: {agent.messages.length}</p>
    </div>
  );
}

Use resume: true when you want the hook to reconnect to the active conversation stream on init. Use resume: { streamId, afterSeq } when you already track a stream cursor yourself.

For resume: true, Better Agent needs persistence to find the active stream for a conversation. With only a StreamStore, use resume: { streamId }. Add runtime state to enable conversation-based resume. See Persistence.

Pass context and tune a run

Use hook options for stable per-chat defaults like context, modelOptions, and delivery.

src/app/billing/page.tsx

"use client";

import { useAgent } from "@better-agent/client/react";
import { client } from "@/better-agent/client";

export default function BillingPage() {
  const agent = useAgent(client, {
    agent: "assistant",
    context: {
      userId: "user_123",
      plan: "pro",
    },
    modelOptions: {
      reasoningEffort: "medium",
    },
    delivery: "stream",
  });

  return <button onClick={() => agent.sendMessage("Summarize my plan.")}>Ask</button>;
}

Add browser-side tools

src/app/tools/page.tsx

"use client";

import { useAgent } from "@better-agent/client/react";
import { client } from "@/better-agent/client";

export default function ToolsPage() {
  const agent = useAgent(client, {
    agent: "assistant",
    toolHandlers: {
      show_confetti: async ({ color }) => {
        console.log("Confetti color:", color);
        return { shown: true };
      },
    },
  });

  return <button onClick={() => agent.sendMessage("Celebrate the upgrade.")}>Run</button>;
}

Use onToolCall instead when you want one per-run function instead of a handler map.

Handle approvals in the UI

When a tool needs human approval, useAgent(...) exposes pending requests and a helper to answer them.

src/app/approvals/page.tsx

"use client";

import { useAgent } from "@better-agent/client/react";
import { client } from "@/better-agent/client";

export default function ApprovalsPage() {
  const { pendingToolApprovals, approveToolCall } = useAgent(client, {
    agent: "assistant",
  });

  return (
    <div>
      {pendingToolApprovals.map((approval) => (
        <div key={approval.toolCallId}>
          <div>{approval.toolName}</div>
          <pre>{JSON.stringify(approval.meta, null, 2)}</pre>

          <button
            onClick={() =>
              approveToolCall({
                toolCallId: approval.toolCallId,
                decision: "approved",
              })
            }
          >
            Approve
          </button>

          <button
            onClick={() =>
              approveToolCall({
                toolCallId: approval.toolCallId,
                decision: "denied",
              })
            }
          >
            Deny
          </button>
        </div>
      ))}
    </div>
  );
}

Watch events and final results

Use callbacks when you want analytics, data parts, disconnect handling, or typed final output.

src/app/observability/page.tsx

"use client";

import { useAgent } from "@better-agent/client/react";
import { client } from "@/better-agent/client";

export default function ObservabilityPage() {
  useAgent(client, {
    agent: "assistant",
    onResponse: (response) => {
      console.log("HTTP status", response.status);
    },
    onEvent: (event) => {
      console.log("Event", event.type);
    },
    onData: (part) => {
      console.log("Data part", part.data);
    },
    onDisconnect: ({ error, streamId }) => {
      console.error("Stream disconnected", streamId, error);
    },
    onError: (error) => {
      console.error("Run failed", error);
    },
    onFinish: ({ finishReason, response }) => {
      console.log("Finished", finishReason);
      console.log(response?.output);
    },
  });

  return null;
}

If your agent has a default outputSchema, onFinish also receives typed structured output.

Shape local replay

Use these options when you want to control how local message history is turned back into model input.

src/app/local-state/page.tsx

"use client";

import { useAgent } from "@better-agent/client/react";
import { client } from "@/better-agent/client";

export default function LocalStatePage() {
  const agent = useAgent(client, {
    agent: "assistant",
    initialMessages: [
      {
        role: "assistant",
        parts: [{ type: "text", text: "Welcome back." }],
      },
    ],
    prepareMessages: ({ messages, input }) => {
      return [
        {
          type: "message",
          role: "system",
          content: `Reuse the important context from the last ${messages.length} local messages.`,
        },
        { type: "message", role: "user", content: [{ type: "text", text: String(input) }] },
      ];
    },
  });

  return (
    <div>
      <button onClick={() => agent.regenerate()}>Regenerate last turn</button>
      <button
        onClick={() =>
          agent.setMessages((messages) => messages.filter((message) => message.role !== "assistant"))
        }
      >
        Hide assistant messages
      </button>
    </div>
  );
}

Use retryMessage(localId) when you want to rerun one earlier user turn, and resumeStream(...) or resumeConversation(...) when you want to reconnect manually instead of using resume on init.

Optimistic UI

Use optimistic insertion when you want the user message to appear in the chat before the request finishes.

src/app/optimistic/page.tsx

"use client";

import { useAgent } from "@better-agent/client/react";
import { client } from "@/better-agent/client";

export default function OptimisticPage() {
  const agent = useAgent(client, {
    agent: "assistant",
    optimisticUserMessage: {
      enabled: true,
      onError: "remove",
    },
    onOptimisticUserMessageError: ({ error }) => {
      console.error("Optimistic message failed", error);
    },
  });

  return (
    <div>
      <button onClick={() => agent.clearError()}>Clear error</button>
      <button onClick={() => agent.reset()}>Reset chat</button>
    </div>
  );
}

Next.js

On this page