Graph Skeleton
Explore how to build the foundational graph skeleton of a research assistant agent that processes user queries with a clarity gate. Learn to implement multi-phase heuristics and model-based checks to filter vague questions and route clear ones downstream. This lesson helps you confirm the architecture works before full pipeline implementation.
The previous lesson scoped the full research assistant, all seven nodes, the complete state schema, and the two routing paths. Nothing has been implemented yet. This lesson makes the first section real.
The goal for this lesson is specific and limited: by the end, the graph should run end to end, vague questions should produce a useful clarification response, and clear questions should pass through to the downstream pipeline and reach END. The downstream nodes will still be stubs that return empty values. That is expected; the value of this lesson is confirming that the clarity gate works correctly and that the skeleton’s architecture is sound before any expensive model calls are involved.
Limiting scope this deliberately is itself a practice worth keeping. Every time a new section of the system is implemented, the goal should be a single testable milestone, not a complete system.
What the clarity gate does
The clarity gate is the first decision in the graph. It determines whether the user’s question is specific enough to search. If the question is too vague, the graph returns a clarification question immediately without calling any search tools or synthesis models. This saves cost and produces a better user experience — a targeted clarification question is more helpful than a generic or hallucinated answer to an unclear prompt.
There are two failure modes the clarity check must handle. The first is a question that is too short to interpret — a single keyword like "api" or a two-word phrase like "pricing info". The second is a question that is grammatically full-length but still too vague for a useful search — for example, "Tell me everything about the plans" or "What's the deal with the API?". The first failure mode can be caught with a word-count heuristic. The second requires model judgement.
The node we are building uses both. A fast heuristic runs first and catches obvious cases without a model call. Questions that pass the heuristic are sent to LLM for a short binary judgement.
Build it step by step
We will build the two real nodes first, then add the stubs for the downstream pipeline, assemble the graph, and verify both paths.
The clarity check node
The node has three ...