@21st-sdk/nextjs 0.0.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AN Dev (an.dev)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @an-sdk/nextjs
+
+Next.js integration for [AN](https://an.dev) AI agent chat. Provides a server-side token handler so your API key never reaches the client.
+
+## Install
+
+```bash
+npm install @an-sdk/nextjs @an-sdk/react ai @ai-sdk/react
+```
+
+## Quick Start
+
+### 1. Set your API key
+
+```env
+# .env.local
+AN_API_KEY=an_sk_your_key_here
+```
+
+Get your API key from [an.dev/agents/dashboard/api](https://an.dev/agents/dashboard/api).
+
+### 2. Create the token route (one line)
+
+```ts
+// app/api/an/token/route.ts
+import { createAnTokenHandler } from "@an-sdk/nextjs/server"
+
+export const POST = createAnTokenHandler({
+  apiKey: process.env.AN_API_KEY!,
+})
+```
+
+### 3. Use in your page
+
+```tsx
+// app/page.tsx
+"use client"
+
+import { useChat } from "@ai-sdk/react"
+import { AnAgentChat, createAnChat } from "@an-sdk/nextjs"
+import "@an-sdk/react/styles.css"
+import { useMemo } from "react"
+
+export default function Chat() {
+  const chat = useMemo(
+    () => createAnChat({
+      agent: "your-agent-slug",
+      tokenUrl: "/api/an/token",
+    }),
+    [],
+  )
+
+  const { messages, sendMessage, status, stop, error } = useChat({ chat })
+
+  return (
+    <AnAgentChat
+      messages={messages}
+      onSend={(msg) =>
+        sendMessage({ parts: [{ type: "text", text: msg.content }] })
+      }
+      status={status}
+      onStop={stop}
+      error={error}
+    />
+  )
+}
+```
+
+That's it. Your `an_sk_` API key stays on the server. The client only receives short-lived JWTs.
+
+## How It Works
+
+```
+Browser                     Your Next.js Server              AN Relay
+  |                                |                            |
+  |-- POST /api/an/token --------->|                            |
+  |                                |-- POST /v1/tokens -------->|
+  |                                |   (with an_sk_ key)        |
+  |                                |<-- { token, expiresAt } ---|
+  |<-- { token, expiresAt } ------|                            |
+  |                                                             |
+  |-- POST /v1/chat/:agent ------(with short-lived JWT)------->|
+  |<-- streaming response -----(SSE)---------------------------|
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,25 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+module.exports = __toCommonJS(src_exports);
+__reExport(src_exports, require("@21st-sdk/react"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("@21st-sdk/react")
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Re-export everything from @21st-sdk/react for convenience\nexport * from \"@21st-sdk/react\"\n"],"mappings":";;;;;;;;;;;;;;;;;AAAA;AAAA;AACA,wBAAc,4BADd;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1 @@
+export * from '@21st-sdk/react';

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from '@21st-sdk/react';

package/dist/index.js

@@ -0,0 +1,3 @@
+// src/index.ts
+export * from "@21st-sdk/react";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Re-export everything from @21st-sdk/react for convenience\nexport * from \"@21st-sdk/react\"\n"],"mappings":";AACA,cAAc;","names":[]}

package/dist/server.cjs

@@ -0,0 +1,71 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server.ts
+var server_exports = {};
+__export(server_exports, {
+  createAnTokenHandler: () => createAnTokenHandler,
+  exchangeToken: () => exchangeToken
+});
+module.exports = __toCommonJS(server_exports);
+async function exchangeToken(options) {
+  const {
+    apiKey,
+    relayUrl = "https://relay.an.dev",
+    expiresIn = "1h",
+    agent,
+    userId
+  } = options;
+  const res = await fetch(`${relayUrl}/v1/tokens`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify({
+      userId,
+      agents: agent ? [agent] : void 0,
+      expiresIn
+    })
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: "Failed to exchange token" }));
+    throw new Error(err.error || `Token exchange failed: ${res.status}`);
+  }
+  return res.json();
+}
+function createAnTokenHandler(options) {
+  return async function POST(req) {
+    try {
+      const body = await req.json().catch(() => ({}));
+      const { agent, userId } = body;
+      const data = await exchangeToken({ ...options, agent, userId });
+      return Response.json(data);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Internal error";
+      return Response.json({ error: message }, { status: 500 });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createAnTokenHandler,
+  exchangeToken
+});
+//# sourceMappingURL=server.cjs.map

package/dist/server.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["export interface TokenHandlerOptions {\n  /** Your an_sk_ API key — keep in process.env, never expose to client */\n  apiKey: string\n  /** Relay URL. Default: \"https://relay.an.dev\" */\n  relayUrl?: string\n  /** Token expiry. Default: \"1h\" */\n  expiresIn?: string\n}\n\nexport interface ExchangeTokenOptions extends TokenHandlerOptions {\n  /** Agent slug to scope the token to */\n  agent?: string\n  /** User identifier for the token */\n  userId?: string\n}\n\n/** Exchange an an_sk_ API key for a short-lived JWT via the relay */\nexport async function exchangeToken(options: ExchangeTokenOptions) {\n  const {\n    apiKey,\n    relayUrl = \"https://relay.an.dev\",\n    expiresIn = \"1h\",\n    agent,\n    userId,\n  } = options\n\n  const res = await fetch(`${relayUrl}/v1/tokens`, {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      Authorization: `Bearer ${apiKey}`,\n    },\n    body: JSON.stringify({\n      userId,\n      agents: agent ? [agent] : undefined,\n      expiresIn,\n    }),\n  })\n\n  if (!res.ok) {\n    const err = await res.json().catch(() => ({ error: \"Failed to exchange token\" }))\n    throw new Error(err.error || `Token exchange failed: ${res.status}`)\n  }\n\n  return res.json() as Promise<{ token: string; expiresAt: string }>\n}\n\n/** Create a Next.js API route handler that exchanges an_sk_ keys for JWTs */\nexport function createAnTokenHandler(options: TokenHandlerOptions) {\n  return async function POST(req: Request) {\n    try {\n      const body = await req.json().catch(() => ({}))\n      const { agent, userId } = body as { agent?: string; userId?: string }\n\n      const data = await exchangeToken({ ...options, agent, userId })\n      return Response.json(data)\n    } catch (err) {\n      const message = err instanceof Error ? err.message : \"Internal error\"\n      return Response.json({ error: message }, { status: 500 })\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiBA,eAAsB,cAAc,SAA+B;AACjE,QAAM;AAAA,IACJ;AAAA,IACA,WAAW;AAAA,IACX,YAAY;AAAA,IACZ;AAAA,IACA;AAAA,EACF,IAAI;AAEJ,QAAM,MAAM,MAAM,MAAM,GAAG,QAAQ,cAAc;AAAA,IAC/C,QAAQ;AAAA,IACR,SAAS;AAAA,MACP,gBAAgB;AAAA,MAChB,eAAe,UAAU,MAAM;AAAA,IACjC;AAAA,IACA,MAAM,KAAK,UAAU;AAAA,MACnB;AAAA,MACA,QAAQ,QAAQ,CAAC,KAAK,IAAI;AAAA,MAC1B;AAAA,IACF,CAAC;AAAA,EACH,CAAC;AAED,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,MAAM,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,EAAE,OAAO,2BAA2B,EAAE;AAChF,UAAM,IAAI,MAAM,IAAI,SAAS,0BAA0B,IAAI,MAAM,EAAE;AAAA,EACrE;AAEA,SAAO,IAAI,KAAK;AAClB;AAGO,SAAS,qBAAqB,SAA8B;AACjE,SAAO,eAAe,KAAK,KAAc;AACvC,QAAI;AACF,YAAM,OAAO,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,CAAC,EAAE;AAC9C,YAAM,EAAE,OAAO,OAAO,IAAI;AAE1B,YAAM,OAAO,MAAM,cAAc,EAAE,GAAG,SAAS,OAAO,OAAO,CAAC;AAC9D,aAAO,SAAS,KAAK,IAAI;AAAA,IAC3B,SAAS,KAAK;AACZ,YAAM,UAAU,eAAe,QAAQ,IAAI,UAAU;AACrD,aAAO,SAAS,KAAK,EAAE,OAAO,QAAQ,GAAG,EAAE,QAAQ,IAAI,CAAC;AAAA,IAC1D;AAAA,EACF;AACF;","names":[]}

package/dist/server.d.cts

@@ -0,0 +1,23 @@
+interface TokenHandlerOptions {
+    /** Your an_sk_ API key — keep in process.env, never expose to client */
+    apiKey: string;
+    /** Relay URL. Default: "https://relay.an.dev" */
+    relayUrl?: string;
+    /** Token expiry. Default: "1h" */
+    expiresIn?: string;
+}
+interface ExchangeTokenOptions extends TokenHandlerOptions {
+    /** Agent slug to scope the token to */
+    agent?: string;
+    /** User identifier for the token */
+    userId?: string;
+}
+/** Exchange an an_sk_ API key for a short-lived JWT via the relay */
+declare function exchangeToken(options: ExchangeTokenOptions): Promise<{
+    token: string;
+    expiresAt: string;
+}>;
+/** Create a Next.js API route handler that exchanges an_sk_ keys for JWTs */
+declare function createAnTokenHandler(options: TokenHandlerOptions): (req: Request) => Promise<Response>;
+
+export { type ExchangeTokenOptions, type TokenHandlerOptions, createAnTokenHandler, exchangeToken };

package/dist/server.d.ts

@@ -0,0 +1,23 @@
+interface TokenHandlerOptions {
+    /** Your an_sk_ API key — keep in process.env, never expose to client */
+    apiKey: string;
+    /** Relay URL. Default: "https://relay.an.dev" */
+    relayUrl?: string;
+    /** Token expiry. Default: "1h" */
+    expiresIn?: string;
+}
+interface ExchangeTokenOptions extends TokenHandlerOptions {
+    /** Agent slug to scope the token to */
+    agent?: string;
+    /** User identifier for the token */
+    userId?: string;
+}
+/** Exchange an an_sk_ API key for a short-lived JWT via the relay */
+declare function exchangeToken(options: ExchangeTokenOptions): Promise<{
+    token: string;
+    expiresAt: string;
+}>;
+/** Create a Next.js API route handler that exchanges an_sk_ keys for JWTs */
+declare function createAnTokenHandler(options: TokenHandlerOptions): (req: Request) => Promise<Response>;
+
+export { type ExchangeTokenOptions, type TokenHandlerOptions, createAnTokenHandler, exchangeToken };

package/dist/server.js

@@ -0,0 +1,45 @@
+// src/server.ts
+async function exchangeToken(options) {
+  const {
+    apiKey,
+    relayUrl = "https://relay.an.dev",
+    expiresIn = "1h",
+    agent,
+    userId
+  } = options;
+  const res = await fetch(`${relayUrl}/v1/tokens`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify({
+      userId,
+      agents: agent ? [agent] : void 0,
+      expiresIn
+    })
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: "Failed to exchange token" }));
+    throw new Error(err.error || `Token exchange failed: ${res.status}`);
+  }
+  return res.json();
+}
+function createAnTokenHandler(options) {
+  return async function POST(req) {
+    try {
+      const body = await req.json().catch(() => ({}));
+      const { agent, userId } = body;
+      const data = await exchangeToken({ ...options, agent, userId });
+      return Response.json(data);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Internal error";
+      return Response.json({ error: message }, { status: 500 });
+    }
+  };
+}
+export {
+  createAnTokenHandler,
+  exchangeToken
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["export interface TokenHandlerOptions {\n  /** Your an_sk_ API key — keep in process.env, never expose to client */\n  apiKey: string\n  /** Relay URL. Default: \"https://relay.an.dev\" */\n  relayUrl?: string\n  /** Token expiry. Default: \"1h\" */\n  expiresIn?: string\n}\n\nexport interface ExchangeTokenOptions extends TokenHandlerOptions {\n  /** Agent slug to scope the token to */\n  agent?: string\n  /** User identifier for the token */\n  userId?: string\n}\n\n/** Exchange an an_sk_ API key for a short-lived JWT via the relay */\nexport async function exchangeToken(options: ExchangeTokenOptions) {\n  const {\n    apiKey,\n    relayUrl = \"https://relay.an.dev\",\n    expiresIn = \"1h\",\n    agent,\n    userId,\n  } = options\n\n  const res = await fetch(`${relayUrl}/v1/tokens`, {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      Authorization: `Bearer ${apiKey}`,\n    },\n    body: JSON.stringify({\n      userId,\n      agents: agent ? [agent] : undefined,\n      expiresIn,\n    }),\n  })\n\n  if (!res.ok) {\n    const err = await res.json().catch(() => ({ error: \"Failed to exchange token\" }))\n    throw new Error(err.error || `Token exchange failed: ${res.status}`)\n  }\n\n  return res.json() as Promise<{ token: string; expiresAt: string }>\n}\n\n/** Create a Next.js API route handler that exchanges an_sk_ keys for JWTs */\nexport function createAnTokenHandler(options: TokenHandlerOptions) {\n  return async function POST(req: Request) {\n    try {\n      const body = await req.json().catch(() => ({}))\n      const { agent, userId } = body as { agent?: string; userId?: string }\n\n      const data = await exchangeToken({ ...options, agent, userId })\n      return Response.json(data)\n    } catch (err) {\n      const message = err instanceof Error ? err.message : \"Internal error\"\n      return Response.json({ error: message }, { status: 500 })\n    }\n  }\n}\n"],"mappings":";AAiBA,eAAsB,cAAc,SAA+B;AACjE,QAAM;AAAA,IACJ;AAAA,IACA,WAAW;AAAA,IACX,YAAY;AAAA,IACZ;AAAA,IACA;AAAA,EACF,IAAI;AAEJ,QAAM,MAAM,MAAM,MAAM,GAAG,QAAQ,cAAc;AAAA,IAC/C,QAAQ;AAAA,IACR,SAAS;AAAA,MACP,gBAAgB;AAAA,MAChB,eAAe,UAAU,MAAM;AAAA,IACjC;AAAA,IACA,MAAM,KAAK,UAAU;AAAA,MACnB;AAAA,MACA,QAAQ,QAAQ,CAAC,KAAK,IAAI;AAAA,MAC1B;AAAA,IACF,CAAC;AAAA,EACH,CAAC;AAED,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,MAAM,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,EAAE,OAAO,2BAA2B,EAAE;AAChF,UAAM,IAAI,MAAM,IAAI,SAAS,0BAA0B,IAAI,MAAM,EAAE;AAAA,EACrE;AAEA,SAAO,IAAI,KAAK;AAClB;AAGO,SAAS,qBAAqB,SAA8B;AACjE,SAAO,eAAe,KAAK,KAAc;AACvC,QAAI;AACF,YAAM,OAAO,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,CAAC,EAAE;AAC9C,YAAM,EAAE,OAAO,OAAO,IAAI;AAE1B,YAAM,OAAO,MAAM,cAAc,EAAE,GAAG,SAAS,OAAO,OAAO,CAAC;AAC9D,aAAO,SAAS,KAAK,IAAI;AAAA,IAC3B,SAAS,KAAK;AACZ,YAAM,UAAU,eAAe,QAAQ,IAAI,UAAU;AACrD,aAAO,SAAS,KAAK,EAAE,OAAO,QAAQ,GAAG,EAAE,QAAQ,IAAI,CAAC;AAAA,IAC1D;AAAA,EACF;AACF;","names":[]}

package/docs/01-overview.md

@@ -0,0 +1,61 @@
+# AN Platform Overview
+
+AN is a platform for building, deploying, and embedding AI agents. You define an agent in TypeScript, deploy it with one command, and embed a chat UI in any React app.
+
+## Architecture
+
+```
+Your Code (agent.ts)
+    |
+    v
+@an-sdk/cli deploy (CLI)
+    |
+    v
+AN Platform
+    |
+    +---> E2B Sandbox (isolated Node.js environment)
+    |         |
+    |         +---> Claude Agent SDK / Codex (executes your agent)
+    |         |
+    |         +---> Your custom tools run here
+    |
+    +---> AN Relay (relay.an.dev)
+              |
+              +---> SSE streaming to clients
+              |
+              +---> Token exchange (API key -> short-lived JWT)
+```
+
+## Packages
+
+| Package | Purpose |
+|---------|---------|
+| `@an-sdk/agent` | Define agents and tools with type inference |
+| `@an-sdk/cli` | Deploy agents from your terminal |
+| `@an-sdk/react` | Chat UI components (theming, tool renderers) |
+| `@an-sdk/nextjs` | Next.js server-side token handler |
+| `@an-sdk/node` | Server-side SDK (sandboxes, threads, tokens) |
+
+## Key Concepts
+
+- **Agent**: A TypeScript config defining model, system prompt, tools, and hooks. Runs in a cloud sandbox.
+- **Tool**: A function your agent can call, with a Zod schema for input validation and full type inference.
+- **Sandbox**: An isolated E2B cloud environment where your agent executes. Has Node.js, git, and system tools.
+- **Thread**: A conversation within a sandbox. One sandbox can have multiple threads.
+- **Relay**: The streaming gateway at `relay.an.dev`. Handles auth, routing, and SSE streaming.
+
+## Runtimes
+
+AN supports two runtimes:
+
+- **`claude-code`** (default) — Uses the Claude Agent SDK. Full tool use, file editing, bash execution.
+- **`codex`** — Uses OpenAI Codex via ACP provider.
+
+## Auth Model
+
+Two layers of authentication:
+
+1. **Client -> Relay**: API key (`an_sk_...`) or short-lived JWT (via token exchange)
+2. **Sandbox -> AI Provider**: Handled internally by the platform (Claude Proxy)
+
+For web apps, use `@an-sdk/nextjs` to exchange your API key for a short-lived JWT on the server, so the key never reaches the browser.

package/docs/02-getting-started.md

@@ -0,0 +1,110 @@
+# Getting Started
+
+## 1. Get an API Key
+
+Sign up at [an.dev](https://an.dev) and get your API key from [an.dev/agents/dashboard/api](https://an.dev/agents/dashboard/api).
+
+## 2. Install
+
+```bash
+npm install @an-sdk/agent zod
+```
+
+## 3. Define Your Agent
+
+Create `src/agent.ts`:
+
+```ts
+import { agent, tool } from "@an-sdk/agent"
+import { z } from "zod"
+
+export default agent({
+  model: "claude-sonnet-4-6",
+  systemPrompt: "You are a helpful coding assistant.",
+  tools: {
+    greet: tool({
+      description: "Greet a user by name",
+      inputSchema: z.object({ name: z.string() }),
+      execute: async ({ name }) => ({
+        content: [{ type: "text", text: `Hello, ${name}!` }],
+      }),
+    }),
+  },
+})
+```
+
+## 4. Login & Deploy
+
+```bash
+npx @an-sdk/cli login
+# Enter your API key: an_sk_...
+
+npx @an-sdk/cli deploy
+# Bundling src/agent.ts...
+# Deploying my-agent...
+# https://api.an.dev/v1/chat/my-agent
+```
+
+Your agent is live.
+
+## 5. Embed in a React App
+
+```bash
+npm install @an-sdk/nextjs @an-sdk/react ai @ai-sdk/react
+```
+
+Create a token route (keeps your API key on the server):
+
+```ts
+// app/api/an/token/route.ts
+import { createAnTokenHandler } from "@an-sdk/nextjs/server"
+
+export const POST = createAnTokenHandler({
+  apiKey: process.env.AN_API_KEY!,
+})
+```
+
+Add the chat UI:
+
+```tsx
+// app/page.tsx
+"use client"
+
+import { useChat } from "@ai-sdk/react"
+import { AnAgentChat, createAnChat } from "@an-sdk/nextjs"
+import "@an-sdk/react/styles.css"
+import { useMemo } from "react"
+
+export default function Chat() {
+  const chat = useMemo(
+    () => createAnChat({
+      agent: "your-agent-slug",
+      tokenUrl: "/api/an/token",
+    }),
+    [],
+  )
+
+  const { messages, sendMessage, status, stop, error } = useChat({ chat })
+
+  return (
+    <AnAgentChat
+      messages={messages}
+      onSend={(msg) =>
+        sendMessage({ parts: [{ type: "text", text: msg.content }] })
+      }
+      status={status}
+      onStop={stop}
+      error={error}
+    />
+  )
+}
+```
+
+## Next Steps
+
+- [Defining Agents](./03-defining-agents.md) — Models, tools, hooks, permissions
+- [React UI](./04-react-ui.md) — Theming, slots, tool renderers
+- [Next.js Integration](./05-nextjs.md) — Server-side token handler
+- [Node SDK](./06-node-sdk.md) — Sandboxes, threads, tokens from server code
+- [CLI Reference](./07-cli.md) — All CLI commands
+- [Custom Tools](./08-custom-tools.md) — Build custom tool renderers

package/docs/03-defining-agents.md

@@ -0,0 +1,159 @@
+# Defining Agents
+
+Agents are defined with the `agent()` and `tool()` functions from `@an-sdk/agent`. These are config-only — they return exactly what you pass in, with type inference added. The actual execution happens in the AN runtime (E2B sandbox).
+
+## `agent(config)`
+
+```ts
+import { agent } from "@an-sdk/agent"
+
+export default agent({
+  // Model (default: "claude-sonnet-4-6")
+  model: "claude-sonnet-4-6",
+
+  // System prompt
+  systemPrompt: "You are a PR reviewer...",
+
+  // Custom tools (see below)
+  tools: { /* ... */ },
+
+  // Runtime: "claude-code" (default) or "codex"
+  runtime: "claude-code",
+
+  // Permission mode: "default", "acceptEdits", or "bypassPermissions"
+  permissionMode: "default",
+
+  // Max conversation turns (default: 50)
+  maxTurns: 50,
+
+  // Max budget in USD
+  maxBudgetUsd: 5,
+
+  // Lifecycle hooks (see below)
+  onStart: async () => {},
+  onToolCall: async ({ toolName, input }) => {},
+  onToolResult: async ({ toolName, input, output }) => {},
+  onStepFinish: async ({ step }) => {},
+  onFinish: async ({ result }) => {},
+  onError: async ({ error }) => {},
+})
+```
+
+### Defaults
+
+| Field | Default |
+|-------|---------|
+| `model` | `"claude-sonnet-4-6"` |
+| `runtime` | `"claude-code"` |
+| `permissionMode` | `"default"` |
+| `maxTurns` | `50` |
+| `tools` | `{}` |
+
+## `tool(definition)`
+
+```ts
+import { tool } from "@an-sdk/agent"
+import { z } from "zod"
+
+const myTool = tool({
+  description: "What this tool does",
+  inputSchema: z.object({
+    path: z.string(),
+    verbose: z.boolean().optional(),
+  }),
+  execute: async (args) => {
+    // args is fully typed: { path: string; verbose?: boolean }
+    return {
+      content: [{ type: "text", text: "result" }],
+    }
+  },
+})
+```
+
+The `execute` function receives args typed from the Zod schema. Return value must have `content` array with `{ type: "text", text: string }` items.
+
+## Hooks
+
+### `onToolCall`
+
+Runs before a tool executes. Return `false` to block it.
+
+```ts
+onToolCall: async ({ toolName, input }) => {
+  if (toolName === "Bash" && input.command?.includes("rm -rf")) {
+    return false // blocked
+  }
+}
+```
+
+### `onToolResult`
+
+Runs after a tool executes with the result.
+
+```ts
+onToolResult: async ({ toolName, input, output }) => {
+  console.log(`Tool ${toolName} returned:`, output)
+}
+```
+
+### `onFinish`
+
+Runs when the agent completes successfully.
+
+```ts
+onFinish: async ({ result }) => {
+  await fetch("https://my-api.com/webhook", {
+    method: "POST",
+    body: JSON.stringify({ done: true }),
+  })
+}
+```
+
+### `onError`
+
+Runs when the agent encounters an error.
+
+```ts
+onError: async ({ error }) => {
+  console.error("Agent failed:", error)
+}
+```
+
+## Permission Modes
+
+| Mode | Behavior |
+|------|----------|
+| `"default"` | Agent asks for confirmation on risky operations |
+| `"acceptEdits"` | Auto-approve file edits, still confirm other actions |
+| `"bypassPermissions"` | Auto-approve everything (use with caution) |
+
+## Type Reference
+
+```ts
+// Agent config (all fields required — defaults filled by agent())
+interface AgentConfig {
+  model: string
+  systemPrompt: string
+  tools: ToolSet
+  runtime: "claude-code" | "codex"
+  permissionMode: "default" | "acceptEdits" | "bypassPermissions"
+  maxTurns: number
+  maxBudgetUsd?: number
+  onStart?: () => Promise<void>
+  onToolCall?: (payload: { toolName: string; input: any }) => Promise<boolean | void>
+  onToolResult?: (payload: { toolName: string; input: any; output: any }) => Promise<void>
+  onStepFinish?: (payload: { step: any }) => Promise<void>
+  onFinish?: (payload: { result: any }) => Promise<void>
+  onError?: (payload: { error: Error }) => Promise<void>
+}
+
+// Tool definition — generic over Zod schema
+interface ToolDefinition<TInput> {
+  description: string
+  inputSchema: ZodType<TInput>
+  execute: (args: TInput) => Promise<{ content: { type: string; text: string }[] }>
+}
+
+// Tool set
+type ToolSet = Record<string, ToolDefinition<any>>
+```