Tutorial: build a support agent

mkdir support-desk && cd support-desk
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install criogenai pytest

mkdir support-desk && cd support-desk
npm init -y
npm pkg set type=module
npm install criogenai
npm install --save-dev tsx typescript @types/node

from typing import Any, Dict

from criogenai import ToolError, tool

# A stand-in for your order database.
ORDERS: Dict[str, Dict[str, Any]] = {
    "A-1001": {"status": "delivered", "total": 48.0},
    "A-1002": {"status": "in transit", "total": 120.0},
}


@tool(read_only=True)
def get_order(order_id: str) -> dict:
    """Look up an order by its id (like A-1001): its status and total."""
    order = ORDERS.get(order_id)
    if order is None:
        # The model sees this message and can ask the customer again.
        raise ToolError(f"No order {order_id}. Ask the customer to check the id.")
    return {"order_id": order_id, **order}


@tool(destructive=True)
def issue_refund(order_id: str, amount: float, reason: str) -> dict:
    """Refund part or all of an order."""
    order = ORDERS.get(order_id)
    if order is None:
        raise ToolError(f"No order {order_id}")
    if not 0 < amount <= order["total"]:
        raise ToolError(f"A refund must be more than 0 and at most {order['total']}")
    return {"order_id": order_id, "refunded": amount, "reason": reason}

import { ToolError, tool } from "criogenai";

// A stand-in for your order database.
const ORDERS: Record<string, { status: string; total: number }> = {
  "A-1001": { status: "delivered", total: 48 },
  "A-1002": { status: "in transit", total: 120 },
};

export const getOrder = tool<{ orderId: string }>({
  name: "get_order",
  description: "Look up an order by its id (like A-1001): its status and total.",
  readOnly: true,
  input: {
    type: "object",
    properties: { orderId: { type: "string" } },
    required: ["orderId"],
  },
  run: ({ orderId }) => {
    const order = ORDERS[orderId];
    // The model sees this message and can ask the customer again.
    if (!order) throw new ToolError(`No order ${orderId}. Ask the customer to check the id.`);
    return { orderId, ...order };
  },
});

export const issueRefund = tool<{ orderId: string; amount: number; reason: string }>({
  name: "issue_refund",
  description: "Refund part or all of an order.",
  destructive: true,
  input: {
    type: "object",
    properties: {
      orderId: { type: "string" },
      amount: { type: "number", exclusiveMinimum: 0 },
      reason: { type: "string" },
    },
    required: ["orderId", "amount", "reason"],
  },
  run: ({ orderId, amount, reason }) => {
    const order = ORDERS[orderId];
    if (!order) throw new ToolError(`No order ${orderId}`);
    if (amount > order.total) throw new ToolError(`A refund must be at most ${order.total}`);
    return { orderId, refunded: amount, reason };
  },
});

from criogenai import Agent, Memory, Storage

INSTRUCTIONS = """You are the support assistant of an online shop.
Look an order up before you answer a question about it.
To refund, call issue_refund: a staff member approves it before it runs.
Save lasting facts about the customer (preferences, past problems) with remember."""


def build_agent(model: Any, storage: Storage) -> Agent:
    return Agent(
        model,
        instructions=INSTRUCTIONS,
        tools=[get_order, issue_refund],
        approve=["issue_refund"],  # pause before every refund
        storage=storage,  # conversations survive restarts
        memory=Memory.by_state("customer_id", "customers"),  # facts per customer
        limits={"model_calls": 12, "tool_calls": 20},
    )

import { Agent, Memory, Storage, type Model } from "criogenai";

const INSTRUCTIONS = `You are the support assistant of an online shop.
Look an order up before you answer a question about it.
To refund, call issue_refund: a staff member approves it before it runs.
Save lasting facts about the customer (preferences, past problems) with remember.`;

export function buildAgent(model: Model, storage: Storage): Agent {
  return new Agent({
    model,
    instructions: INSTRUCTIONS,
    tools: [getOrder, issueRefund],
    approve: ["issue_refund"], // pause before every refund
    storage, // conversations survive restarts
    memory: Memory.byState("customer_id", "customers"), // facts per customer
    limits: { modelCalls: 12, toolCalls: 20 },
  });
}

import asyncio
import sys

from criogenai import Reply, Storage, Thread, load_env
from support_agent import build_agent

load_env()  # OPENAI_API_KEY from .env, if there is one


async def settle_approvals(desk: Thread, reply: Reply) -> Reply:
    """Asks a staff member about every refund the agent wants to make."""
    while reply.needs_approval:
        for request in reply.approvals:
            print(f"  [staff] {request.tool} {request.args}")
        if input("  [staff] approve? y/n > ").strip().lower() == "y":
            reply = await desk.approve()
        else:
            reply = await desk.reject("A staff member declined the refund.")
    return reply


async def main(customer_id: str, ticket_id: str) -> None:
    storage = Storage("sqlite://support.db")
    agent = build_agent("openai:gpt-5-mini", storage)
    chat = agent.thread(ticket_id, actor=f"customer:{customer_id}")
    desk = agent.thread(ticket_id, actor="staff:sam")  # same thread, another person
    try:
        while True:
            text = input("you > ").strip()
            if text in ("", "quit"):
                break
            reply = await chat.send(text, customer_id=customer_id)
            reply = await settle_approvals(desk, reply)
            print("agent >", reply.text)
    finally:
        await storage.close()


if __name__ == "__main__":
    # python support_chat.py <customer id> <ticket id>
    asyncio.run(main(*(sys.argv[1:3] if len(sys.argv) >= 3 else ["c-7", "ticket-1"])))

import * as readline from "node:readline/promises";
import { Storage, loadEnv, type Reply, type Thread } from "criogenai";
import { buildAgent } from "./support_agent.js";

loadEnv(); // OPENAI_API_KEY from .env, if there is one

const terminal = readline.createInterface({ input: process.stdin, output: process.stdout });

/** Asks a staff member about every refund the agent wants to make. */
async function settleApprovals(desk: Thread, reply: Reply): Promise<Reply> {
  while (reply.needsApproval) {
    for (const request of reply.approvals) console.log(`  [staff] ${request.tool}`, request.args);
    const answer = await terminal.question("  [staff] approve? y/n > ");
    reply = answer.trim().toLowerCase() === "y"
      ? await desk.approve()
      : await desk.reject("A staff member declined the refund.");
  }
  return reply;
}

export async function main(customerId: string, ticketId: string): Promise<void> {
  const storage = new Storage("sqlite://support.db");
  const agent = buildAgent("openai:gpt-5-mini", storage);
  const chat = agent.thread(ticketId, { actor: `customer:${customerId}` });
  const desk = agent.thread(ticketId, { actor: "staff:sam" }); // same thread, another person
  try {
    for (;;) {
      const text = (await terminal.question("you > ")).trim();
      if (text === "" || text === "quit") break;
      let reply = await chat.send(text, { state: { customer_id: customerId } });
      reply = await settleApprovals(desk, reply);
      console.log("agent >", reply.text);
    }
  } finally {
    terminal.close();
    await storage.close();
  }
}

// npx tsx support_chat.ts <customer id> <ticket id>
await main(process.argv[2] ?? "c-7", process.argv[3] ?? "ticket-1");

python support_chat.py c-7 ticket-1

npx tsx support_chat.ts c-7 ticket-1

async def send_streaming(chat: Thread, text: str, customer_id: str) -> Reply:
    """send(), printing the answer as it is written."""
    stream = chat.stream(text, customer_id=customer_id)
    print("agent > ", end="", flush=True)
    async for event in stream:
        if event.type == "text":
            print(event.text, end="", flush=True)
        elif event.type == "tool_call_started":
            print(f"[{event.tool}] ", end="", flush=True)
    print()
    return await stream.reply()  # the same saved reply send() returns

/** send(), printing the answer as it is written. */
export async function sendStreaming(chat: Thread, text: string, customerId: string): Promise<Reply> {
  const stream = chat.stream(text, { state: { customer_id: customerId } });
  process.stdout.write("agent > ");
  for await (const event of stream) {
    if (event.type === "text") process.stdout.write(event.text);
    else if (event.type === "tool_call_started") process.stdout.write(`[${event.tool}] `);
  }
  process.stdout.write("\n");
  return stream.reply(); // the same saved reply send() returns
}

import asyncio

from criogenai import FakeModel, FakeReply, Storage
from support_agent import build_agent


def test_a_refund_waits_for_a_person() -> None:
    async def scenario() -> None:
        model = FakeModel([
            FakeReply.tool_call("issue_refund", {"order_id": "A-1001", "amount": 20, "reason": "broken"}),
            "I have refunded 20.",
        ])
        agent = build_agent(model, Storage())  # in memory: nothing left behind
        chat = agent.thread("t-1")

        reply = await chat.send("Please refund 20 on A-1001", customer_id="c-7")
        assert reply.needs_approval
        assert reply.approvals[0].args["amount"] == 20

        reply = await chat.approve()
        assert reply.text == "I have refunded 20."
        assert reply.tool_calls == 1

    asyncio.run(scenario())


def test_an_unknown_order_goes_back_to_the_model() -> None:
    model = FakeModel([FakeReply.tool_call("get_order", {"order_id": "Z-9"}), "Which order?"])
    agent = build_agent(model, Storage())
    result = agent.run_sync("Where is Z-9?", customer_id="c-7")
    tool_message = result.messages[2]
    assert tool_message["status"] == "error"
    assert "No order Z-9" in tool_message["content"][0]["text"]
    assert result.text == "Which order?"

import assert from "node:assert/strict";
import { test } from "node:test";
import { FakeModel, FakeReply, Storage } from "criogenai";
import { buildAgent } from "./support_agent.js";

test("a refund waits for a person", async () => {
  const model = new FakeModel([
    FakeReply.toolCall("issue_refund", { orderId: "A-1001", amount: 20, reason: "broken" }),
    "I have refunded 20.",
  ]);
  const agent = buildAgent(model, new Storage()); // in memory: nothing left behind
  const chat = agent.thread("t-1");

  let reply = await chat.send("Please refund 20 on A-1001", { state: { customer_id: "c-7" } });
  assert.ok(reply.needsApproval);
  assert.equal(reply.approvals[0].args.amount, 20);

  reply = await chat.approve();
  assert.equal(reply.text, "I have refunded 20.");
  assert.equal(reply.toolCalls, 1);
});

test("an unknown order goes back to the model", async () => {
  const model = new FakeModel([FakeReply.toolCall("get_order", { orderId: "Z-9" }), "Which order?"]);
  const agent = buildAgent(model, new Storage());
  const result = await agent.run("Where is Z-9?", { state: { customer_id: "c-7" } });
  const toolMessage = result.messages[2] as { status: string; content: { text: string }[] };
  assert.equal(toolMessage.status, "error");
  assert.match(toolMessage.content[0].text, /No order Z-9/);
  assert.equal(result.text, "Which order?");
});

pytest support_test.py

npx tsx --test support_test.ts