Customer support agent

You are Acme's support assistant. Answer questions about Acme orders, shipping,
returns and billing, briefly.

- Look up an order before you answer a question about it.
- When you can't help, or the customer asks for a person, open a ticket.

- https://help.acme.com/shipping
- https://help.acme.com/returns

---
refusal: I can only help with questions about your Acme account and orders.
---

Answer questions about Acme orders, billing, shipping and returns. Refuse anything else.

import { Client, Dispatch, type ToolCall } from "@stream-io/stream-agents";
import { z } from "zod";

const agent = new Client().agent("support");

// The user whose turn made the call. It's empty when the router didn't say,
// so refuse those rather than look up orders for nobody in particular.
const customerOf = ({ user }: ToolCall) => {
  if (!user.id) throw new Error("The call doesn't say who the customer is.");
  return user.id;
};

agent.tools.register({
  name: "lookup_order",
  description: "Look up one of the customer's orders",
  parameters: z.object({ order_id: z.string() }),
  run: ({ order_id }, signal, call) => orders.find(order_id, customerOf(call)),
});

agent.tools.register({
  name: "open_ticket",
  description: "Hand the conversation over to the support team",
  parameters: z.object({ summary: z.string() }),
  run: ({ summary }, signal, call) => helpdesk.open(customerOf(call), summary),
});

await new Dispatch().host(agent).run();

import { Tools } from "@stream-io/stream-agents";
import { z } from "zod";

const tools = new Tools().register({
  name: "issue_refund",
  description: "Refund one of the customer's orders",
  parameters: z.object({
    order_id: z.string(),
    summary: z
      .string()
      .describe("the order and the amount, such as Order 1042, $39.90"),
  }),
  displayTitle: "Refunding your order",
  approval: {
    title: "Refund this order?",
    message: "The money goes back to the card the order was paid with.",
    reasonArgument: "summary",
    allowTitle: "Refund",
    declineTitle: "Not now",
  },
  run: async ({ order_id }) => {
    const response = await fetch("/api/refunds", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ order_id }),
    });
    if (!response.ok) throw new Error("The refund didn't go through.");
    return `Refunded order ${order_id}.`;
  },
});

import { api, openConversation, type AgentChat } from "./agent";

async function open(): Promise<AgentChat> {
  const support = api.agent("support");
  // The newest conversation held in writing. Calls are sessions of their own.
  const { items } = await support.sessions.query({
    limit: 1,
    modality: "text",
  });
  const latest = items[0];
  const session = latest
    ? await support.sessions.resume(latest.id, { tools })
    : await support.sessions.create({ tools });
  return openConversation(session);
}

let opening: Promise<AgentChat> | undefined;

/** Opens the support conversation once per page load, however often it's asked. */
export function openSupport(): Promise<AgentChat> {
  opening ??= open().catch((error: unknown) => {
    // A failed open can be tried again.
    opening = undefined;
    throw error;
  });
  return opening;
}

import {
  type FormEvent,
  useEffect,
  useMemo,
  useState,
  useSyncExternalStore,
} from "react";
import { Chat } from "stream-chat-react";
import {
  AIClientIdentity,
  AIConversation,
  AIMessageComposer,
  AISuggestions,
  type AIMessageRating,
  type AIToolApprover,
} from "stream-chat-react/ai-components";

import { api, type AgentChat } from "./agent";
import { openSupport } from "./support";
import { useAgentMessages } from "./useAgentMessages";
// The call view of the Voice agent use case.
import { VoiceAgent } from "./VoiceAgent";

const starters = [
  "Where is my order?",
  "I want to return an item",
  "Talk to a person",
];

export const SupportPage = () => {
  const [chat, setChat] = useState<AgentChat>();
  const [failure, setFailure] = useState<string>();

  useEffect(() => {
    openSupport().then(setChat, (error: unknown) =>
      setFailure(error instanceof Error ? error.message : String(error)),
    );
  }, []);

  if (failure) return <p role="alert">{failure}</p>;
  return chat ? <SupportConversation chat={chat} /> : null;
};

const SupportConversation = ({ chat }: { chat: AgentChat }) => {
  const { session, client, channel } = chat;
  const messages = useAgentMessages(channel);
  const [ratings, setRatings] = useState<Record<string, AIMessageRating>>({});
  const [failure, setFailure] = useState<string>();
  // The router refuses a question while the agent is still answering one.
  const { kind } = useSyncExternalStore(
    session.state.subscribe,
    session.state.get,
  );
  const isAnswering = kind === "responding" || kind === "working";

  const approver = useMemo<AIToolApprover>(
    () => ({
      userId: client.userId ?? "",
      clientId: AIClientIdentity.installId(),
      decide: async (call, allowed) => session.decide(call.id, { allowed }),
    }),
    [client, session],
  );

  // Resolves once the agent starts answering. Says so if the question was refused.
  const ask = async (text: string) => {
    setFailure(undefined);
    try {
      await session.responses.create(text);
      return true;
    } catch (error) {
      setFailure(error instanceof Error ? error.message : String(error));
      return false;
    }
  };

  const rate = (messageId: string, rating: AIMessageRating | null) =>
    setRatings(({ [messageId]: _, ...rest }) =>
      rating ? { ...rest, [messageId]: rating } : rest,
    );

  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    // The draft waits until the reply is done, as the send button does.
    if (isAnswering) return;
    const form = event.currentTarget;
    const text = new FormData(form).get("message");
    if (typeof text !== "string" || !text.trim()) return;
    // Cleared once it's sent, so a refused question stays in the composer.
    void ask(text.trim()).then((sent) => sent && form.reset());
  };

  return (
    <Chat client={client}>
      {/* `str-chat` is the SDK's theme scope: its fonts, colors and spacing. */}
      <div className="str-chat support">
        <aside className="support-call">
          <VoiceAgent agent="support" api={api} />
        </aside>
        <div className="support-conversation">
          <AIConversation
            approver={approver}
            emptyContent={
              <AISuggestions
                onSelect={(text) => void ask(text)}
                suggestions={starters}
              />
            }
            messages={messages}
            replyActions={(message) => ({
              rating: ratings[message.id] ?? null,
              onRate: (rating) => rate(message.id, rating),
            })}
          />
        </div>
        <div className="support-composer">
          {failure && <p role="alert">{failure}</p>}
          <AIMessageComposer onSubmit={handleSubmit}>
            <AIMessageComposer.TextInput placeholder="Ask about an order" />
            <div className="support-composer__actions">
              <AIMessageComposer.SubmitButton />
            </div>
          </AIMessageComposer>
        </div>
      </div>
    </Chat>
  );
};