Skip to content
Huy Nguyen's Blog

Agent Graph Engineering

10 parts so far, in reading order. The series is still being written, with a new part every few days.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

  10. 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.