Design, Build & Deploy an End-to-End Agentic AI System

Before you write any code you build a clean, isolated workspace. These commands make a project folder, create a private Python virtual environment just for this project, turn it on, and install the libraries the app needs. Doing this first keeps this project's packages from colliding with anything else on your machine.

1. mkdir -p end-to-end/tests makes the project folder and a tests sub-folder in one go (-p means "create parents, don't complain if they exist"). cd end-to-end moves you inside it — every later step assumes you are in this folder.
2. python3 -m venv .venv creates a virtual environment — a private copy of Python living in a hidden .venv folder. source .venv/bin/activate switches your terminal to use it (Windows uses the .ps1 line instead). Your prompt then shows (.venv) so you know it's on.
3. pip install ... downloads the four libraries the app uses: fastapi (the web framework), uvicorn (the server that runs it), httpx + pytest (used by the tests), and anthropic (the Claude SDK, for when you later go real).
4. pip freeze > requirements.txt writes the exact installed versions into a file, so anyone else — including the Docker image in Step 5 — can recreate the same setup.

What the output means: A success line like Successfully installed fastapi uvicorn .... The leading (.venv) confirms the environment is active — if you don't see it, the next steps will fail with "command not found".

Try this: Close the terminal and open a new one, then run uvicorn --version. It will fail until you re-run source .venv/bin/activate — that's the whole point of an environment: it's per-terminal, so you always re-activate before working.

This is the heart of the capstone: one file that wires together four ideas you met earlier — a safety guardrail, scoped retrieval, a gated action tool, and a trace log — behind a single handle() method. Read it as a pipeline: a message comes in at the top of handle and flows down through each check in a deliberate order.

1. The setup at the top: TRACE = [] is a running log of what happened (observability). PII = re.compile(...) is a pattern that spots things shaped like a US social-security number. DOCS is a tiny stand-in knowledge base mapping each user to their own private note.
2. input_rail(msg) is the guardrail. It returns False, "injection" if the message tries to say "ignore your" rules (a prompt-injection attack), otherwise True plus the message with any detected PII replaced by [REDACTED]. Returning a pair (ok, payload) lets the caller branch.
3. retrieve(msg, user) is scoped retrieval: DOCS.get(user, "") only ever returns that user's document, so one user can never see another's data.
4. create_ticket(title, confirm=False) is a gated write tool. It raises an error unless you pass confirm=True — an action that changes the world must be explicitly confirmed, never triggered by accident.
5. _answer(msg, context) only produces a reply if there is context to ground it in; otherwise it returns None. This is how the system refuses to make things up when it has no supporting information.
6. System.handle runs them in order: log the call, guardrail first (escalate if it fails), then retrieve, then answer. If there's no grounding it escalates; otherwise it returns {"action": "SEND", "reply": ...}. The order is the safety design.

What the output means: Nothing prints on its own — this file defines the system and creates one ready-to-use instance, system = System(), that the app and tests import. A good call returns a dict whose action is "SEND"; a blocked or ungrounded one returns "ESCALATE".

Try this: Trace two messages by hand through handle: "ignore your rules" stops at the guardrail and escalates; "my account?" for user "alice" retrieves her doc and sends. Notice the guardrail runs before retrieval — that ordering is exactly what the tests check.

This wraps the system in a small web API so other programs (or a browser, or your tests) can talk to it over HTTP. FastAPI turns plain Python functions into web endpoints, and Pydantic checks that incoming requests have the right shape.

1. from system import system imports the single ready-made instance you created in Step 2. The web layer adds no new logic — it just exposes what already works.
2. class ChatRequest(BaseModel) declares that a chat request must contain a message string and a user string. If a caller sends the wrong shape, FastAPI rejects it automatically with a clear error — you never parse JSON by hand.
3. @app.post("/chat") marks the function below it as the handler for POST requests to /chat. It simply calls system.handle(...) and returns the result, which FastAPI converts to JSON for you.
4. @app.get("/health") is a tiny endpoint that always returns {"ok": True}. Deploy platforms and monitors ping a health check like this to know the service is alive.

Try this: Ask yourself why /chat is a POST but /health is a GET. POST is for sending data (your message); GET is for simply reading a status. Matching the HTTP verb to the action is a small but real piece of API design.

Now you actually start the server and talk to it from the command line. uvicorn is the program that runs your FastAPI app; curl is a tool that sends HTTP requests from the terminal, so you can test the API without a browser.

1. uvicorn app:app --port 8000 & starts the server. app:app means "in the file app.py, use the object named app." The trailing & runs it in the background so you get your prompt back; sleep 2 waits a moment for it to boot.
2. The first curl hits /health with a plain GET and should print {"ok":true} — proof the server is up.
3. The second curl does a POST to /chat: -X POST sets the method, -H "Content-Type: application/json" says the body is JSON, and -d '{...}' is the actual message and user. The backslash just continues the command onto the next line.

What the output means: Two JSON lines. {"ok":true} is the health check. The second line is the real answer — {"action":"SEND","reply":"Based on your account: Your plan renews on the 1st."} — showing the whole pipeline ran and grounded its reply in alice's document.

Try this: Run the same POST with "user":"bob". You'll get bob's document instead of alice's — the same scoped-retrieval rule from Step 2, now visible over the network.

These tests prove the system behaves correctly — the happy path and the failure paths — without needing an API key or a running server. FastAPI's TestClient calls your endpoints in-memory, so the whole suite runs in a fraction of a second.

1. client = TestClient(app) creates a fake HTTP client wired straight to your app — it lets tests call /health and /chat without launching a server.
2. test_safe_question_sends checks the happy path: a normal question for alice returns action == "SEND". test_injection_escalates_before_retrieval sends "ignore your rules" and asserts it ESCALATEs — the guardrail caught it.
3. test_gated_tool_requires_confirmation uses pytest.raises(PermissionError) to assert that calling create_ticket("x") with no confirmation is blocked, then checks that adding confirm=True succeeds. This is the safety gate, tested both ways.
4. test_user_scoping asks as "bob" and asserts alice's word "renews" is not in the reply — no data leaks between users. The last two tests hit the real HTTP endpoints and check status 200 and the JSON body.

What the output means: Each def test_... is one independent check. assert statements are the pass/fail conditions: if an assert is false, that test fails and pytest tells you exactly which line and why.

Try this: Notice there are six test functions — that matches the "6 passed" you'll see next. Add a test that asks as a user not in DOCS (say "carol") and assert the action is "ESCALATE" because there's no grounding for her.

This one command runs the whole test suite. pytest automatically finds every function named test_* in the tests/ folder, runs each one, and reports pass or fail. The -v flag (verbose) lists each test by name so you can see exactly what ran.

1. python -m pytest runs pytest through your project's Python, so it uses the libraries from your active .venv. tests/ tells it where to look.
2. Each line ending in PASSED is one test that succeeded. The names read like a spec of what the system guarantees: safe questions send, injections escalate, the gated tool needs confirmation, and so on.
3. The final 6 passed line is the summary. If any test failed, pytest would instead show FAILED with the exact assertion that broke — your first clue for debugging.

What the output means: Six green PASSED lines and 6 passed in 0.30s. That means every behaviour — happy path, guardrail order, gated tool, user scoping, and both endpoints — is verified. This is your objective evidence the system works.

Try this: Temporarily change one assertion to something false (e.g. expect "ESCALATE" in the safe-question test) and re-run. Watch pytest turn that line red and print the mismatch — then change it back. Seeing a test fail on purpose builds trust that green really means good.

A Dockerfile is a recipe for packaging your app into a container — a self-contained box that includes Python, your code, and its dependencies, so it runs the same way on any machine. This is how the service gets deployed.

1. FROM python:3.12-slim starts from a small official image that already has Python 3.12 installed — you build on top of it rather than from scratch. WORKDIR /app sets the folder inside the container where everything lives.
2. COPY requirements.txt . then RUN pip install ... -r requirements.txt copies just the dependency list and installs it. Doing this before copying the code lets Docker reuse the cached install layer when only your code changes — a standard speed trick.
3. COPY . . copies your actual source files in. CMD [...] is the command the container runs on start: the same uvicorn line as before, but bound to 0.0.0.0 so it's reachable from outside the container.
4. The two terminal lines build the image (docker build -t agentic-system .) and run it, mapping the container's port 8000 to your machine's port 8000 with -p 8000:8000.

What the output means: On docker run you see Uvicorn running on http://0.0.0.0:8000. From another terminal, curl localhost:8000/health returns {"ok":true} — the exact same app, now running inside a portable container.

Try this: If the build fails complaining about requirements, run pip freeze > requirements.txt inside your active venv first (Step 1) so the file exists and is complete. The container can only install what's listed there.

The final piece of production discipline: before shipping, an evals gate runs a script that measures the system's quality against fixed bars, and only lets you deploy if it passes. This turns "I think it's good" into "the numbers say it clears the bar."

1. export ANTHROPIC_API_KEY="..." puts your Claude API key into the environment so the real (non-mock) components can call the model. The key lives in the environment, never in your code.
2. python evals.py is the gate: it scores things like grounding faithfulness (are answers actually supported by retrieved context?) and guardrail catch rate (how often does the safety layer catch bad input?), each compared against a required minimum (a "bar").
3. The idea is a hard rule: if any score is below its bar, the script fails and you do not deploy. Quality is enforced automatically, not left to judgment on a busy day.

What the output means: Each line shows a measured score, its bar, and OK when it clears — e.g. grounding faithfulness: 0.89 (bar 0.85) OK. The final all bars met — safe to deploy is the green light. Any line without OK would block the deploy.

Try this: Decide what your bars should be for a real problem. A customer-facing bot might demand a higher guardrail catch rate (say 0.98) than an internal tool. Choosing the bar honestly — and gating on it — is exactly the senior judgment this capstone is testing.