Introduction to Sammy

Sammy is an auto-configuring AI agent framework that scans your codebase, understands your APIs and business logic, and generates production-ready AI agents — all without requiring AI expertise.

Quick Start

Go from an existing Next.js app to a working, tool-using AI assistant at /chat in about 10 minutes. The CLI scaffolds the wiring for you.

Prerequisites

• A Next.js project (App Router) with some API routes or server functions
• Node.js 18+
• A Sammy API key (create one in your dashboard)

Step 1: Install the SDK

The package is sammy-sdk; it ships the sammy CLI.

npm install sammy-sdk

Step 2: Scan your codebase

Add your API key to .env.local, then run discovery — it writes a reviewable sammy.config.json.

# .env.local
SAMMY_API_KEY=sk_sammy_your_key_here

npx sammy init

Step 3: Generate tools & agents

npx sammy generate   # writes .sammy/tools + .sammy/agents
npx sammy eval       # optional: self-evaluate and refine

Step 4: Scaffold the wiring

This writes the server helper, the chat + history API routes, and a /chat page, and patches next.config, middleware, and .env.local. See Scaffolding for details.

npx sammy scaffold next        # add --dry-run to preview first

Step 5: Install the chat UI

The scaffolded /chat page renders SammyChatApp, so install the frontend packages:

npm install sammy-sdk-ui sammy-sdk-react sammy-sdk-client

Step 6: Run it

For local demos without logging in, set a real seeded user id so write tools that persist foreign keys succeed (scaffold adds the placeholder):

# .env.local
SAMMY_DEV_USER_ID=<a-real-user-id-from-your-db>

npm run dev   # then open http://localhost:3000/chat

Scaffolding

sammy scaffold next writes the Next.js App Router wiring so you don't have to copy it by hand. It is idempotent and never overwrites your files — anything it can't edit safely is printed as a manual step.

npx sammy scaffold next
npx sammy scaffold next --dry-run   # preview without writing

What it creates

What it patches

CLI Reference

All Sammy CLI commands and their options.

Discovery Engine

The discovery engine is Sammy's core differentiator. It performs static analysis combined with LLM-powered semantic understanding to build a complete capability map of your application.

What Gets Scanned

How It Works

Tool Generation

The tool generator reads sammy.config.json and scaffolds executable tool files that agents can invoke at runtime.

What Gets Generated

// .sammy/tools/billing/getInvoices.ts (auto-generated)
import { z } from "zod";

export const getInvoicesSchema = z.object({
  customerId: z.string().describe("The customer ID"),
  status: z.enum(["draft", "open", "paid", "void"]).optional(),
  from: z.string().date().optional(),
  to: z.string().date().optional(),
});

export const getInvoices = {
  name: "getInvoices",
  description: "List invoices for a customer with optional filters",
  schema: getInvoicesSchema,
  permission: "read",
  handler: async (params, context) => {
    const { listInvoices } = await import("@/services/billing/invoices");
    return listInvoices(params);
  },
};

Runtime

The runtime engine is what serves your AI assistant in production. It handles message routing, agent orchestration, tool execution, and streaming responses.

Request Flow

Modes

Evaluation & Refinement

Sammy auto-generates test scenarios, runs them against your agents, scores across 6 dimensions, and self-refines until all thresholds pass.

The 6 Scoring Dimensions

The Refinement Loop

sammy.config.json

The config file is the contract between discovery and everything downstream. It's auto-generated but designed to be human-readable and editable.

{
  "$schema": "https://unpkg.com/sammy-sdk/schema.json",
  "version": "1.0",
  "project": {
    "framework": "nextjs",
    "frameworkVersion": "15.2",
    "router": "app",
    "orm": "prisma"
  },
  "domains": [
    {
      "name": "billing",
      "description": "Manages subscriptions, invoices, and payments via Stripe",
      "tools": [
        {
          "name": "getInvoices",
          "type": "query",
          "permission": "read",
          "handler": "src/services/billing/invoices.ts:listInvoices"
        }
      ]
    }
  ],
  "architecture": {
    "type": "multi-agent",
    "router": { "model": "fast" },
    "agents": [
      { "name": "billing-agent", "domains": ["billing"], "model": "balanced" }
    ]
  }
}

Architecture Options

Sammy automatically recommends an architecture based on how many domains are discovered and their complexity.

You can override the recommendation by setting architecture.type in your config to "single", "multi-agent", or "hierarchical".

Model Tiers

Sammy uses abstract model tiers instead of specific model names. This lets us upgrade models without changing your code.

API Routes

Scaffolding generates everything below — this section documents what those files contain so you can customize them or wire them by hand.

One shared Sammy instance

Next.js can load each route in a separate module graph, so keep a single instance on globalThis — that way chat and history share one conversation store.

// lib/sammy-server.ts
import { Sammy } from "sammy-sdk";
import { auth } from "@/lib/auth";

const g = globalThis as typeof globalThis & { __sammy?: Sammy };

export function getSammy() {
  if (!g.__sammy) {
    g.__sammy = new Sammy({
      systemPrompt: "You are a helpful assistant. Use tools for current data; be concise.",
      // conversationStorage: new YourRedisStorage(...), // see Conversation Storage
    });
  }
  return g.__sammy;
}

// Never trust a client-sent user in production — resolve it server-side.
export async function resolveUserFromSession(_req: Request) {
  const session = await auth();
  if (session?.user?.id) {
    return { id: session.user.id, email: session.user.email ?? undefined };
  }
  // Dev only: FK-safe writes when demoing /chat without logging in.
  const devId = process.env.SAMMY_DEV_USER_ID;
  if (devId) return { id: devId };
  return undefined;
}

The chat endpoint

One handler — it handles JSON responses, SSE streaming, body validation, and errors.

// app/api/chat/route.ts
import { createSammyRouteHandler } from "sammy-sdk";
import { getSammy, resolveUserFromSession } from "@/lib/sammy-server";

export const runtime = "nodejs";
export const dynamic = "force-dynamic";

export const POST = createSammyRouteHandler(getSammy(), {
  resolveUser: resolveUserFromSession,
});

Required: next.config

The runtime loads your generated .sammy/*.ts tools via tsx at request time, so they must stay external to the bundle.

// next.config.mjs
const nextConfig = {
  serverExternalPackages: ["sammy-sdk", "tsx"],
};
export default nextConfig;

Conversation History

Three more handlers give you a persistent thread list, resumable conversations, and delete — all scoped to the resolved user, so users never see each other's threads.

// app/api/chat/conversations/route.ts
import { createSammyListConversationsHandler } from "sammy-sdk";
import { getSammy, resolveUserFromSession } from "@/lib/sammy-server";

export const runtime = "nodejs";
export const dynamic = "force-dynamic";

export const GET = createSammyListConversationsHandler(getSammy(), {
  resolveUser: resolveUserFromSession,
});

// app/api/chat/conversations/[id]/route.ts
import {
  createSammyGetConversationHandler,
  createSammyDeleteConversationHandler,
} from "sammy-sdk";
import { getSammy, resolveUserFromSession } from "@/lib/sammy-server";

export const runtime = "nodejs";
export const dynamic = "force-dynamic";

const opts = { resolveUser: resolveUserFromSession };
export const GET = createSammyGetConversationHandler(getSammy(), opts);
export const DELETE = createSammyDeleteConversationHandler(getSammy(), opts);

HTTP contract

SSE events when streaming: text, tool_call, tool_result, agent_handoff, done, error.

Frontend Packages

Choose your level of abstraction — from a drop-in widget to a raw client for any framework.

import { SammyChatApp } from "sammy-sdk-ui";

export default function ChatPage() {
  return <SammyChatApp endpoint="/api/chat" title="My Assistant" height={560} />;
}

import { SammyChatInline, SammyChat } from "sammy-sdk-ui";

// Inline panel inside a page
<SammyChatInline endpoint="/api/chat" title="Support" />

// Floating widget (corner bubble)
<SammyChat endpoint="/api/chat" position="bottom-right" />

import { SammyProvider, useSammyChat, useSammyConversations } from "sammy-sdk-react";

function MyChat() {
  const { conversations, refresh } = useSammyConversations();
  const chat = useSammyChat({ onConversationId: () => refresh() });

  return (
    <div>
      <button onClick={() => chat.startNewConversation()}>New chat</button>
      {conversations.map((c) => (
        <button key={c.id} onClick={() => chat.selectConversation(c.id)}>{c.title}</button>
      ))}
      {/* render chat.messages; an input that calls chat.send(text) */}
    </div>
  );
}

export function App() {
  return (
    <SammyProvider endpoint="/api/chat">
      <MyChat />
    </SammyProvider>
  );
}

import { SammyClient } from "sammy-sdk-client";

const client = new SammyClient({ endpoint: "/api/chat" });

const list = await client.listConversations();
const detail = await client.getConversation(list[0].id);
await client.deleteConversation(list[0].id);

const stream = client.stream("Show me unpaid invoices", { conversationId: detail.id });
stream.on("text", (chunk) => { /* update UI */ }).on("done", (final) => { /* settle */ });

Security & Auth

Sammy has security built in at every layer — from tool permissions to data handling.

Permission Levels

Data Handling

Conversation Storage

By default, conversations are kept in an in-memory store. That is perfect for local development, but it is not durable — history is wiped on restart and is not shared across multiple instances. For production, plug in your own store.

The interface

ConversationStorage is a small interface; implement it and pass it to new Sammy(...). Every chat and history route then uses it transparently.

import type { ConversationStorage } from "sammy-sdk";

export class RedisConversationStorage implements ConversationStorage {
  async getOrCreate(id, userId) { /* ... */ }
  async append(id, message)     { /* ... */ }
  async get(id, userId)         { /* ... */ }
  async list(userId, opts)      { /* ... */ }
  async delete(id, userId)      { /* ... */ }
  async touch(id, patch)        { /* optional */ }
}

new Sammy({ conversationStorage: new RedisConversationStorage(/* ... */) });

What to use where

Deployment

A Sammy-powered app deploys like any other Next.js app (Vercel, your own Node host, containers). Keep these production specifics in mind.

Before you ship

• resolveUser wired to your real auth (not SAMMY_DEV_USER_ID)
• ConversationStorage backed by Redis or a database
• serverExternalPackages: ["sammy-sdk", "tsx"] in next.config
• Middleware protects /chat and /api/chat
• SAMMY_API_KEY stored in a secrets manager
• sammy generate runs in CI when sammy.config.json changes
• App-level rate limits / cost controls on LLM usage