id: fastapi-agents type: rule version: 1.0.0 created: 20/03/2026 modified: 20/03/2026 status: active

FastAPI + LangGraph Backend Rules

Framework Configuration

• Framework: FastAPI
• AI Orchestration: LangGraph
• Validation: Pydantic
• Python Version: 3.12+
• Package Manager: uv

Agent Patterns

✅ DO: Agent Structure

from abc import ABC, abstractmethod
from pydantic import BaseModel, Field

class BaseAgent(ABC):
    """Abstract base class for all agents."""

    def __init__(self, name: str, capabilities: list[str]):
        self.name = name
        self.capabilities = capabilities
        self.agent_id = str(uuid.uuid4())

    @abstractmethod
    async def execute(self, task: str, context: dict) -> TaskOutput:
        """Execute a task. Must be implemented by subclasses."""
        pass

    def can_handle(self, task: str) -> bool:
        """Check if agent can handle this task."""
        return any(cap in task.lower() for cap in self.capabilities)

✅ DO: Pydantic Models

class TaskOutput(BaseModel):
    """Structured output from task execution."""
    task_id: str
    agent_id: str
    status: str = Field(description="completed, failed, or pending_verification")
    outputs: list[dict[str, Any]] = Field(default_factory=list)
    requires_verification: bool = Field(default=True)

✅ DO: API Route Pattern

from fastapi import APIRouter

router = APIRouter(prefix="/api", tags=["api"])

@router.get("/endpoint")
async def endpoint() -> dict:
    """Endpoint description."""
    return {"status": "success"}

Critical Rules

• No Self-Attestation: Agents CANNOT verify their own work - use IndependentVerifier
• Async Everywhere: All agent methods must be async def
• Type Hints Required: Every function needs type hints, use Pydantic for complex types
• Environment Variables: Never hardcode secrets, use config/settings.py

Anti-Patterns

❌ Missing type hints, using dict instead of Pydantic, self-verification, sync functions in async context

Key Commands

cd apps/backend && uv sync                    # Install dependencies
uv run uvicorn src.api.main:app --reload     # Development server
uv run pytest                                # Run tests
uv run mypy src/                             # Type checking
uv run ruff check src/                       # Linting

Verification Required

• Independent verification for all agent outputs
• Type checking with mypy passes
• All tests pass
• Linting passes