Build an AI agent with Arcade and CopilotKit

ARCADE_API_KEY={arcade_api_key}
ARCADE_USER_ID={arcade_user_id}
OPENAI_API_KEY=your_openai_api_key

import Arcade from "@arcadeai/arcadejs";
 
// Created lazily so the module can be imported during `next build` without the
// key set (the SDK throws on construction when ARCADE_API_KEY is missing).
let arcadeClient: Arcade | undefined;
function getArcade() {
  if (!arcadeClient) arcadeClient = new Arcade({ apiKey: process.env.ARCADE_API_KEY });
  return arcadeClient;
}
 
export function getArcadeUserId(): string {
  const userId = process.env.ARCADE_USER_ID;
  if (userId) return userId;
  // Fail CLOSED in production: a shared fallback id would put every user on ONE
  // Arcade token vault (cross-account access). In dev, fall back for convenience.
  if (process.env.NODE_ENV === "production") {
    throw new Error("ARCADE_USER_ID is not set. Derive it per-request from your session.");
  }
  return "demo-user@example.com";
}
 
export type ArcadeToolResult =
  | { authorizationRequired: true; toolName: string; provider: string; authUrl: string }
  | { authorizationRequired: false; toolName: string; provider: string; output: unknown }
  | { error: string; toolName: string };
 
export async function runArcadeTool({
  toolName,
  input,
  userId,
}: {
  toolName: string;
  input: Record<string, unknown>;
  userId: string;
}): Promise<ArcadeToolResult> {
  const provider = toolName.split(".")[0] ?? toolName;
  try {
    const arcade = getArcade();
 
    // 1. Does this user already have the scopes this tool needs? Status is one of
    //    not_started | pending | completed | failed.
    const auth = await arcade.tools.authorize({ tool_name: toolName, user_id: userId });
 
    // 2. Not connected yet → return the URL so CopilotKit renders a "Connect" card.
    //    A `failed` status (or a missing URL) is an error, not a dead card.
    if (auth.status !== "completed") {
      if (auth.status === "failed" || !auth.url) {
        return { error: `Couldn't start authorization for ${provider}.`, toolName };
      }
      return { authorizationRequired: true, toolName, provider, authUrl: auth.url };
    }
 
    // 3. Otherwise run the tool with the user's vaulted credentials.
    const response = await arcade.tools.execute({ tool_name: toolName, input, user_id: userId });
 
    // 4. Fail closed: runtime failures come back as data, not as a thrown error.
    if (response.success === false || response.output?.error) {
      return { error: response.output?.error?.message ?? "The tool call failed.", toolName };
    }
    return { authorizationRequired: false, toolName, provider, output: response.output?.value ?? null };
  } catch (err) {
    // Unexpected/transport error. Return an error shape instead of throwing, since a
    // thrown error kills the run. Don't surface raw internals in production.
    console.error(`[arcade] ${toolName} failed:`, err);
    const detail = err instanceof Error ? err.message : String(err);
    return {
      error: process.env.NODE_ENV === "production" ? "The tool call failed unexpectedly." : detail,
      toolName,
    };
  }
}

import {
  BuiltInAgent,
  CopilotRuntime,
  createCopilotRuntimeHandler,
  defineTool,
} from "@copilotkit/runtime/v2";
import { z } from "zod";
import { getArcadeUserId, runArcadeTool } from "@/lib/arcade";
 
// Tools are built per request so each runs against the *current* user's id.
function buildTools(userId: string) {
  const searchNews = defineTool({
    name: "searchNews",
    description: "Search recent news stories by keyword using Google News.",
    parameters: z.object({ keywords: z.string().describe("Search keywords") }),
    execute: async ({ keywords }) =>
      runArcadeTool({ toolName: "GoogleNews.SearchNewsStories", input: { keywords }, userId }),
  });
 
  const sendEmail = defineTool({
    name: "sendEmail",
    description: "Send an email from the user's connected Gmail account.",
    parameters: z.object({
      recipient: z.string().describe("Recipient email address"),
      subject: z.string().describe("Subject line"),
      body: z.string().describe("Plain-text body"),
    }),
    execute: async ({ recipient, subject, body }) =>
      runArcadeTool({ toolName: "Gmail.SendEmail", input: { recipient, subject, body }, userId }),
  });
 
  const listEmails = defineTool({
    name: "listEmails",
    description: "List recent emails from the user's connected Gmail inbox.",
    // Param name mirrors the Arcade tool's schema (Gmail.ListEmails takes `n_emails`).
    parameters: z.object({
      n_emails: z.number().int().min(1).max(50).default(10).describe("How many to return"),
    }),
    execute: async ({ n_emails }) =>
      runArcadeTool({ toolName: "Gmail.ListEmails", input: { n_emails }, userId }),
  });
 
  return [searchNews, sendEmail, listEmails];
}
 
const SYSTEM_PROMPT = `You can act for the user through Arcade tools: searching Google News, and reading and sending Gmail.
 
When a tool result is { "authorizationRequired": true, ... }, the chat shows a "Connect" card.
Do NOT retry or invent a result. In one sentence, tell the user to click Connect, then come
back and say continue. When they confirm, call the SAME tool again with the SAME arguments.
 
Before sending email, confirm the recipient and subject in one line. Keep replies short. The
tool cards show the details.`;
 
function buildAgent(userId: string) {
  return new BuiltInAgent({
    model: process.env.OPENAI_MODEL || "openai/gpt-4o",
    apiKey: process.env.OPENAI_API_KEY,
    prompt: SYSTEM_PROMPT,
    tools: buildTools(userId),
    maxSteps: 6, // > 1 so the agent can call a tool and then respond
  });
}
 
// Resolve the Arcade user id per request from your SERVER-VERIFIED session. A
// single shared id would put every visitor on ONE Arcade vault (cross-account
// access). getArcadeUserId() is the demo fallback and throws in production.
function resolveArcadeUserId(request: Request): string {
  // const { userId } = await verifySession(request); return userId;
  return getArcadeUserId();
}
 
// The runtime can read and send email on your keys, so never leave it open in prod.
// Replace this with your real session check; it fails CLOSED until you do.
function authorizeRuntimeRequest(request: Request): void {
  // const session = await verifySession(request);
  // if (!session) throw new Response("Unauthorized", { status: 401 });
  if (process.env.NODE_ENV === "production") {
    throw new Response("Runtime auth is not configured.", { status: 503 });
  }
}
 
const runtime = new CopilotRuntime({
  // Per request → a fresh agent scoped to THIS user's id.
  agents: ({ request }) => ({ default: buildAgent(resolveArcadeUserId(request)) }),
});
 
const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
  mode: "single-route",
  hooks: {
    // Reject unauthorized calls before the agent runs.
    onRequest: ({ request }) => authorizeRuntimeRequest(request),
  },
});
 
export const GET = handler;
export const POST = handler;
export const OPTIONS = handler;

"use client";
import { CopilotChat, useRenderTool } from "@copilotkit/react-core/v2";
import { z } from "zod";
 
// useRenderTool usually hands `result` back as a JSON string, but tolerate an
// already-parsed object or an empty/missing value so a partial result never throws.
function parse<T>(result: unknown): T | undefined {
  if (result == null) return undefined;
  if (typeof result === "object") return result as T;
  if (typeof result !== "string" || result.length === 0) return undefined;
  try {
    return JSON.parse(result) as T;
  } catch {
    return undefined;
  }
}
 
type ToolResult =
  | { authorizationRequired: true; provider: string; authUrl: string }
  | { authorizationRequired: false; provider: string; output: unknown }
  | { error: string };
 
function LoadingCard({ label }: { label: string }) {
  return <p className="text-sm text-zinc-500">{label}</p>;
}
 
function ErrorCard({ message }: { message: string }) {
  return (
    <div className="rounded-2xl border border-red-200 bg-red-50 p-4 text-sm text-red-700">
      {message}
    </div>
  );
}
 
function EmailSentCard({ recipient, subject }: { recipient: string; subject: string }) {
  return (
    <div className="rounded-2xl border border-green-200 bg-green-50 p-4 text-sm">
      <p className="font-semibold">Email sent</p>
      <p className="mt-1 text-zinc-600">
        To {recipient} — {subject}
      </p>
    </div>
  );
}
 
// Tool output flows into an href, so only ever link to a real http(s) URL,
// never a javascript:/data: scheme.
function safeHttpUrl(url: string): string | undefined {
  try {
    const u = new URL(url);
    return u.protocol === "https:" || u.protocol === "http:" ? url : undefined;
  } catch {
    return undefined;
  }
}
 
function AuthorizationCard({ provider, authUrl }: { provider: string; authUrl: string }) {
  const href = safeHttpUrl(authUrl);
  return (
    <div className="rounded-2xl border border-violet-200 bg-violet-50 p-4">
      <p className="font-semibold">Connect {provider}</p>
      <p className="mt-1 text-sm text-zinc-600">
        Arcade needs you to authorize {provider} once. Your credentials are vaulted by Arcade
        and never shared with the model.
      </p>
      {href && (
        <a
          href={href}
          target="_blank"
          rel="noopener noreferrer"
          className="mt-3 inline-block rounded-lg bg-violet-600 px-3.5 py-2 text-sm font-semibold text-white"
        >
          Connect {provider}
        </a>
      )}
    </div>
  );
}
 
export default function Page() {
  useRenderTool({
    name: "sendEmail",
    parameters: z.object({ recipient: z.string(), subject: z.string(), body: z.string() }),
    render: ({ status, parameters, result }) => {
      if (status !== "complete") return <LoadingCard label="Sending email…" />;
      const r = parse<ToolResult>(result);
      if (r && "error" in r) return <ErrorCard message={r.error} />;
      if (r && r.authorizationRequired)
        return <AuthorizationCard provider={r.provider} authUrl={r.authUrl} />;
      // Only render success on the positive discriminant. A missing or unparseable
      // result (r === undefined) must not fall through to a green "sent" card.
      if (r && r.authorizationRequired === false)
        return <EmailSentCard recipient={parameters.recipient} subject={parameters.subject} />;
      return <ErrorCard message="Couldn't read the tool result." />;
    },
  });
 
  return <CopilotChat agentId="default" />;
}

"use client";
import { CopilotKit } from "@copilotkit/react-core/v2";
 
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit" useSingleEndpoint>
      {children}
    </CopilotKit>
  );
}

import "@copilotkit/react-core/v2/styles.css";
import { Providers } from "./providers";
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Send an email to me@example.com with the subject "Hello from my agent" and a friendly one-liner.

Done, go ahead.

Find the latest news on open-source AI agents and email me a 3-bullet summary.