Add an AI agent to an existing SaaS without rewriting it

// services/support.ts — functions that ALREADY exist in your app.
export async function searchOrders(userId: string, q: string): Promise;
export async function getOrder(userId: string, orderId: string): Promise;
export async function refundOrder(userId: string, orderId: string): Promise;
export async function listInvoices(userId: string): Promise;

// agent/tools.ts
import * as support from "../services/support.js";

export function buildTools(userId: string) {
  return {
    search_orders: async ({ query }: { query: string }) =>
      JSON.stringify(await support.searchOrders(userId, query)),
    get_order: async ({ order_id }: { order_id: string }) =>
      JSON.stringify(await support.getOrder(userId, order_id)),
    list_invoices: async () =>
      JSON.stringify(await support.listInvoices(userId)),
  };
}

import type Anthropic from "@anthropic-ai/sdk";

export const toolSchemas: Anthropic.Tool[] = [
  {
    name: "search_orders",
    description: "Search the current user's orders by free-text query. Use for 'where is my order' questions.",
    input_schema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
  },
  {
    name: "get_order",
    description: "Fetch full details for one of the current user's orders by id.",
    input_schema: { type: "object", properties: { order_id: { type: "string" } }, required: ["order_id"] },
  },
  {
    name: "list_invoices",
    description: "List the current user's invoices. Takes no arguments.",
    input_schema: { type: "object", properties: {} },
  },
];

export const refundSchema: Anthropic.Tool = {
  name: "propose_refund",
  description: "Propose a refund for an order. This does NOT execute; it returns an action for the user to confirm.",
  input_schema: {
    type: "object",
    properties: { order_id: { type: "string" }, reason: { type: "string" } },
    required: ["order_id", "reason"],
  },
};

// Adapter returns a structured proposal instead of performing the refund.
async function propose_refund(input: { order_id: string; reason: string }) {
  return JSON.stringify({ action: "refund", ...input, requires_confirmation: true });
}

import Anthropic from "@anthropic-ai/sdk";
import { buildTools } from "./tools.js";
import { toolSchemas, refundSchema } from "./schemas.js";

const client = new Anthropic();
const MODEL = "claude-sonnet-4-6";

export async function runSupportAgent(userId: string, message: string): Promise {
  const registry: Record Promise> = {
    ...buildTools(userId),
    propose_refund: async (i) => JSON.stringify({ action: "refund", ...i, requires_confirmation: true }),
  };
  const tools = [...toolSchemas, refundSchema];
  const messages: Anthropic.MessageParam[] = [{ role: "user", content: message }];

  for (let turn = 0; turn < 8; turn++) {
    const res = await client.messages.create({ model: MODEL, max_tokens: 1024, tools, messages });
    messages.push({ role: "assistant", content: res.content });
    if (res.stop_reason !== "tool_use") {
      const t = res.content.find((b) => b.type === "text");
      return t && t.type === "text" ? t.text : "(no answer)";
    }
    const results: Anthropic.ToolResultBlockParam[] = [];
    for (const b of res.content) {
      if (b.type !== "tool_use") continue;
      console.log(`[support-agent] user=${userId} -> ${b.name}`);
      let out: string;
      try { out = await registry[b.name](b.input); }
      catch (err) { console.error(`[support-agent] ${b.name} failed`, err); out = `Error: ${(err as Error).message}`; }
      results.push({ type: "tool_result", tool_use_id: b.id, content: out });
    }
    messages.push({ role: "user", content: results });
  }
  return "Stopped: reached the turn limit.";
}

// app/api/agent/route.ts (Next.js App Router)
import { NextResponse } from "next/server";
import { runSupportAgent } from "@/agent/loop";
import { getSessionUser } from "@/lib/auth";

export async function POST(req: Request) {
  try {
    const user = await getSessionUser();
    if (!user) return NextResponse.json({ ok: false, error: "Unauthorized" }, { status: 401 });
    const { message } = (await req.json()) as { message: string };
    const answer = await runSupportAgent(user.id, message);
    return NextResponse.json({ ok: true, data: { answer } });
  } catch (err) {
    console.error("[api/agent] failed", err);
    return NextResponse.json({ ok: false, error: (err as Error).message }, { status: 500 });
  }
}

# Set the model key as a Totalum environment secret (never commit it).
# Totalum dashboard -> Project -> Environment variables:
#   ANTHROPIC_API_KEY = sk-ant-...

# Then publish the project from the Totalum dashboard.
# Your route is now live at:
#   https://.totalum.app/api/agent

import { api } from "@/lib/api";
const res = await api.post("/api/agent", { message: "Where is my last order?" });
if (res.ok) console.log(res.data.answer);

curl -X POST https://.totalum.app/api/agent \
  -H "Content-Type: application/json" \
  -H "Cookie: " \
  -d '{"message":"Refund my last order, it arrived broken."}'