Set up BetterAgent with your AI IDE

# BetterAgent Setup Prompt
 
You are helping a developer add BetterAgent to their Next.js project.
BetterAgent gives the app an AI assistant that can call routes, server
actions, and trigger client-side effects — no extra backend required.
 
---
 
## Step 1: Install packages
 
npm install -D betteragent-cli
npm install betteragent-react betteragent-next
 
## Step 2: Authenticate
 
Ask the user for their BetterAgent secret key (format: ba_secret_...).
They can find it in the dashboard under project settings. Then run:
 
  npx betteragent login --key <secret-key>
 
## Step 3: Initialize
 
Run the setup wizard. It will prompt for a chat component variant.
Sidebar is a good default for most apps.
 
  npx betteragent init
 
This generates:
- Tool files (routes.betteragent.ts, server-actions.betteragent.ts, actions.betteragent.ts)
- components/betteragent-provider.tsx — a ready-to-use <AgentProvider> wrapper
- Adds NEXT_PUBLIC_BETTERAGENT_CLIENT_KEY to .env.local
 
## Step 4: Discover tools
 
Scan the project for existing Next.js routes and server actions:
 
  npx betteragent discover
 
Review the generated files and remove any routes the agent should not
access (admin-only endpoints, internal APIs, etc.).
 
## Step 5: Sync
 
Push the tool definitions to the BetterAgent backend:
 
  npx betteragent sync
 
## Step 6: Add the provider
 
Import the generated AgentProvider (in components/betteragent-provider.tsx)
and wrap children with it in the dashboard or root layout.
 
Replace endUserId with the authenticated user's real ID from your auth system.
 
If the agent exposes route tools that read or write per-user data, pass
authToken so the engine can authenticate requests to your backend on behalf
of the logged-in user:
 
  - String: forwarded as Authorization: Bearer <token>
  - Object: forwarded verbatim — use this when your backend expects a
    specific header format or non-Bearer scheme:
      authToken={{ Authorization: `Bearer ${sessionToken}` }}
      authToken={{ "X-Api-Key": apiKey }}
  - Function (Client Component only): called per-request for refreshed tokens
 
For session-cookie-based auth (e.g. iron-session, custom cookies), read
the cookie server-side and pass it as an object:
 
  import { cookies } from "next/headers";
  const sessionToken = (await cookies()).get("session")?.value;
 
  <AgentProvider
    ...
    authToken={{ Authorization: `Bearer ${sessionToken}` }}
  >
 
Your route handlers must accept this header to authenticate agent requests.
Browser requests using cookies are unaffected — only agent calls use the header.
 
Full layout example:
 
  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>
    );
  }
 
Also import and render the chat component that betteragent init installed.
The provider supplies context but renders no UI on its own. For the sidebar
variant, add it alongside your main content:
 
  import { ChatSidebar } from "@/components/chat/sidebar";
 
  <div className="flex h-screen">
    <main className="flex-1 overflow-y-auto">{children}</main>
    <ChatSidebar title="Assistant" greeting="Hi — how can I help?" />
  </div>
 
---
 
## Tool file reference (for manual edits after discovery)
 
Tool files teach the agent what it can do. Three file types:
 
### routes.betteragent.ts — HTTP routes called server-to-server
 
  import { defineRoute } from "betteragent-next";
  import { z } from "zod";
 
  export const getUser = defineRoute({
    name: "getUser",
    method: "GET",
    path: "/api/user",
    description: "Get the current authenticated user's profile. Use when " +
      "the user asks about their account or profile details.",
    schema: z.object({}),
  });
 
  export const routes = [getUser];
 
### server-actions.betteragent.ts — Next.js Server Actions
 
This file has "use server" at the top. Handlers must be imported from your
own "use server" files — do not define them inline. Export each action
individually; do not export an array. The generated AgentProvider imports
this file automatically.
 
  "use server";
 
  import { defineServerAction } from "betteragent-next";
  import { z } from "zod";
  import { updateProfile } from "@/app/actions/profile";
 
  export const updateUserProfile = defineServerAction({
    name: "updateUserProfile",
    description: "Update the user's display name and bio. Only call after " +
      "they explicitly ask to change their name.",
    schema: z.object({
      name: z.string().min(1).max(100),
      bio:  z.string().max(500).optional(),
    }),
    handler: updateProfile,
  });
 
### actions.betteragent.ts — Browser-side effects
 
  import { defineAction } from "betteragent-next";
  import { z } from "zod";
 
  export const openModal = defineAction({
    name: "openModal",
    description: "Open a modal or dialog. Use when the user asks to see or " +
      "edit something in a dialog.",
    schema: z.object({
      name: z.enum(["settings", "profile", "billing"]),
    }),
  });
 
  export const actions = [openModal];
 
Register client actions in AgentProvider via the actions prop (add it to
the generated components/betteragent-provider.tsx):
 
  <BetterAgentProvider
    ...
    actions={{
      openModal: ({ name }) => setOpenDialog(name),
    }}
  >
 
---
 
## Key facts
 
- Credits: 2 per conversation start · 1 per message · 3 per tool call
- Free plan: 500 credits/30-day period, no card required
- Run betteragent sync whenever tool files change
- Better descriptions = better agent decisions
  Describe *when* to use a tool, not just *what* it does
- Docs:          https://docs.betteragent.dev
- CLI reference: https://docs.betteragent.dev/cli
- Tool files:    https://docs.betteragent.dev/tools