kumaran-is Iron Law: Always consult the agentic-ai-dev skill and its MCP sources before writing agent code; never generate LangGraph/LangChain patterns from memory.
Agentic AI Coding Standards
Mandatory coding standards for all Python agentic AI services using LangChain, LangGraph, and FastAPI.
Key Rules
| # | Rule | Standard |
|---|---|---|
| 1 | State typing | Always TypedDict; never dict[str, Any] |
| 2 | Message lists | Annotated[list[BaseMessage], add_messages] |
| 3 | Loop protection | iteration_count in state + max check in routing function |
| 4 | Tool functions | @tool + docstring + try/except + return strings |
| 5 | LLM instantiation | Factory function; never inline ChatAnthropic() in nodes |
| 6 | Temperature | 0 for factual; 0.7 only for creative tasks |
| 7 | Checkpointing | PostgresSaver in production; MemorySaver only in tests |
| 8 | Error handling | Log + return error state; never swallow exceptions |
| 9 | Naming | build_<name>_agent(), <verb>_node(), <Name>State |
| 10 | Config | pydantic-settings with fail-fast; no os.getenv() with silent defaults |
| 11 | Type hints | mypy --strict; Literal for routing return types |
| 12 | Async | async def for all I/O; ainvoke/astream in API routes |
| 13 | Logging | structlog with agent_name, thread_id, node_name context |
| 14 | Secrets | Never log API keys; redact PII before logging |
| 15 | Testing | Basic invoke + tool usage + iteration limit + error recovery |
| 16 | Cost | Track tokens; configure budget caps; use cheapest viable model |
| 17 | Imports | Group: stdlib → third-party → langchain/langgraph → local |
Import Ordering
# 1. Standard library
from __future__ import annotations
import json
from typing import Annotated, Literal
# 2. Third-party
from fastapi import APIRouter, Depends
from pydantic import BaseModel, Field
# 3. LangChain / LangGraph
from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
from langchain_core.tools import tool
from langgraph.graph import END, StateGraph
from langgraph.graph.message import add_messages
# 4. Local
from ..core.config import settings
from ..core.logging import get_logger
Naming Conventions
| Element | Pattern | Example |
|---|---|---|
| State | <Name>State |
AgentState, RAGState, MultiAgentState |
| Graph builder | build_<name>_agent() |
build_react_agent(), build_rag_agent() |
| Node function | <verb>_node() |
agent_node(), retrieve_node(), grade_node() |
| Tool function | <verb>_<noun>() |
search_web(), query_database(), calculate_cost() |
| Provider factory | LLMProviderFactory |
Singleton, injected via Depends() |
| Config | Settings |
pydantic-settings, singleton settings instance |
| Exception | <Name>Error |
AgentError, ToolError, LLMProviderError |
File Structure
src/<service>/
├── agents/
│ ├── graphs/ # build_*_agent() functions
│ ├── nodes/ # *_node() functions
│ ├── tools/ # @tool functions
│ └── state.py # TypedDict state schemas
├── rag/ # RAG-specific code
├── memory/ # Checkpointing + semantic memory
├── guardrails/ # Input/output validation
├── llm/providers.py # LLM factory
├── core/
│ ├── config.py # pydantic-settings
│ ├── logging.py # structlog setup
│ └── exceptions.py # Exception hierarchy
├── observability/ # Metrics + tracing
├── models/schemas.py # Pydantic request/response
├── api/routes/ # FastAPI routes
└── main.py # FastAPI app + lifespan
Reference
For concrete code examples and anti-patterns, Read reference/agentic-standards-examples.md.
Error Handling
Import errors: Verify LangChain/LangGraph package versions match pyproject.toml constraints.
State type mismatches: Ensure all graph state fields use TypedDict with proper Annotated types — never dict[str, Any].
Graph recursion errors: Check recursion_limit in config and verify iteration_count is incremented in routing functions.