Agent Graph Engineering
10 parts so far, in reading order. The series is still being written, with a new part every few days.
Part 0: I Needed This Before It Had a Name
Years of shipping LLM features as intent detection and nested conditionals, the state machine idea that would not go away, and the library I started building and abandoned before the practice had a name. The story behind this series, and why graphs outlive the frameworks that implement them.
Part 1: The Stack, and Why Each Piece Is There
The stack for building a typed, observable, controllable agent graph: Pydantic AI, LangGraph, chanx, OpenTelemetry, pytest and evals. What each piece buys you, what it costs, the architecture we build across the series, and the full series map.
Part 2: Split the Services, and Know Where the Line Goes
Why the agent graph and the business logic belong in dedicated services, how to draw the line at state ownership rather than at layers, and the bug that taught me the thread a person reads and the thread a model remembers are not the same object.
Part 3: Contracts, Not Conventions
Three services in two languages, and nothing hand-written at the seams. How OpenAPI and AsyncAPI become generated clients, why a Python docstring ends up in your TypeScript, and the form nobody wrote that stops a reviewer approving arguments they were never shown.
Part 4: The Agent and the Graph
A typed model call and the flow that routes it, taught together because they compose. Why the agent's output type is also your routing table, how a node declares its own legal moves, and what replaces the if/else on an intent classifier.
Part 5: Tools and Guardrails
What the model may do, and what it may say. Structured tool errors you raise instead of return, at-most-once execution for actions you cannot undo, and why the guardrail that works is demarcation rather than detection.
Part 6: Subgraphs, the Multi-Agent System You Can See
Subgraphs as modules: one responsibility each, their own state, their own agents. A supervisor routing to specialists is a multi-agent system, and building it this way gives you a topology you can export and a span per step instead of a conversation you have to reconstruct.
Part 7: Human in the Loop, Not in the Graph
Human-in-the-loop in LangGraph. What interrupt() gives you, the documented rules it comes with and the one that turns out to be quieter than documented, why a graph that changes every sprint outgrows them, and the design that replaces it: end the run, hand the state back, and route on how far the work got.
Part 8: Why a WebSocket, and How Progress Streams
Updated:SSE first, because it is usually the right answer, then where it stopped fitting. What chanx does on each side of the socket, what AsyncAPI generates from it, how it sits next to Pydantic AI's streaming and LangGraph's stream writer, the practices worth copying, and what a socket costs you.
Part 9: Practices for Both Services
The patterns that make the Django side and the agent side adoptable rather than just readable. Two layers of authorization instead of one, secure-by-default enums, polymorphic events that reach TypeScript as a union, and production-safe settings with dev as the layer that loosens them.
More to come. A new part goes up every few days.