Quickstart: Node SDK

This guide takes you from nothing installed to a working AI chatbot that can read your email, check your calendar, and send Slack messages — all through a chat interface you own.

create-supyagent-app scaffolds a complete Next.js app with the Vercel AI SDK, Supyagent Cloud integrations, chat persistence, and a ready-to-use UI. All batteries included.

Prerequisites

• Node.js 18+ — check with node --version
• A Supyagent account — sign up at supyagent.com and connect at least one integration (Google, Slack, etc.)
• An AI provider API key — Anthropic, OpenAI, or OpenRouter

Step 1: Scaffold the app

npx create-supyagent-app my-agent

The CLI walks you through a few prompts:

? AI provider: Anthropic (Claude)
? Agent mode: Skills (token-efficient, recommended)
? Database: SQLite (local dev)
? Authentication: Login via browser (recommended)

It opens your browser to authenticate with Supyagent, then scaffolds the project, installs dependencies, sets up the database, and starts the dev server automatically.

✔ Scaffolded project
✔ Installed dependencies
✔ Database ready
Starting dev server...

  ➜ Local: http://localhost:3000

Step 2: Open and chat

Open http://localhost:3000 in your browser. You'll see a chat interface. Try asking:

What emails did I get today?

The agent will:

1. Load the Gmail skill documentation from Supyagent Cloud
2. Call the Gmail API through Supyagent to fetch your messages
3. Present a summary in the chat

Try more:

What's on my calendar this week?

Send a Slack message to #general saying "deploying now"

Summarize my last 5 unread emails and create a calendar event for anything that needs follow-up

Step 3: Understand what was generated

The scaffolded app has everything wired up:

my-agent/
├── src/app/
│   ├── api/chat/route.ts      # AI chat endpoint — this is the core
│   ├── api/chats/route.ts     # Chat history CRUD
│   ├── chat/page.tsx          # Chat UI
│   └── page.tsx               # Home page
├── prisma/schema.prisma       # Chat + message persistence
├── .env.local                 # API keys (auto-populated)
└── package.json

The key file is src/app/api/chat/route.ts:

import { streamText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { supyagent, createBashTool } from '@supyagent/sdk';

const client = supyagent({ apiKey: process.env.SUPYAGENT_API_KEY! });

export async function POST(req: Request) {
  const { messages } = await req.json();

  // Fetch skill docs + tools from Supyagent Cloud (cached 5 min)
  const { systemPrompt, tools: skillTools } = await client.skills({ cache: 300 });

  const result = streamText({
    model: anthropic('claude-sonnet-4-6-20250620'),
    system: `You are a helpful assistant.\n\n${systemPrompt}`,
    messages,
    tools: { ...skillTools, bash: createBashTool() },
  });

  return result.toDataStreamResponse();
}

That's it — client.skills() fetches the available integrations, and the AI SDK handles tool calling automatically.

Step 4: Connect more integrations

Visit supyagent.com/integrations to connect additional services. Your agent picks them up automatically on the next request — no code changes needed.

Non-interactive setup

For CI or scripted environments, pass all options as flags:

npx create-supyagent-app my-agent \
  --provider anthropic \
  --db sqlite \
  --mode skills \
  --supyagent-api-key sk_live_... \
  --anthropic-api-key sk-ant-...

Skills vs Tools mode

Both use the same Supyagent Cloud API. Switch modes by changing how you initialize tools in the API route.

Adding to an existing project

If you already have a Next.js app and want to add Supyagent Cloud integrations:

npm install @supyagent/sdk

import { supyagent } from '@supyagent/sdk';

const client = supyagent({ apiKey: process.env.SUPYAGENT_API_KEY! });

// In your route handler:
const { systemPrompt, tools } = await client.skills({ cache: 300 });
// Pass systemPrompt and tools to streamText() or generateText()

See the SDK documentation for the full API reference.

Troubleshooting

SUPYAGENT_API_KEY is not set

Make sure .env.local contains your Supyagent API key. You can get one from supyagent.com/api-keys, or run the scaffold again with --supyagent-api-key.

Agent doesn't use integrations

Check that you have active integrations on your dashboard. The agent can only use services you've connected.

Tool calls return permission errors

Some services require specific permissions to be enabled. Visit your dashboard and check the permissions for the integration.

What's next

• SDK Reference — Full client API, persistence, context management, React components
• Full API Route Example — Complete route with persistence, context, and image support
• Cloud Integrations — All supported providers and their capabilities