Project: a self-correcting writer-reviewer agent
A self-correcting writer-reviewer agent is a LangGraph graph in which a writer drafts, a reviewer checks the draft against written rules, and a reviser improves it from the feedback, repeating until the draft passes or a revision limit is reached.
Last updated: 08 Oct, 2026 · LangChain 1.4 · LangGraph 1.2
This project builds the loop from Loop engineering with three LangGraph nodes. A node is a function that reads the shared state and returns the fields it changes, and the edges between nodes decide what runs next. If LangGraph is new, LangGraph essentials teaches the pieces used here: state, nodes, edges and conditional edges.
The writer, reviewer and reviser architecture
The video builds a self-correcting multi-agent system for blog-style explanations. The user gives a topic and the writer drafts it. A reviewer, the verifier, checks the draft against rules the builder chose: beginner friendly, an everyday analogy, an example. If the draft passes, the user sees it. If it fails, the feedback goes to a reviser, which improves the draft and sends it back to the reviewer. The video keeps the tools out to keep the demo simple, so the model is called directly.
The stop condition has two parts: the reviewer passes the draft, or a maximum number of revisions is reached and the latest draft is shown.
One difference from the video is deliberate. The video's writer, reviewer and reviser all call one Groq model, llama-3.3-70b-versatile, which Groq has since retired. When a model reviews its own writing it shares its blind spots, so this page gives the judge its own, larger model: the writer and reviser run openai/gpt-oss-20b, and the reviewer's judge runs openai/gpt-oss-120b. The reviewer also checks the word count in Python before it asks the judge, because a count needs no model.
Building the three agents
The models and the limit
Two model objects, one per role, and the revision limit that the stop condition uses.
from typing import Literal, TypedDict
from pydantic import BaseModel, Field
from langchain.chat_models import init_chat_model
from langgraph.graph import END, START, StateGraph
writer_llm = init_chat_model("groq:openai/gpt-oss-20b", temperature=0)
judge_llm = init_chat_model("groq:openai/gpt-oss-120b", temperature=0)
MAX_REVISIONS = 2The review schema
The judge must return a decision and feedback, with no other text. A Pydantic class with with_structured_output forces that shape, so the loop can read decision without parsing text.
class Review(BaseModel):
decision: Literal["PASS", "REVISE"] = Field(description="PASS only if every rule is met")
feedback: str = Field(description="One or two precise fixes; empty when PASS")
judge = judge_llm.with_structured_output(Review, method="json_schema")The state and the rules
The state is the dictionary every node reads and updates: the topic, the current draft, the reviewer's feedback and decision, and how many revisions have run. RULES is the checklist the judge applies.
class State(TypedDict):
topic: str
draft: str
feedback: str
decision: str
revisions: int
RULES = ("1. Easy for a beginner. 2. Contains an everyday analogy. "
"3. Contains a tiny concrete example. 4. Stays on the topic.")The writer
The writer reads the topic from the state and returns the first draft. It also resets the feedback, the decision and the revision count, since a new run starts empty.
def writer(state: State):
reply = writer_llm.invoke(
"You are a beginner-friendly teacher. Explain the topic in 120 to 160 words, with simple "
"language, one everyday analogy and one tiny example.\n\nTopic: " + state["topic"])
return {"draft": reply.content, "feedback": "", "decision": "", "revisions": 0}The reviewer
The reviewer is the verifier. The word count is checked first, in code, and a wrong length returns a REVISE decision with a feedback line the reviser can act on. Only a draft with an acceptable length reaches the judge model.
def reviewer(state: State):
words = len(state["draft"].split())
if not 120 <= words <= 160:
return {"decision": "REVISE", "feedback": f"The draft has {words} words; it must have 120 to 160."}
review = judge.invoke(f"You are a strict reviewer. Check the answer against these rules only: {RULES} "
f"If any rule fails, choose REVISE.\n\nTopic: {state['topic']}\n\nAnswer:\n{state['draft']}")
return {"decision": review.decision, "feedback": review.feedback}The reviser
The reviser gets the topic, the draft and the feedback, and returns an improved draft with the revision count raised by one.
def reviser(state: State):
reply = writer_llm.invoke(
"Improve the answer using the reviewer feedback. Keep it 120 to 160 words, beginner friendly. "
f"Return only the improved answer.\n\nTopic: {state['topic']}\n\nAnswer:\n{state['draft']}\n\n"
f"Feedback: {state['feedback']}")
return {"draft": reply.content, "revisions": state["revisions"] + 1}Wiring the loop
The video connects the nodes in a LangGraph graph: START to the writer, the writer to the reviewer, then a conditional edge that either ends the run or goes to the reviser, and the reviser back to the reviewer. That back edge is the loop.
The route function
A conditional edge calls a function that returns a label. The label "done" ends the run and "revise" runs the reviser. Both a pass and the revision limit return "done", which is the two-part stop condition.
def route(state: State) -> Literal["revise", "done"]:
if state["decision"] == "PASS" or state["revisions"] >= MAX_REVISIONS:
return "done"
return "revise"The graph
add_node registers each function, add_edge adds a fixed edge, and add_conditional_edges maps the route labels to nodes. compile() returns the runnable graph.
builder = StateGraph(State)
builder.add_node("writer", writer)
builder.add_node("reviewer", reviewer)
builder.add_node("reviser", reviser)
builder.add_edge(START, "writer")
builder.add_edge("writer", "reviewer")
builder.add_conditional_edges("reviewer", route, {"revise": "reviser", "done": END})
builder.add_edge("reviser", "reviewer")
graph = builder.compile()Running the self-correcting agent
The video runs its graph in a terminal: a simple topic passes on the first review, and a harder one needs a revision. The run below does the same with graph.stream in updates mode, which yields one update per node as it finishes. The first topic is a plain one, the second is harder, and the third is the second topic again with the revision limit set to 0, to show what happens when the limit is reached before a pass.
def run(topic, show_draft=False):
final = {}
print("TOPIC:", topic)
start = {"topic": topic, "draft": "", "feedback": "", "decision": "", "revisions": 0}
for update in graph.stream(start, stream_mode="updates"):
for node, values in update.items():
final.update(values)
if node == "reviewer":
print(f" reviewer: {values['decision']}, {values['feedback'] or 'no changes needed'}")
else:
print(f" {node}: {len(values['draft'].split())} words")
print(f" final decision: {final['decision']}, revisions used: {final['revisions']}")
if show_draft:
print(" FINAL DRAFT:", final["draft"])
run("What is an AI agent?", show_draft=True)
run("How does attention work in a transformer?")
MAX_REVISIONS = 0 # the same topic, with no revisions allowed
run("How does attention work in a transformer?")TOPIC: What is an AI agent? writer: 134 words reviewer: PASS, no changes needed final decision: PASS, revisions used: 0 FINAL DRAFT: An **AI agent** is a computer program that can act on its own to reach a goal. Think of it like a smart robot vacuum. The vacuum has sensors (to see where it is), a plan (to clean the floor), and a controller (to move and avoid obstacles). It doesn’t need a human to tell it every step; it decides what to do next based on what it sees. **Everyday analogy:** A smart thermostat is an AI agent. It watches the temperature, knows your schedule, and turns the heater on or off to keep you comfortable without you pressing buttons. **Tiny example:** A chatbot that answers customer questions. It reads your message, decides the best reply, and sends it back—all automatically. That chatbot is an AI agent working toward the goal of helping you. TOPIC: How does attention work in a transformer? writer: 189 words reviewer: REVISE, The draft has 189 words; it must have 120 to 160. reviser: 134 words reviewer: PASS, no changes needed final decision: PASS, revisions used: 1 TOPIC: How does attention work in a transformer? writer: 201 words reviewer: REVISE, The draft has 201 words; it must have 120 to 160. final decision: REVISE, revisions used: 0
What each run did
- Topic 1: no revision needed. The writer's 134-word draft passed the first review, so the run ended with
revisions used: 0. The reviewer checked the rules and found nothing to fix. - Topic 2: one revision. The first draft had 189 words. The word-count check rejected it before the judge was called, with the feedback "The draft has 189 words; it must have 120 to 160". The reviser cut it to 134 words, the reviewer passed it, and the run ended with one revision used.
- Topic 2 with no revisions allowed. The writer's draft had 201 words and failed the length check. With the limit at 0 the route function returned "done" at once, so the final decision is REVISE with 0 revisions used. The graph ended with a draft that did not pass, and the decision field says so.
- What the loop fixed. In both runs of the harder topic the writer overshot the length, and the cheapest verifier, a word count in Python, caught it. The failure and the fix were exact because the check was code.
One model vs a separate judge
| Writer reviews its own draft | A separate judge reviews it | |
|---|---|---|
| Blind spots | Shared with the writer | Different from the writer's |
| Cost | One model | A second model call per review |
| Rules that code can check | Left to the model | Checked in Python first, free and exact |
| Best for | Quick demos | Anything whose result a user will read |
Where you use this pattern
- Content pipelines. A drafting agent and a reviewer that holds the style guide.
- Support replies. A draft is checked for tone and policy before it is sent.
- Report generation. Numbers in a draft are checked in code, wording by a judge.
decision is REVISE. Show the user that status, or hold the draft back. A limit protects the budget; it does not make the draft correct.Related
- Previous: Anatomy of a good loop
- Next: Harness engineering
- Go deeper: Conditional edges
- Set
MAX_REVISIONS = 0before the first run and read the decision of a draft that gets no revision. - Add a fifth rule to
RULES, such as "No jargon without a definition", and run the transformer topic again. - Swap the judge for
init_chat_model("groq:openai/gpt-oss-20b")and compare its feedback with the 120b judge's.
This is what real progress feels like.