LangGraph & OpenAI Agents: an approval check before an agent acts

npm i spurvik

// approval/request.ts: ask a person before the agent acts
import { createMultiChannelApprovalRouter } from "spurvik/channels";

const router = createMultiChannelApprovalRouter({
  signingSecret: process.env.SPURVIK_SIGNING_SECRET!, // at least 16 characters
  channels: [{ type: "slack", webhookUrl: process.env.SLACK_WEBHOOK_URL! }],
});

export async function askBeforeRefund(orderId: string, amountEur: number) {
  const { links, receipts } = await router.requestApproval({
    gateId: crypto.randomUUID(),
    actionName: "stripe.refunds.create",
    summary: `Refund €${amountEur} on order ${orderId}`,
    context: { amountEur, currency: "EUR" },
    callbackBaseUrl: "https://your-app.example/api/spurvik/callback", // your own GET endpoint
  });
  return { gateId: links.gateId, receipts };
}

// app/api/spurvik/callback/route.ts: your endpoint; there is no hosted handler
import { verifyChannelApprovalToken } from "spurvik/channels";

const usedNonces = new Set<string>(); // use your database in production

export async function GET(req: Request) {
  const q = new URL(req.url).searchParams;
  const gateId = q.get("gateId");
  const decision = q.get("decision");
  const nonce = q.get("nonce");
  if (!gateId || !nonce || (decision !== "approved" && decision !== "rejected")) {
    return new Response("Link invalid.", { status: 400 });
  }
  const valid = verifyChannelApprovalToken({
    gateId,
    actionHmac: q.get("hmac") ?? "",
    decision,
    issuedAtUnix: Number(q.get("ts")),
    signature: q.get("sig") ?? "",
    nonce,
    signingSecret: process.env.SPURVIK_SIGNING_SECRET!,
    maxAgeSeconds: 3600, // default is 86400
  });
  if (!valid || usedNonces.has(nonce)) {
    return new Response("Link invalid, expired or already used.", { status: 400 });
  }
  usedNonces.add(nonce);
  // Continue the action only when decision === "approved".
  // Record the decision for this gateId in your own store.
  return new Response(decision === "approved" ? "Approved." : "Blocked.");
}

npm i spurvik @openai/agents zod

// agents.ts: OpenAI Agents SDK
import { Agent, OpenAIProvider, run, tool } from "@openai/agents";
import { z } from "zod";
import {
  withSpurvikModel,
  createSpurvikNeedsApproval,
  resolveAgentInterruptions,
} from "spurvik/openai-agents";

const config = {
  apiKey: process.env.SPURVIK_API_KEY!,
  signingSecret: process.env.SPURVIK_SIGNING_SECRET!,
  contentHash: { mode: "keyed" as const, secret: process.env.SPURVIK_CONTENT_HASH_SECRET! },
  baseUrl: process.env.SPURVIK_BASE_URL!,
  riskTier: "limited_art50" as const, // your own classification
};

const issueRefund = tool({
  name: "issue_refund",
  description: "Refund an order",
  parameters: z.object({ orderId: z.string(), amountEur: z.number() }),
  needsApproval: createSpurvikNeedsApproval(config, { actionName: "issue_refund" }),
  execute: async ({ orderId, amountEur }) => `Refunded €${amountEur} on ${orderId}`,
});

const model = withSpurvikModel(await new OpenAIProvider().getModel("gpt-4o-mini"), config);
const agent = new Agent({ name: "ops", model, tools: [issueRefund] });

let result = await run(agent, "Refund order 42 for €40");
if (result.interruptions.length > 0) {
  // Sends each pending tool call to the review queue and waits for a decision.
  // Only "approved" calls state.approve; "rejected" and "overridden" call state.reject.
  await resolveAgentInterruptions(result.interruptions, config, { state: result.state });
  result = await run(agent, result.state);
}
await model.flush();

npm i spurvik @langchain/langgraph @langchain/core

// graph.ts: LangGraph
import { StateGraph, MessagesAnnotation, START, END } from "@langchain/langgraph";
import { AIMessage } from "@langchain/core/messages";
import { spurvikInterrupt } from "spurvik/langgraph";

const config = {
  apiKey: process.env.SPURVIK_API_KEY!,
  signingSecret: process.env.SPURVIK_SIGNING_SECRET!,
  contentHash: { mode: "keyed" as const, secret: process.env.SPURVIK_CONTENT_HASH_SECRET! },
  baseUrl: process.env.SPURVIK_BASE_URL!,
  riskTier: "limited_art50" as const, // your own classification
};

export const graph = new StateGraph(MessagesAnnotation)
  .addNode("refund", async () => {
    // Sends the action to the review queue and waits (120 s by default).
    const decision = await spurvikInterrupt(
      { actionName: "issue_refund", payload: { orderId: "42", amountEur: 40 } },
      config,
    );
    if (!decision.approved) {
      // "rejected" and "overridden" both land here: do not act.
      return { messages: [new AIMessage(`Refund not issued (${decision.status}).`)] };
    }
    // ... issue the refund here ...
    return { messages: [new AIMessage("Refund issued.")] };
  })
  .addEdge(START, "refund")
  .addEdge("refund", END)
  .compile();