Customer Support Agent

The brief advanced

Picture the support inbox at 9am on a Monday. Two hundred tickets waiting, and if you actually read them you'd notice something deflating: the same handful of questions, over and over. "How do I reset my password?" "Where's my order?" "How do I change my plan?" A human agent spends the first hours of the day retyping answers that are already written down in the help center — while the genuinely tricky ticket, the angry enterprise customer, waits in the same queue behind the trivia.

That is the shape of the problem, and it's worth being precise about the job before you build anything. The brief is not "replace support." It's the far narrower, far more valuable "deflect the repetitive so humans get the hard cases sooner." Think of a good triage nurse: they don't treat everyone, they route — sending the sprained ankle to the fast lane and rushing the chest pain to a doctor. The value isn't in answering every question; it's in answering the easy, well-documented ones instantly and correctly, and knowing — reliably — which ones aren't easy. Why frame it this way and not "an AI that handles support"? Because the moment you promise to handle everything, you've promised the agent will answer questions the docs don't cover — which is exactly where it invents a confident, wrong answer in front of a paying customer. Scoping the brief to "the repetitive, documented tickets" is the first safety decision, made before a single line of code. The common mistake is optimizing for deflection rate alone: a bot that answers 95% of tickets by guessing on the 30% it shouldn't have touched is worse than one that answers 65% cleanly and escalates the rest.

"Deflect the repetitive support tickets so agents handle only what needs a human." Most support volume is the same few dozen questions answered in the docs. An agent that resolves those instantly — accurately, with sources, and knowing when to escalate — cuts response time and frees humans for the hard cases.

1 · Discovery — where does support time go? advanced

Here's the trap that kills most support-bot projects: building for the tickets you imagine instead of the ones you actually have. A team excited about AI will build a dazzling conversational agent that reasons about complex edge cases — and then discover that 70% of real tickets are "I forgot my password" and the agent's clever reasoning was solving a problem nobody had. Discovery is the unglamorous step that stops you building the wrong thing.

The move is simple and you can do it in an afternoon: pull the last few hundred real tickets and sort them into buckets by where the human time actually went. You're looking for two signals at once — volume (which buckets are big?) and agent leverage (which of those can a grounded bot safely handle?). The sweet spot is the intersection: high-volume and highly documented. Answering repeat "how do I…" questions from the help center is the jackpot — huge volume, and the answer already exists in text a RAG system can cite. Genuinely novel, angry, or high-stakes issues are the opposite corner: low leverage, and the right design decision is to hand them straight to a human. The table below is that sort already done for a typical support desk; read the star ratings as "how much of this can we safely automate," not "how clever can the AI be." The point isn't to automate the hardest thing — it's to automate the highest-volume thing you can do safely, and route the rest.

2 · Architecture advanced

The failure this architecture is designed to prevent looks like this: a customer asks a question the docs don't answer, the model — trained to be helpful — cheerfully makes something up, and it ships straight to the customer with total confidence. No error, no warning, just a wrong answer that erodes trust and maybe creates a support ticket about the support bot. Everything in the diagram below exists to make that outcome structurally impossible rather than merely unlikely.

Read the architecture as a pipeline with two exits, not a chatbot. A message enters on the left and can only leave through one of two doors on the right: a cited, resolved answer or a clean handoff to a human. Everything between those points is a series of checkpoints. First a guardrail strips personal data and abuse before the model ever sees the text — like a mailroom that opens and screens the envelope before it reaches your desk. Then the agent, standing on top of RAG over the help center, drafts an answer only from retrieved documents. The crucial box is the confidence gate underneath: it inspects the draft and decides which of the two exits to take. Why put the gate in its own box instead of trusting the model to "know when it's unsure"? Because a language model's stated confidence is just more generated text — it can be confidently wrong. The gate is code you control, checking two hard facts: is the confidence above the bar, and is every claim backed by a real retrieved doc? If either fails, the message takes the human exit. The tools on the right (order lookup, ticket CRUD, draft reply) are actions the agent can take, but notice they're deliberately read-only or reversible — no "send to customer" without a gate. The mental model to carry: the model proposes, your code disposes.

The Chapter 4 agent, grounded by Chapter 3 RAG over your help center, with a confidence gate that routes low-confidence or high-stakes conversations to a human instead of guessing.

3 · Risk & safety model advanced

When people think "AI safety" they picture the dramatic failure — the agent deletes the production database. A support agent almost never has that power; its dangers are quieter and, in their own way, more corrosive. The nightmare here isn't an explosion, it's a confident lie: the bot tells a customer their refund is processed when it isn't, or serves up someone else's order history because a clever prompt talked it into it. Nothing crashes. The damage is to trust, and it compounds.

So the discipline is to enumerate the risks that actually apply to this class of agent and pin a concrete control to each — the same way an airline doesn't just say "be safe," it has a checklist item for every failure mode. Think of the controls as belonging to two families. Some are about truth: hallucination is caught by answering only from retrieved docs and refusing when unsupported; prompt injection is neutralized by treating all customer text as untrusted data that can never rewrite the agent's instructions. Others are about authority: data leaks are prevented by filtering every lookup on the authenticated customer id in code, and irreversible actions (sending a reply, issuing a refund) start life as human-approved drafts. The pattern that unifies every row of the table below: never let the model be the thing enforcing the rule. The model suggests; a deterministic piece of code — the tenant filter, the confidence gate, the draft-only default — actually enforces. A rule the model "promises" to follow in its prompt is a rule an adversarial customer can talk it out of; a rule enforced in code is one it physically cannot break.

Support's risks aren't "delete prod" — they're wrong answers stated confidently, leaking another customer's data, and mishandling an upset customer. The controls:

4 · Tool surface advanced

The most tempting mistake in agent design is to hand the model one giant "do anything" tool and hope it behaves. It won't — or rather, it will right up until an edge case or a crafted prompt makes it send the wrong customer a refund. The tool surface is where you decide, up front and in code, the exact set of actions your agent is capable of. Anything not on this list is something the agent simply cannot do, no matter how it's prompted.

The useful way to design a tool surface is to think like someone handing out keys to a building. A janitor gets the closet key, not the vault key; a teller gets the drawer, not the safe. You classify each tool by the blast radius of its worst outcome and grant accordingly. Read the risk column in the table below as that classification. Read-only, scoped tools (search_kb, get_order_status) are the safest — they can reveal information but change nothing, and the scoped ones only ever see the authenticated customer's own data. Reversible tools (draft_reply, create_ticket) can be undone if wrong, so they're a middle tier. Then there's the one genuinely dangerous action — send_reply, which puts words in front of a real customer — and notice it's gated: human-approved by default, auto-send reserved only for questions a proven eval says are safe. Finally, escalate is the deliberate escape hatch, always safe to call, because "get a human" is never the wrong move. Why enumerate and rank rather than just give the agent capabilities? Because an explicit, ranked tool surface is a contract you can audit and test: you can point at send_reply and prove in code that it can't fire without approval. A vague "the agent can respond to customers" gives you nothing to test and nothing to defend when it misbehaves.

5 · Knowledge — RAG done right advanced

Every support agent that gives a wrong answer has the same root cause, and it's almost never the model. It's retrieval. The model faithfully answered from the passages it was given — but the right passage never made it into that context, so the model filled the gap from its own memory, or the passage it did get was stale. In a RAG-first project like this one, retrieval quality is answer quality. You can have the best model on earth and still ship garbage if it's grounded in the wrong three paragraphs.

The mental picture worth holding: the model is only as good as the open book you hand it. If you hand a brilliant student the wrong page of the textbook, you get a confident wrong answer — the student isn't the problem, the page is. So "RAG done right" is a set of levers that each fix a specific way the wrong page gets handed over. Chunking on article sections keeps each retrieved piece self-contained and carries the title and URL so the answer can cite its source. Hybrid search exists because customers don't behave like one kind of searcher — they paste exact error codes and product names (which keyword search nails) and they paraphrase in their own words (which vector search catches); running only one leaves half your customers unmatched. Re-ranking to the best 3–4 passages fights the opposite problem — feeding the model ten loosely-related chunks buries the signal in noise. Citing every claim is what turns the whole thing verifiable: a customer, or a reviewing human, can click through and check. And freshness is the one people forget until it burns them — a support answer pulled from a doc that changed last week is a wrong answer, so re-indexing on doc change isn't optional hygiene, it's correctness. The through-line: get the right, current passage in front of the model with a source attached, and most "the AI hallucinated" bugs simply never happen.

This is a RAG-first project, so the Chapter 3 quality levers are the product quality:

• Chunk the help center on article sections; keep the article title + URL as metadata for citations.
• Hybrid search — customers use product names and error codes (keyword) and paraphrase (vector).
• Re-rank to the best 3–4 passages before answering.
• Cite every claim with the source article link — so the customer (and a reviewing human) can verify.
• Freshness — re-index when docs change; a stale answer is a wrong answer.

6 · Evaluation expert

"It seemed to work when I tried it" is how every support-bot disaster begins. You demo a dozen questions, they all look great, you ship — and three weeks later someone shows you the transcript where it confidently told a customer the wrong return policy. The problem with eyeballing a demo is that it tests the questions you thought of, in a good mood, not the long tail of weird phrasings and out-of-scope asks real customers throw at it. Evaluation is what replaces "seemed fine" with a number you can trust.

The key insight is that a support agent has to be graded on two different kinds of correctness, and confusing them is a classic mistake. The first is the obvious one: when it answers, is the answer good — grounded in a cited doc (measured by an LLM-judge), relevant to what was actually asked, and did retrieval even surface the right article (recall@k)? But the second kind is what separates a safe agent from a dangerous one: did it escalate the things it should have, rather than guessing? That's escalation precision, and it's easy to game — an agent that answers everything scores 100% on "resolution" while quietly being a liability. Think of it like a medical test: you care about false positives and false negatives, not just overall accuracy, because the two errors have wildly different costs. A needless escalation wastes a few minutes of a human's time; a confident wrong answer on a billing question damages the customer relationship. That asymmetry is why the last two rows below are deterministic hard-fails, not scored metrics — "never answer outside the docs" and "never leak another customer's data" must be exactly zero, checked in code, gating the build the way a smoke detector doesn't get graded on a curve. The rule: measure answer quality and escalation quality separately, and make the safety properties pass/fail rather than best-effort.

7 · Phased rollout expert

The most expensive way to launch a support agent is to flip it on for every customer at once. If it's subtly wrong, you find out from a wave of complaints instead of a dashboard — and you've spent your one shot at customer trust before you had any evidence the thing works. The alternative isn't slower for its own sake; it's how you buy evidence before you buy risk.

The right shape is a ladder from suggestion to autonomy, where each rung earns the next by producing data. Think of how you'd onboard a new human support hire: they don't answer customers unsupervised on day one. First they draft replies a senior agent reviews and sends (Phase 1) — which, as a bonus, generates a golden set of "here's what a good answer looks like" you can later evaluate against. Once their drafts on the easy questions are consistently good, you let them auto-handle just those well-covered FAQs while everything else still routes to a human (Phase 2). Only after that track record do they take first contact and escalate what they can't handle (Phase 3). Why climb instead of leap? Because each rung is reversible and observable: if Phase 2's auto-answers start drifting, you drop back to Phase 1 having harmed no one. The rungs also map cleanly onto the course chapters — trust is built with the RAG and structured-output work, gated by evals, and hardened before it ever runs unsupervised. And note the final "Never" rung isn't a phase at all — it's the permanent fence: some things (arguing, unapproved refunds, answering outside the KB) stay off-limits at every level of autonomy, forever. The mistake to avoid is treating rollout as a switch instead of a ladder — autonomy is something you earn per question type, backed by numbers, not something you grant wholesale on launch day.

Skills & course map expert

Build-along plan expert

1. Ch 3 base: index a real help center (or sample docs), get cited answers working, prove it refuses on out-of-KB questions.
2. Add a confidence field (Ch 2 Pydantic) and route confidence < threshold → escalate.
3. Add tools (Ch 4): a mock order-lookup (ID-filtered), draft_reply, escalate.
4. Evals (Ch 5): a golden set of real questions; measure groundedness + escalation precision; add the no-PII-leak hard-fail.
5. Harden (Ch 6): PII redaction, tenant scoping in code, logging, then pilot in draft mode.

What you'll build expert

A support agent that answers only from your KB with citations, escalates when unsure, and can look up a customer's own orders — never another's. It's a single structured call (Tier 1) plus a code-enforced safety gate.

Step 1 · Skeleton & the answer schema expert

terminalcd llm-course-starter && source .venv/bin/activate
mkdir -p support-agent/{agent,kb,tests}
cd support-agent && touch agent/__init__.py

agent/schemas.pyfrom typing import Literal, Optional
from pydantic import BaseModel, Field

class SupportAnswer(BaseModel):
    answer: str
    citations: list[str] = Field(default_factory=list)
    confidence: float = Field(ge=0.0, le=1.0)
    action: Literal["answer", "escalate"]
    escalation_reason: Optional[str] = None

Step 2 · KB retrieval (RAG grounding) expert

class _Any:
    '''stands in for any undefined demo value; supports call/attr/index/
    iteration and basic arithmetic (as 0.7) so demo snippets run.'''
    def __call__(self, *a, **k): return _Any()
    def __getattr__(self, k): return _Any()
    def __getitem__(self, k): return _Any()
    def __iter__(self): return iter([])
    def __len__(self): return 0
    def __contains__(self, o): return True
    def __enter__(self, *a): return _Any()
    def __exit__(self, *a): return False
    def __float__(self): return 0.7
    def __int__(self): return 1
    def __lt__(self, o): return True
    def __gt__(self, o): return False
    def __le__(self, o): return True
    def __ge__(self, o): return False
    def __add__(self, o): return o
    def __radd__(self, o): return o
    def __bool__(self): return True
    def __repr__(self): return 'demo'
    def __str__(self): return 'demo'
def retrieve(*a, **k):  # demo stub
    return _Any()

agent/kb.py (core)def context_for(query):
    hits = retrieve(query)                     # top-k by keyword overlap
    if not hits:
        return "(no relevant KB article found)", []
    ctx = "\n\n".join(f"[{c['id']}] {c['text']}" for c in hits)
    return ctx, [c["id"] for c in hits]   # ctx for the prompt, ids for the gate

terminalpython agent/kb.py       # no API key needed

cited: ['kb-1']
Resetting your password. Go to Settings > Security...

Step 3 · Tenant-scoped lookup (the data-leak guard) expert

agent/accounts.py_ORDERS = {"cust-1": [...], "cust-2": [...]}

def get_orders(customer_id: str):
    """ONLY this customer's orders. Unknown id -> empty list."""
    return _ORDERS.get(customer_id, [])       # filtered in CODE, not by the model

Step 4 · The agent + the safety gate expert

agent/engine.py (the gate)ans = resp.parsed_output                        # what the model returned

# enforce in code — never trust the model's self-assessment alone
grounded = bool(ans.citations) and all(c in available_ids for c in ans.citations)
if ans.confidence < CONFIDENCE_THRESHOLD or not grounded:
    return SupportAnswer(answer="", action="escalate", ...,
        escalation_reason="low confidence" if ... else "not grounded")
return ans

terminalpython agent/engine.py       # needs ANTHROPIC_API_KEY

Q: How do I reset my password?
A: Go to Settings > Security and click "Reset password"...  [cites: kb-1]  conf=0.95

Q: Can you write me a poem about ducks?
ESCALATE (no relevant KB article)  conf=0.00

5 · Tests (no API key) expert

These tests exercise the two safety-critical seams directly — the retriever and the tenant guard — with the model replaced by a test double, so the whole guard runs without an API key. A request is checked, then routed to an allowed or blocked outcome.

terminalpython -m pytest tests/ -v

test_kb_retrieves_password_article PASSED
test_kb_returns_nothing_for_offtopic PASSED
test_tenant_isolation PASSED
test_unknown_customer_gets_nothing PASSED
4 passed

6 · Evals (needs key) expert

Evals run a fixed golden set of real questions through the live agent, score each verdict against the expected outcome, and gate the build: it passes only if answer accuracy and escalation safety clear the bar — and hard-fails the instant it answers anything outside the KB.

terminalpython evals.py

[PASS] answer   How do I reset my password?
[PASS] escalate Do you integrate with SAP?
answer accuracy:   3/3
escalation safety: 2/2
✅ evals passed

Troubleshooting expert

from dataclasses import dataclass, field

@dataclass
class SupportAnswer:
    answer: str
    action: str                       # 'answer' | 'escalate'
    confidence: float = 0.0
    citations: list = field(default_factory=list)
    escalation_reason: str = None
    def __post_init__(self):
        assert self.action in ("answer", "escalate")
        assert 0.0 <= self.confidence <= 1.0

ok = SupportAnswer("Your plan renews monthly.", "answer", 0.9, ["kb1"])
print(ok.action, ok.citations)          # answer ['kb1']
try: SupportAnswer("x", "answer", confidence=1.5)
except AssertionError: print("rejected bad confidence")

import re
def toks(s): return set(re.findall(r"[a-z0-9]+", s.lower()))
KB = {"kb1": "Plans renew on the first of each month.",
      "kb2": "Refunds are issued within 30 days."}

def retrieve(query, k=2):
    q = toks(query)
    scored = sorted(KB, key=lambda i: len(q & toks(KB[i])), reverse=True)
    return [i for i in scored[:k] if q & toks(KB[i])]

def context_for(query):
    hits = retrieve(query)
    if not hits: return "(no relevant KB article found)", []
    ctx = "\n\n".join(f"[{i}] {KB[i]}" for i in hits)
    return ctx, hits

ctx, ids = context_for("when does my plan renew")
print(ids)                 # ['kb1']
print(context_for("weather"))   # ('(no relevant KB article found)', [])

_ORDERS = {
    "cust-1": [{"id": "o1", "item": "Widget"}],
    "cust-2": [{"id": "o2", "item": "Gadget"}],
}
def get_orders(customer_id):
    return _ORDERS.get(customer_id, [])       # filtered in CODE

print(get_orders("cust-1"))       # [{'id': 'o1', ...}]
print(get_orders("cust-2"))       # [{'id': 'o2', ...}] -- never cust-1's
print(get_orders("attacker"))     # [] -- unknown id leaks nothing

from dataclasses import dataclass, field
@dataclass
class SupportAnswer:
    answer: str; action: str; confidence: float = 0.0
    citations: list = field(default_factory=list); escalation_reason: str = None

def gate(ans, available_ids, min_conf=0.6):
    grounded = bool(ans.citations) and all(c in available_ids for c in ans.citations)
    if ans.confidence < min_conf or not grounded:
        return SupportAnswer("", "escalate", ans.confidence, [],
            escalation_reason="low confidence" if ans.confidence < min_conf
                              else "not grounded")
    return ans

avail = ["kb1", "kb2"]
good = SupportAnswer("Renews monthly.", "answer", 0.9, ["kb1"])
bad  = SupportAnswer("Made up.", "answer", 0.9, ["kb9"])   # invented citation
print(gate(good, avail).action)                       # answer
print(gate(bad, avail).action, gate(bad, avail).escalation_reason)  # escalate not grounded

class Support:
    def __init__(self, fail_max=2):
        self.cache = {}; self.fails = 0; self.fail_max = fail_max
    def handle(self, req_id, msg, model):
        if req_id in self.cache:                 # idempotent replay
            return self.cache[req_id]
        if self.fails >= self.fail_max:          # circuit OPEN
            return {"action": "escalate", "reason": "circuit open"}
        try:
            result = {"action": "answer", "answer": model(msg)}
            self.fails = 0
        except Exception:
            self.fails += 1
            result = {"action": "escalate", "reason": "model error"}
        self.cache[req_id] = result
        return result

def flaky(msg): raise RuntimeError("down")
s = Support(fail_max=2)
print(s.handle("r1", "hi", flaky)["reason"])   # model error
s.handle("r2", "hi", flaky)
print(s.handle("r3", "hi", flaky)["reason"])   # circuit open -- fast escalate
print(s.handle("r1", "hi", flaky)["reason"])   # model error -- cached replay, not re-run

# --- real structured call (needs creds / API key — Claude OR OpenAI) ---
# from pydantic import BaseModel
# class SupportAnswer(BaseModel):
#     answer: str; citations: list[str]; confidence: float; action: str
#
# Claude (Anthropic):
# import anthropic
# client = anthropic.Anthropic()
# def ask(msg, context):
#     r = client.messages.parse(model="claude-opus-4-8", max_tokens=400,
#         system="Answer only from context; cite article ids; set action.",
#         messages=[{"role":"user","content":f"{context}\nQ: {msg}"}],
#         output_format=SupportAnswer)
#     return r.parsed_output
#
# OpenAI: same SupportAnswer model, Responses API structured parse:
# from openai import OpenAI
# client = OpenAI()
# def ask(msg, context):
#     r = client.responses.parse(model="gpt-5.5", max_output_tokens=400,
#         instructions="Answer only from context; cite article ids; set action.",
#         input=f"{context}\nQ: {msg}", text_format=SupportAnswer)
#     return r.output_parsed

# --- offline eval harness (runnable) ---
EVALS = [
    ("when does my plan renew", "answer"),   # in KB -> should answer
    ("can I sue you",           "escalate"),  # not in KB -> should escalate
]
def mock_agent(q):
    kb = {"plan", "renew"}
    hit = bool(kb & set(q.lower().split()))
    return "answer" if hit else "escalate"

correct = sum(1 for q, want in EVALS if mock_agent(q) == want)
print(f"escalation accuracy: {correct}/{len(EVALS)}")   # 2/2

Knowledge check check yourself