> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recursiv.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recursiv.io/_mcp/server.

# Connect Next.js

The `@recursiv/sdk` is a zero-dependency TypeScript SDK that runs in Server Components, API routes, and Client Components. This guide gets a Next.js app from install to a streaming agent.

## Install

```bash
npm install @recursiv/sdk
```

## Configure the key

No account yet? [Sign up](https://recursiv.io/register) and mint a key at [recursiv.io/account/api-keys](https://recursiv.io/account/api-keys).

Keep the key server side. Put it in `.env.local`:

```bash
RECURSIV_API_KEY=sk_live_...
```

The SDK reads `RECURSIV_API_KEY` automatically, so on the server you can just do `new Recursiv()`. You can also pass the key explicitly:

```typescript
import { Recursiv } from '@recursiv/sdk';

const r = new Recursiv({ apiKey: process.env.RECURSIV_API_KEY });
```

## First authenticated call

Most resources hang off a project. Create one, then run a query. Project IDs are UUIDs, so always use the `id` the API returns. Project-scoped calls return a `{ data }` envelope.

```typescript
// app/api/setup/route.ts
import { Recursiv } from '@recursiv/sdk';

export async function POST() {
  const r = new Recursiv();

  const { data: project } = await r.projects.create({ name: 'my-app' });

  await r.databases.ensure({ project_id: project.id, name: 'main' });

  const { data: result } = await r.databases.query({
    project_id: project.id,
    sql: 'SELECT NOW() as time',
  });

  return Response.json({ project: project.id, rows: result.rows });
}
```

## Run and stream an agent

Create an agent against any model, then stream its replies. In Node and the browser use `chatStream()`, which yields an async iterable of `{ delta }` chunks.

```typescript
// app/api/chat/route.ts
import { Recursiv } from '@recursiv/sdk';

export async function POST(req: Request) {
  const { agentId, message } = await req.json();
  const r = new Recursiv();

  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      for await (const chunk of r.agents.chatStream(agentId, { message })) {
        controller.enqueue(encoder.encode(chunk.delta ?? ''));
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
  });
}
```

Create the agent once (in setup, a script, or the dashboard):

```typescript
const { data: agent } = await r.agents.create({
  project_id: project.id,
  name: 'Support Bot',
  model: 'anthropic/claude-sonnet-4.6',
  system_prompt: 'You are a helpful assistant.',
});
```

The `model` field is model agnostic. Pass any supported model id.

## Where to go next

* [Quickstart](/guides/start-here/quickstart) for the full set of first calls
* [Add AI Agents to Next.js](/recipes/cookbook/agents) for agent details
* [Add Authentication to Next.js](/recipes/cookbook/apps) for user auth
* [API Reference](/api-reference) for the full REST surface
* Recursiv ships hundreds of data integrations (Slack, email, databases, and more) that agents can call as tools