Quickstart

Welcome! Arcten allows you to embed deeply-integrated enterprise grade AI agents into your application. Our philosophy is that getting started shouldn't take more than a couple minutes.

This quickstart shows how to get started with our React SDK for Next.js applications. However, we support all websites (any stack) with our embeddeable Vanilla JavaScript SDK as well.

To request features or report bugs check out feedback.arcten.com (no sign up required).

Create Project and API Key

Create a new project on the dashboard at arcten.com.

Copy your API key and add it to your .env or .env.local file:

ARCTEN_API_KEY=sk_proj_keyhere...

Install Package

npm install @arcteninc/core

After installing, update your package.json scripts to include arcten-extract-types in your dev and build commands:

{
  "scripts": {
    "dev": "arcten-extract-types && next dev",
    "build": "arcten-extract-types && next build"
  }
}

This ensures that your agent always has access to the latest type definitions from your codebase.

Add Styles to globals.css

Add the Arcten styles import to your app/globals.css (or your main CSS file):

@import "@arcteninc/core/styles";

This should be added after your Tailwind directives to ensure Arcten components are styled correctly.

Add Agent Component

In your root app layout, import and include the ArctenAgent component.

import { ArctenAgent } from "@arcteninc/core";
import "@arcteninc/core/styles";
// Import tool metadata from the .arcten folder in your project root
import { toolMetadata } from "../.arcten/tool-metadata";

// Add into your layout
return (
  <div className="flex h-screen">
    <div className="flex-1 overflow-scroll">
      {children}
    </div>
    <ArctenAgent
      systemPrompt="You are an expert AI agent tasked with helping the user."
      toolMetadata={toolMetadata}
    />
  </div>
);

Important: If you are using Next.js, it is essential that the ArctenAgent component lives in a "client component". We recommend following our setup:

First, create a ClientWrapper component.

"use client";

import { ArctenAgent } from "@arcteninc/core";
import "@arcteninc/core/styles";
// Import tool metadata - adjust the relative path to point to .arcten folder in your project root
import { toolMetadata } from "../.arcten/tool-metadata";

interface ClientWrapperProps {
  children: React.ReactNode;
}

export function ClientWrapper({ children }: ClientWrapperProps) {
  return (
    // use flex layout to put agent in the sidebar (next to your app content)
    <div className="flex h-screen" >
      <div className="flex-1 overflow-scroll">
        {children}
      </div>
      <ArctenAgent
        systemPrompt="You are an expert AI agent tasked with helping the user."
        toolMetadata={toolMetadata}
      />
    </div>
  );
}

Then, include the ClientWrapper in your app/layout.tsx:

import type { Metadata } from "next";
import { ClientWrapper } from "./ClientWrapper";
import "./globals.css";

export const metadata: Metadata = {
  title: "My App",
  description: "My app - now powered by Arcten Agent!",
};

export default function RootLayout({children}: Readonly<{children: React.ReactNode}>) {
  return (
    <html lang="en">
      <body>
        <ClientWrapper>{children}</ClientWrapper>
      </body>
    </html>
  );
}

Coming soon. Upvote this on our roadmap board here.

We plan to support more frameworks/languages. Suggest one here (no login required).

Create API Route

You will need to create an API route.

Create an API route at app/api/arcten/token/route.ts:

import { verifyToken } from "@arcteninc/core/server";
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  try {
    const body = await req.json();
    const { user } = body;

    const apiKey = process.env.ARCTEN_API_KEY;

    if (!apiKey) {
      throw new Error("ARCTEN_API_KEY environment variable is not set");
    }

    const tokenResponse = await verifyToken({
      apiKey,
      user,
    });

    return NextResponse.json(tokenResponse);
  } catch (error) {
    console.error("Token generation error:", error);
    return NextResponse.json(
      {
        error:
          error instanceof Error ? error.message : "Failed to generate token",
      },
      { status: 500 }
    );
  }
}

If you're using a separate backend like Express, you will have to point the ArctenAgent component's tokenEndpoint prop to your server's address:

<ArctenAgent
  ...
  tokenEndpoint="https://yourapi.com/api/arcten/token",
  ...
/>

Create an API endpoint in your Express app (which is hosted at https://yourapi.com):

import { verifyToken } from "@arcteninc/core/server";
import express, { Request, Response } from "express";

const app = express();
app.use(express.json());

app.post("/api/arcten", async (req: Request, res: Response) => {
  try {
    const { user } = req.body;

    const apiKey = process.env.ARCTEN_API_KEY;

    if (!apiKey) {
      throw new Error("ARCTEN_API_KEY environment variable is not set");
    }

    const tokenResponse = await verifyToken({
      apiKey,
      user,
    });

    res.json(tokenResponse);
  } catch (error) {
    console.error("Token generation error:", error);
    res.status(500).json({
      error:
        error instanceof Error ? error.message : "Failed to generate token",
    });
  }
});

We plan to support more server frameworks/languages. Suggest one here (no login required).