Cody Borders 30cdea2aac Build Bookly customer support agent

A FastAPI + vanilla JS chat app fronting an Anthropic Claude agent for
order status, returns, and policy questions.

Architecture:
- agent.py: system prompt, runtime reminder injection, output validation,
  agentic tool-use loop with prompt caching on the system prompt block
- tools.py: four tools (lookup_order, check_return_eligibility,
  initiate_return, lookup_policy) with per-session SessionGuardState
  enforcing protocol ordering on the tool side
- mock_data.py: orders, return policy, and FAQ entries used as the single
  source of truth by both the prompt and the tools
- server.py: FastAPI app exposing /api/chat, /health, and the static UI
- static/: vanilla HTML/CSS/JS chat UI, no build step
- tests/: 30 tests covering tool-side enforcement, the privacy boundary,
  output validation, and the agent loop with a mocked Anthropic client
- deploy/: systemd unit and nginx site config for production

2026-04-14 22:17:59 -07:00

1.5 KiB

Raw Blame History

Bookly

A conversational customer support agent for a fictional online bookstore.

The agent handles two depth use cases (order status and returns) and one breadth use case (policy questions) over a vanilla HTML chat UI, backed by Anthropic Claude with a four-layer guardrail strategy. The full agent design rationale lives in DESIGN.md.

Stack

Python 3.11+, FastAPI, Uvicorn
Anthropic Claude (Sonnet) with prompt caching
Vanilla HTML / CSS / JS chat frontend (no build step)
Pytest

Setup

python3 -m venv venv
./venv/bin/pip install -r requirements.txt
cp .env.example .env
# edit .env and set ANTHROPIC_API_KEY

Run locally

./venv/bin/uvicorn server:app --host 127.0.0.1 --port 8014

Then open http://127.0.0.1:8014 in a browser.

Tests

./venv/bin/python -m pytest tests/ -v

Tests mock the Anthropic client, so no API key or network access is required.

Project layout

agent.py        System prompt, guardrails (layers 1, 2, 4), agentic loop
tools.py        Tool schemas, handlers, SessionGuardState (layer 3)
mock_data.py    Orders, return policy, FAQ policies
server.py       FastAPI app: /api/chat, /health, static mount
config.py       pydantic-settings config loaded from .env
static/         index.html, style.css, chat.js
tests/          test_tools.py, test_agent.py
deploy/         systemd unit + nginx site config for the production droplet

Design

See DESIGN.md for the architecture, conversation design, hallucination and safety controls, and production-readiness tradeoffs.

1.5 KiB Raw Blame History