---
name: langgraph-python-fastapi
description: "Use when building, refactoring, or reviewing a LangGraph + Python + FastAPI (Agentic AI Workflows) project (LangGraph, LangChain, FastAPI, Python, Pydantic, Vector DB). Production architecture for autonomous multi-agent systems, LangGraph cyclic state graphs, Pydantic v2 structured tool calling, and Chroma/Qdrant vector stores."
license: MIT
metadata:
  source: https://stackitfast.com/rules/langgraph-python-fastapi
  version: "2026-10-04"
---

# LangGraph + Python + FastAPI (Agentic AI Workflows) — Agent Skill

## When to use this skill
- Any task that scaffolds, modifies, refactors, or reviews code in a LangGraph + Python + FastAPI (Agentic AI Workflows) codebase.
- Whenever the project depends on LangGraph, LangChain, FastAPI, Python, Pydantic, Vector DB.
- Apply these guidelines before proposing architecture, database, or deployment changes.

## Guidelines
# Project Architecture & Guidelines (LangGraph + Python + FastAPI)

## 1. System Architecture
- **Framework**: FastAPI (Async ASGI with Uvicorn).
- **Agent Orchestration**: LangGraph (`StateGraph`, `MessagesState`) for stateful cyclic multi-agent loops.
- **Data Validation & Tools**: Pydantic v2 (`BaseModel`, `Field`) for type validation and structured LLM tool definitions.
- **Vector Database**: Qdrant / Chroma / pgvector for semantic retrieval augmented generation (RAG).
- **LLM Integration**: LangChain Chat Models (`ChatOpenAI`, `ChatAnthropic`, local Ollama/vLLM endpoints).

## 2. Directory & Module Organization
- `app/api/`: FastAPI route handlers (e.g. `POST /api/chat`, `GET /api/runs/{run_id}`).
- `app/agents/`:
  - `graph.py`: StateGraph definition, node connections, and compiled runnable workflow.
  - `state.py`: TypedDict or Pydantic definitions of agent memory and intermediate scratchpads.
  - `nodes.py`: Discrete execution steps (reasoner, retriever, tool_executor, reviewer).
- `app/tools/`: Custom Pydantic-validated tool functions decorated with `@tool`.
- `app/core/`: Configuration, LLM client singleton, and OpenTelemetry / LangSmith tracing.

## 3. Agent Graph Guardrails
- Always bound maximum cyclic iterations using `recursion_limit` (e.g. `graph.compile().invoke(..., {"recursion_limit": 25})`).
- Model agent state explicitly: use `Annotated[list[BaseMessage], add_messages]` to ensure message append behavior without overwriting history.
- Implement conditional routing edges (`add_conditional_edges`) checking tool call requests before executing external side effects.

## 4. Structured Output & Tool Execution
- Never parse raw LLM strings with regular expressions. Use `model.with_structured_output(PydanticSchema)` or native tool calling.
- Sandbox tool execution with error boundaries: catch tool exceptions and return error messages back to the agent loop to allow self-correction.
- Enforce timeout limits on external API calls executed by agents.

## 5. Streaming & Observability
- Expose streaming responses using Server-Sent Events (SSE) via FastAPI `StreamingResponse` using `graph.astream_events(version="v2")`.
- Enable LangSmith or OpenTelemetry tracing via environment variables for complete inspection of prompt tokens, latency, and tool inputs.

## 6. Testing Conventions
- Unit test individual graph nodes as pure functions (given state, assert output state) before testing the compiled graph end-to-end.
- Use LangSmith evaluation datasets or `pytest` fixtures with recorded LLM responses (cassettes) to keep tests deterministic and avoid burning API credits on every CI run.
- Test tool-calling contracts by asserting the Pydantic schema rejects malformed arguments, not just that valid ones pass.
- Assert `recursion_limit` is actually enforced with a test that forces a cyclic loop and expects a `GraphRecursionError`.

## 7. Git Workflow & PR Conventions
- Conventional Commits (`feat:`, `fix:`, `refactor:`) scoped to the agent/node, e.g. `fix(agents/retriever): handle empty vector store results`.
- Any PR changing a prompt template or tool schema must include before/after LangSmith trace links or eval scores in the description.
- Require `pytest`, `ruff check .`, and `mypy .` green before merge.
- Flag prompt-only changes distinctly (`prompt:` commit prefix) so trace regressions are easy to bisect later.

## Source
Maintained at https://stackitfast.com/rules/langgraph-python-fastapi — also available as AGENTS.md, CLAUDE.md, and Cursor .mdc.