Agent Harness Workshop

📺 Workshop landing · Architecture · Slides · Ramp-up guide

⚠️ Workshop-only — do not deploy to the internet. This repo ships with default credentials baked into the docker-compose files (litellm/litellm, mem0/mem0, miniosecret, myredissecret, mysecret for NEXTAUTH_SECRET, sk-shopharness-workshop master key, etc.) so the local stack runs out of the box. All ports bind to 127.0.0.1 for the same reason. Rotate every secret and harden network exposure before running this on any host reachable from the public internet.

Build a production support agent for ShopHarness, a fake e-commerce company. Each step adds one harness component. By the end you have a complete agent with sandboxing, context engineering, tool access, orchestration, guardrails, memory, cost controls, and observability.

Setup (do this once)

cp .env.example .env            # then edit .env and add your API keys
make setup                      # installs Python deps + seeds the database
make verify                     # checks everything is ready

How to work through this workshop

Everything runs from this project root directory. Do not cd into step folders.

1. Open steps/00-baseline/README.md and read the instructions
2. Run the commands listed there (they all start with uv run python steps/...)
3. When the README says "Next step", open the next folder's README and continue

Each step's README tells you exactly what to run, what to look for, and what you should learn before moving on.

Prerequisites

You need these installed before running make setup:

1. uv (Python package manager): brew install uv
2. Anthropic API key: sign up at https://console.anthropic.com and load ~$5 credits

These are needed from step 05 onwards. You can install them later:

3. Podman: brew install podman (runs Mem0 and Langfuse infrastructure)
4. Ollama: brew install ollama then ollama pull nomic-embed-text (local embeddings)
5. E2B account: sign up at https://e2b.dev with GitHub (free $100 credit, for step 08)

Project Structure

ecommerceSupportAgent/          <-- you are here, always run commands from here
  README.md                     this file
  Makefile                      setup, verify, reset, clean
  pyproject.toml                Python dependencies
  .env.example                  copy to .env, add your keys

  db/                           database
    seed-data.sql                 seed script
    shopharness.db                generated (gitignored)

  docs/                         public site (deployed to GitHub Pages)
    index.html                    workshop landing page
    learn.html                    ramp-up guide
    architecture.html             reference architecture
    deck/                         Reveal.js presentation slides
    assets/                       shared CSS + JS

  tickets/                      test scenarios (6 tickets)
    ticket-01-order-status.md     simple order check
    ticket-02-small-refund.md     $29.99 refund request
    ticket-03-large-refund.md     $899 refund + legal threat
    ticket-04-angry-multi.md      cancel sub + refund, 3rd contact
    ticket-05-social-eng.md       social engineering attempt
    ticket-06-product-question.md warranty question (RAG)

  steps/                        workshop steps (read each README in order)
    00-baseline/                  the broken agent, no harness
    01-context-engineering/       add policies, identity, RAG
    02-tool-access/               add MCP servers for database
    03-orchestration/             add agent loop (Claude Agent SDK)
    04-guardrails/                add safety gates (NeMo Guardrails)
    05-memory/                    add persistent memory (Mem0)
    06-cost-controls/             add model routing and budgets (LiteLLM)
    07-observability-evals/       add tracing + evals (Langfuse)
    08-sandbox/                   add per-ticket isolation (E2B)
    09-complete/                  everything wired together

If You Get Stuck

If you change a file while experimenting and want to restore it:

make reset S=01     # resets step 01 to its original state (uses git)
make reset-all      # resets all steps
make db             # reseeds the database with clean data

Learning Guide

Before starting, or to understand the concepts behind each step, visit the public ramp-up guide — or open docs/learn.html locally in a browser.

Utility Commands

All commands run from the project root:

make setup          install deps + seed database
make verify         check that setup is complete
make db             reseed database to clean state
make reset S=01     reset a step to known-good solution
make clean          remove database and Python cache
make help           show available commands