Building a Multi-Agent Workflow for Automated API Documentation Using LangGraph

API documentation is usually the first thing to rot in a codebase because developers hate writing it more than they hate debugging race conditions. I spent the last few days hacking together a multi-agent pipeline using LangGraph to automate this, and the result is surprisingly robust because it treats documentation as a "refinement loop" rather than a single-shot prompt.

The core problem with using a standard LLM for docs is that it hallucinate parameters or misses edge cases. My solution was to split the labor into three distinct nodes: a Code Analyzer, a Technical Writer, and a Validator.

Here is the graph logic: the Analyzer parses the route handlers and schemas; the Writer drafts the Markdown; the Validator then "tests" the documentation by attempting to simulate a request based only on the generated text. If the Validator finds a discrepancy between the doc and the actual code, it sends the draft back to the Writer with a specific error log.

For the state management, I used a typed dictionary to pass the source code, the current draft, and a list of "critiques" between nodes.

from typing import TypedDict, List
from langgraph.graph import StateGraph, END

class DocState(TypedDict):
    source_code: str
    draft: str
    critiques: List[str]
    iteration_count: int

def analyzer_node(state: DocState):
    # Extracting endpoints, types, and logic
    # Prompt: "Identify all API endpoints and required headers in this file"
    return {"draft": "Initial analysis of endpoints..."}

def writer_node(state: DocState):
    # Converts analysis to polished OpenAPI/Markdown
    # Uses the 'critiques' list to fix previous errors
    return {"draft": "Updated documentation version..."}

def validator_node(state: DocState):
    # The 'adversarial' step: checks for missing fields
    # Returns critiques if gaps are found
    return {"critiques": ["Missing description for the 'user_id' parameter"]}

workflow = StateGraph(DocState)
workflow.add_node("analyze", analyzer_node)
workflow.add_node("write", writer_node)
workflow.add_node("validate", validator_node)

workflow.set_entry_point("analyze")
workflow.add_edge("analyze", "write")
workflow.add_edge("write", "validate")
workflow.add_conditional_edges(
    "validate",
    lambda x: "write" if x["critiques"] else END
)

A huge productivity gain here came from my .cursorrules config. I told Cursor to always treat the DocState as the source of truth when I'm modifying the graph, which stopped it from hallucinating non-existent LangGraph methods.

Key configuration tips for this setup:

• System Prompts for the Validator: Don't tell the Validator to "be helpful." Tell it to "be a pedantic API consumer who refuses to use an endpoint if a single parameter is ambiguous." This forces the Writer node to be precise.
• Token Management: Passing the entire codebase into the state is a mistake. I implemented a pre-processing step that only feeds the agent the specific function signatures and Pydantic models.
• Checkpointing: I used MemorySaver so I can pause the graph, manually edit a piece of the documentation that the AI is struggling with, and then resume the validation loop.

The "gotcha" I hit was the infinite loop. If the Validator and Writer disagree on a naming convention, they can bounce back and forth forever. I added a hard stop at iteration_count > 3 which triggers a "Human-in-the-loop" intervention.

This approach turned a four-hour manual documentation chore into a 30-second execution. The difference is that you aren't just asking an AI to "write docs," you're building a factory that verifies its own output.