Customer Support Refund Agent

A hands-on reference implementation of an agentic loop with tool use, structured error handling, and a programmatic escalation hook, built on the Anthropic Messages API with TypeScript. Written as a practice exercise while preparing for the Claude Certified Architect (Foundations) certification.

What it demonstrates

• An agentic loop driven by stop_reason: it continues while the model returns tool_use and stops when the model returns end_turn, rather than parsing text or using an iteration cap as the primary stop condition.
• Tool design with two deliberately similar tools, issue_refund and issue_store_credit, that depend on clear descriptions to be selected correctly.
• Structured tool errors that carry an error category (transient, validation, permission) and a retryable flag, so the loop retries only what is worth retrying and explains business errors to the user.
• A pre-execution hook that intercepts tool calls and blocks refunds above a fixed 500 dollar limit, rerouting them to human escalation. This is deterministic enforcement in code, not a prompt instruction.
• Handling of multi-concern requests in a single pass.

Requirements

• Node.js 18 or newer
• An Anthropic API key

Setup

npm install

Create a .env file in the project root:

ANTHROPIC_API_KEY=your-key-here

Project structure

• src/tools.ts: tool definitions and descriptions, an in-memory order store, structured error helpers, and the tool dispatch with per-tool business rules.
• src/agent.ts: the agentic loop, retry-with-backoff on retryable errors, and the pre-execution escalation hook.
• verify.ts: a deterministic check that calls the tools directly with no model, proving the business rules independently of the agent.

Running

Run the agent:

npx tsx src/agent.ts

Run the deterministic rule check (no API calls, no tokens):

npx tsx verify.ts

Notes on the scaffolding

Some pieces exist only to make behavior observable while learning and are not production code. A one-time fault injection simulates a transient tool failure so the retry path can be seen, the order store is in memory and resets each run, and limits, retry counts, and step caps are named constants rather than external configuration.

Known limitations

• No persistence; the order store is a fixture.
• The escalation hook gates on amount only.
• Retry, limit, and step values are constants, not real configuration.