# LangGraph + Python + FastAPI (Agentic AI Workflows) — AI Agent Guidelines & Architecture Rules

> Production architecture for autonomous multi-agent systems, LangGraph cyclic state graphs, Pydantic v2 structured tool calling, and Chroma/Qdrant vector stores.
> Technologies: LangGraph, LangChain, FastAPI, Python, Pydantic, Vector DB

---

## AGENTS.md
```markdown
# 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.
```

---

## CLAUDE.md
```markdown
# CLAUDE.md — LangGraph + Python + FastAPI Commands & Conventions

## Common Commands
- `uvicorn app.main:app --reload` - Start local development server with live reload
- `pytest` - Run agent unit tests and evaluation benchmarks
- `ruff check .` - Run Python linter
- `ruff format .` - Format code adhering to Black/PEP8 standards
- `mypy .` - Perform strict static type checking

## Code Style Guidelines
- Adhere to Python 3.11+ type hints (`list[str]`, `dict[str, Any]`, `X | Y` union syntax).
- Keep agent state minimal: persist large documents in vector stores or object storage, passing only pointers/IDs in memory state.
- Encapsulate all prompt templates inside versioned constants or LangChain PromptTemplate objects.
- Handle asynchronous operations with `async`/`await` throughout all agent nodes and database queries.
```

---

## .cursor/rules/stack.mdc
```markdown
---
description: LangGraph + Python + FastAPI agentic AI workflow rules
globs: ["**/*.py"]
alwaysApply: true
---

# LangGraph + Python + FastAPI

- FastAPI (async ASGI) serving LangGraph `StateGraph` agents; Pydantic v2 for tool schemas; Qdrant/Chroma/pgvector for RAG.
- Always bound cyclic iterations with `recursion_limit` — an unbounded agent loop is a production incident waiting to happen.
- Model state with `Annotated[list[BaseMessage], add_messages]` so messages append instead of overwrite.
- Use `add_conditional_edges` to gate tool execution behind explicit checks before any external side effect runs.
- Structured output only: `model.with_structured_output(Schema)` or native tool calling — never regex-parse raw LLM strings.
- Sandbox tool execution: catch exceptions inside tools, return the error to the agent loop so it can self-correct.
- Stream responses via SSE (`graph.astream_events(version="v2")`); trace with LangSmith or OpenTelemetry.
- Python 3.11+ type hints throughout; keep large documents in the vector store, pass only pointers/IDs in agent state.
```

---

## Architecture Overview & Best Practices
## Architecture Overview

Production architectural standard for **autonomous agentic systems** built on **LangGraph**, **FastAPI**, and **Pydantic v2**.

### Key Advantages

- **Stateful Cyclic Workflows**: LangGraph supports human-in-the-loop approvals, time-travel debugging, and cyclic reasoning loops where agents evaluate, revise, and retry failed actions.
- **Deterministic Tool Calling**: Pydantic v2 schemas enforce strict input/output boundaries on tool execution, preventing hallucinated parameters.
- **Production Streaming**: Async generators stream token-by-token thought processes and tool execution statuses directly to web clients.