Library / 04 Quality, Evals & Reliability
Reviewed Oct 2026Debugging Claude-Based AI Agents
Turn a vague customer complaint into reproducible evidence and a verified outcome.
01 / flow
Debug from source to answer
Customer requestContext + retrievalInstructions + modelTool call + resultInterpretationFinal answer
02 / note
Order status example
Customer asks whether an order shipped. Tool returns “label created”; agent says “Yes.” The first wrong layer is interpreting label creation as carrier possession.
03 / table
Failure source → inspection
| Layer | What to check |
|---|---|
| Request | Exact wording and missing identifiers |
| Instructions | Written rules, conflicts, stale examples |
| Conversation context | Prior turns and first context drift |
| Retrieval | Sources used, relevance, dates and access |
| Tools | Selected tool, arguments, raw results and timeouts |
| Permissions | Identity, scopes and approval requirements |
| Model output | Certainty, tone, compliance and evidence |
| Operations | Retries, loops, latency, errors and usage |
04 / flow
Practical investigation
Expected behaviorExact actual behavior + IDsAssess impactRead traceLocate first divergenceReproduce safelyRoute ownerRegression + customer update
05 / table
Fix ownership
| Owner | Likely responsibility |
|---|---|
| Customer success | Capture reproducible evidence, impact and follow-up |
| Engineering | Fix code, tools, routing, instrumentation |
| Security / policy | Permission or privacy determinations |
| PM | Prioritization, acceptable tradeoffs and quality bars |
06 / list
Close the loop
- Original request and paraphrases pass
- Nearby statuses / failure cases pass
- Correct permissions and customer identity verified
- Monitoring or owner identified
- Customer is told the verified outcome
GOING DEEPER
Field debugging: evidence, safety, and handoff
At first report: capture a usable issue packet
| Field | What to capture |
|---|---|
| Expected vs actual | Exact customer request, approved source-of-truth rule, the answer/action the agent gave |
| Scope and urgency | Customer impact, scale, severity, account conditions, workaround, privacy or financial risk |
| Traceability | Environment/version, time, request or conversation ID, trace ID, model, permitted tool calls |
| Reproduction | Safe minimal steps with the same input; change one condition at a time |
| Diagnosis and route | First observed divergence, candidate owner, evidence supporting the hypothesis |
| Closure | Exact-case retest, paraphrases, nearby boundaries, customer update, monitoring owner |
Symptom → first place to inspect
| Symptom | First check |
|---|---|
| Wrong fact | Retrieved source, tool result, data age and status definitions |
| Wrong action | Tool chosen, arguments, user scope, approval and permissions |
| No action | Tool discoverability, missing input, permission denial or tool error |
| Confident guess | Unknown-data handling, instructions and escalation |
| Slow or costly | Timing by step, repeated tools, context volume, retries and provider latency |
| Looping | Stop rules, retry count, repeated results and safe escalation |
Regression case categories
| Case | Purpose |
|---|---|
| Positive | Agent may answer or act on sufficiently established facts |
| Negative / no-action | Agent should abstain rather than make up an answer or mutate state |
| Paraphrase | Same intent written differently should retain meaning |
| Boundary and missing context | Ambiguity, missing identifiers, stale results and close status values |
| Permission / failure | Denied access, timeout, empty result and proper fallback |
MCP: what it is and is not: Model Context Protocol (MCP) is a standard interface between an AI host and tools/resources. An MCP host/application uses an MCP client to connect to an MCP server, which exposes capabilities backed by a CRM, database or document system. The server is not the model and does not replace application-level permissions. Check both tool descriptions and actual server results when debugging.
Stop and escalate: Escalate possible data exposure, unauthorized account changes, payment/refund harm, security abuse, repeated unsafe actions or a high-volume production incident immediately; do not independently change production tools, permissions, prompts, records or payment logic.
Ownership boundary: Customer Success owns customer context, evidence, safe reproduction, validation and communication; product defines intended behavior and release tradeoffs; engineers own changes to implementation, tools and instrumentation; security owns access policy and incidents; operations owns availability and rollback.