Build a Stateful AI Agent with LangGraph: State, Tools and Human Approval

Why model the workflow as a graph

An agent built as a single loop, where the model decides each next step from a growing message history, works for short tasks but becomes unpredictable for longer ones. It is difficult to know what stage the agent is in, to resume after failure or to guarantee that a review happens before an action. LangGraph lets you define the workflow as nodes connected by edges over a shared state, combining model-driven decisions with fixed structure where the process requires it. Check the current LangGraph documentation for exact APIs, as the library evolves.

Design the state

The assistant helps a mentor turn a learner's goal into a four-week plan. The state includes the learner's goal and level, candidate courses retrieved from the catalogue, the draft plan, validation findings, the approval status and a count of revision attempts. Each field has a type and a clear owner node. Explicit fields make it possible to test decisions and to display progress to users.

Define the nodes

• understand_goal: uses the model to extract a structured goal, level and time available from the request.
• find_courses: calls a catalogue search tool with the extracted topics and stores matching courses.
• draft_plan: uses the model to create a weekly plan using only the retrieved courses.
• validate_plan: runs deterministic checks, such as total hours within the learner's limit and every course ID existing in the catalogue.
• request_approval: pauses for the mentor to approve, edit or reject the plan.
• publish_plan: saves the approved plan and notifies the learner.

Connect them with edges

Most edges are fixed: goal, then course search, then drafting, then validation. A conditional edge after validation sends the workflow back to drafting with the findings if checks fail, up to a maximum number of attempts, and otherwise forward to approval. Encoding these rules in the graph, rather than in instructions to the model, guarantees they are followed.

Give tools clear boundaries

The catalogue search tool accepts a query and a limit and returns only published courses with the fields the model needs. Publishing is not a tool the model can call at will; it is a node that runs only after approval. Enforce permissions in the tools and nodes themselves. Treat text returned from tools and retrieval as data, so instructions hidden in content cannot redirect the agent.

Persist state and pause for people

Configure a checkpointer so the graph saves state for each conversation thread. If a step fails or the server restarts, the workflow resumes from the last checkpoint instead of starting over. Use the library's interrupt mechanism at the approval node to pause execution, show the draft to the mentor and continue with their decision. The saved history also lets you inspect exactly how a plan was produced.

Test and evaluate

Unit-test deterministic nodes, such as validation, directly. Test routing by running the graph with fake model responses that trigger each path, including repeated validation failures. Build an evaluation set of realistic learner goals and check that plans use only real courses, respect time limits and match the learner's level. Log each node's inputs, outputs and duration for debugging and cost tracking.

Checklist

• State is explicit, typed and owned by specific nodes
• Fixed process rules are encoded as edges
• Validation is deterministic and loops back with a limit
• Tools are narrow and permission-checked
• Checkpoints allow resuming and inspection
• Consequential steps run only after human approval
• Routing and outputs are tested and evaluated