OpenAI Agents SDK

npm install @openai/agents samva zod

import { tool } from "@openai/agents";
import { MailboxSendConflictError, WhatsAppServiceWindowClosedError } from "samva";
import { z } from "zod";

// Set before any await: a model can call both tools in one turn, and the calls run together.
let claimed = false;

const replyToCustomer = tool({
  name: "reply_to_customer",
  description:
    "Submit a reply to the customer's message. A person at the business approves it before it is sent.",
  parameters: z.object({ text: z.string().min(1).describe("The plain-text reply.") }),
  // A failed request stops the turn instead of going back to the model as text.
  errorFunction: null,
  execute: async ({ text }) => {
    if (claimed) return "You already finished this message. Do not call again.";
    claimed = true;
    // Without channel: "whatsapp", Samva treats the reply as email and rejects a WhatsApp thread.
    const reply =
      received.channel === "whatsapp"
        ? {
            id: received.mailboxId,
            messageId: received.messageId,
            channel: "whatsapp" as const,
            text,
          }
        : { id: received.mailboxId, messageId: received.messageId, text };
    try {
      const receipt = await samva.mailboxes.reply(reply, { idempotencyKey: `reply:${eventId}` });
      return `Submitted: ${receipt.state}.`;
    } catch (error) {
      if (error instanceof MailboxSendConflictError) {
        log(
          `already answered ${received.messageId}: ${error.receipt.state}, action ${error.receipt.actionId}`,
        );
        return "Already answered.";
      }
      if (error instanceof WhatsAppServiceWindowClosedError) {
        log(`skipped ${received.messageId}: WhatsApp service window closed`);
        return "Not sent: the WhatsApp service window is closed.";
      }
      throw error;
    }
  },
});

const leaveForPerson = tool({
  name: "leave_for_person",
  description:
    "Send nothing and leave this message for a person. Use it when the business instructions do not cover the question or the message is not a customer asking for help.",
  parameters: z.object({
    reason: z.string().min(1).describe("One short sentence for the person."),
  }),
  execute: async ({ reason }) => {
    if (claimed) return "You already finished this message. Do not call again.";
    claimed = true;
    log(`left ${received.messageId} for a person: ${reason}`);
    return "Left for a person.";
  },
});

import { Agent, Runner } from "@openai/agents";

const runner = new Runner({ traceIncludeSensitiveData: false });

for await (const event of samva.mailboxes.events({ cursor, mailboxIds: [mailboxId] })) {
  if (event.type === "mailbox.message.received") {
    const received = parseReceivedMessage(event.data);
    if (received === undefined) throw new Error(`Malformed event ${event.id}`);

    const agent = new Agent({
      name: "Mailbox agent",
      instructions: systemPrompt(instructions),
      model: "gpt-5.6-sol",
      modelSettings: { reasoning: { effort: "low" }, parallelToolCalls: false },
      tools: mailboxTools(samva, received, event.id, log),
      // The tool's result is the end of the turn, so the model is not called again to summarize it.
      toolUseBehavior: "stop_on_first_tool",
    });

    await runner.run(agent, userTurn(received), { maxTurns: 2 });
  }
  await saveCursor(event.cursor);
}