Quickstart

This guide walks through setting up an agent with Next.js.

Prerequisites

• Node.js 18+
• A Next.js app (or npx create-next-app@latest)
• An API key for your model provider (e.g. ANTHROPIC_API_KEY)

1. Install

npm i experimental-agent ai

2. Create your agent

import { agent } from "experimental-agent";

export const myAgent = agent("my-agent", {
  model: "anthropic/claude-opus-4.6",
  system: "You are a helpful assistant. Be concise.",
});

This agent includes built-in tools (Read, Write, Edit, Grep, List, Bash, Skill, JavaScript) and uses local filesystem storage in development.

3. Create chat helpers

import { createUIMessageStreamResponse } from "ai";
import { myAgent } from "@/agent";

export async function sendMessage({
  chatId,
  message,
}: {
  chatId: string;
  message: string;
}) {
  const session = myAgent.session(chatId);
  await session.send(message);
  const stream = await session.stream();
  return createUIMessageStreamResponse({ stream });
}

export async function reconnectStream({ chatId }: { chatId: string }) {
  const session = myAgent.session(chatId);
  const stream = await session.stream();
  return createUIMessageStreamResponse({ stream });
}

4. Wire into your app

await sendMessage({
  chatId: "my-first-session",
  message: "What files are in the current directory?",
});

Call sendMessage from your request layer and use reconnectStream when the client resumes an in-progress response. For concrete Next.js route handlers, see Using with Next.js.

What you just built

• An agent with a model, system prompt, and built-in tools
• Chat helpers for sending and reconnecting streams
• Persistent sessions — send another message to my-first-session and the agent remembers the conversation
• Local storage that persists across restarts (stored in .agent/ in your project root)

Adding Workflow (Optional)

To make the agent durable — surviving crashes, timeouts, and deploys — add a workflow:

import { myAgent } from "@/agent";
import type { SessionSendArgs } from "experimental-agent";

export async function agentWorkflow(
  sessionId: string,
  ...args: SessionSendArgs<typeof myAgent>
) {
  "use workflow";
  return await myAgent.session(sessionId).send(...args);
}

Then use start() in your route instead of calling send() directly:

import { start } from "workflow/api";
import { agentWorkflow } from "./workflow";

const result = await start(agentWorkflow, [chatId, message]);
const stream = await session.stream(result);

Next steps

• Build Your First Agent: Extend this quickstart with sandbox, custom tools, approvals, and deployment.
• Build Your First Tool: Create a custom tool with typed input and output.
• Concepts: Understand sessions, tools, sandbox, and storage.
• API Reference: Full agent() API documentation.