Human-in-the-loop approval with the OpenAI Agents SDK

import { randomUUID } from "node:crypto";
import { Agent, run, RunState, tool, type RunResult } from "@openai/agents";
import { z } from "zod";

const issueCredit = tool({
  name: "issue_credit",
  description: "Issue an account credit to a customer",
  parameters: z.object({ customer: z.string(), amountUsd: z.number(), reason: z.string() }),
  needsApproval: async (_context, { amountUsd }) => amountUsd > 50,
  execute: async ({ customer, amountUsd }) => `Credited ${customer} $${amountUsd}`,
});

export const agent = new Agent({
  name: "Billing agent",
  instructions: "Resolve billing tickets. When a credit is rejected, do not retry it; say what the reviewer asked for.",
  tools: [issueCredit],
});

export type Prompt = { decisionId: string; toolName: string; arguments: string };
export type Decision = { approved: boolean; note?: string };
export type AgentReply = { kind: "done"; output: string } | { kind: "approval"; requestId: string; prompts: Prompt[] };

// Use your database: one row per request, owner checked and deleted in one statement.
const pending = new Map<string, { ownerId: string; snapshot: string; decisionIds: string[] }>();

function reply(ownerId: string, result: RunResult<unknown, Agent<unknown, any>>): AgentReply {
  const interruptions = result.interruptions ?? [];
  if (!interruptions.length) return { kind: "done", output: String(result.finalOutput ?? "") };
  const requestId = randomUUID();
  const decisionIds = interruptions.map(() => randomUUID());
  pending.set(requestId, { ownerId, snapshot: result.state.toString(), decisionIds });
  return {
    kind: "approval",
    requestId,
    prompts: interruptions.map((item, i) => ({ decisionId: decisionIds[i]!, toolName: item.name ?? "unknown_tool", arguments: item.arguments ?? "{}" })),
  };
}

export async function start(ownerId: string, message: string) {
  return reply(ownerId, await run(agent, message));
}

export async function decide(ownerId: string, requestId: string, decisions: Record<string, Decision>) {
  const stored = pending.get(requestId);
  if (!stored || stored.ownerId !== ownerId) throw new Error("That approval request is no longer open.");
  if (!stored.decisionIds.every((id) => decisions[id])) throw new Error("Decide every pending tool call.");
  pending.delete(requestId);
  const state = await RunState.fromString(agent, stored.snapshot);
  state.getInterruptions().forEach((item, i) => {
    const decision = decisions[stored.decisionIds[i]!]!;
    if (decision.approved) state.approve(item);
    else state.reject(item, { message: decision.note || "The reviewer rejected this credit." });
  });
  return reply(ownerId, await run(agent, state));
}

import { decide, start, type Decision } from "../../../lib/billing-agent";

// Take the user from your session (Clerk, Auth.js, your own cookie), never from the request body.
declare function currentUserId(req: Request): Promise<string>;

export async function POST(req: Request) {
  const userId = await currentUserId(req);
  const body: { message: string } | { requestId: string; decisions: Record<string, Decision> } = await req.json();
  const reply = "message" in body ? await start(userId, body.message) : await decide(userId, body.requestId, body.decisions);
  return Response.json(reply);
}

"use client";

import { useRef } from "react";
import { ApprovalCard } from "@/components/pixilui/approval-card";
import type { AgentReply, Decision, Prompt } from "../lib/billing-agent";

type Credit = { customer: string; amountUsd: number; reason: string };

export function BillingApprovals({ reply, onReply }: { reply: Extract<AgentReply, { kind: "approval" }>; onReply: (next: AgentReply) => void }) {
  const decisions = useRef<Record<string, Decision>>({});

  async function record(prompt: Prompt, decision: Decision) {
    decisions.current[prompt.decisionId] = decision;
    if (Object.keys(decisions.current).length < reply.prompts.length) return; // wait for the other cards
    const response = await fetch("/api/agent", { method: "POST", body: JSON.stringify({ requestId: reply.requestId, decisions: decisions.current }) });
    if (!response.ok) throw new Error("Not sent"); // the card says nothing changed and offers the buttons again
    onReply((await response.json()) as AgentReply);
  }

  return reply.prompts.map((prompt) => {
    const credit = JSON.parse(prompt.arguments) as Credit;
    return (
      <ApprovalCard
        key={prompt.decisionId}
        title={`Credit $${credit.amountUsd.toFixed(2)} to ${credit.customer}`}
        risk={credit.amountUsd >= 500 ? "high" : "medium"}
        items={[
          { label: "Amount", value: `$${credit.amountUsd.toFixed(2)}`, numeric: true },
          { label: "Reason", value: credit.reason },
        ]}
        source={prompt.toolName}
        labels={{ approve: "Approve credit" }}
        onApprove={() => record(prompt, { approved: true })}
        onReject={(note) => record(prompt, { approved: false, note })}
      />
    );
  });
}