ai-agent-designlisted

# LangGraph + Convex AI Agent Design Skill This skill encodes production-grade design principles for building AI agents in **TypeScript** using **LangGraph** for orchestration and **Convex** as the backend (database, real-time state, serverless functions, and caching). Before writing any code, diagnose the right architecture using the decision framework below. The single most common mistake is over-engineering — reaching for multi-agent complexity before validating a single-agent approach. --- ## Part 1: Design Principles (Read First) These aren't rules to follow blindly — they're the distilled lessons of what separates working production agents from prototypes that collapse under real usage. ### 1. Start with the simplest possible thing Always begin with a single LangGraph node and one clear system prompt. Verify the agent reliably understands and executes a tightly-scoped task before expanding. If you find yourself adding complexity early, that's usually a sign the task definition is fuzzy, not that you need more agents. ### 2. LLM intelligence belongs at bounded decision points only Deterministic code should handle routing, data transformation, retries, and error handling. Reserve LLM calls for the things only LLMs can do: natural language understanding, unstructured data extraction, and fuzzy reasoning. The temptation to make everything "smart" is what kills reliability. ### 3. State is the architecture In LangGraph, your `StateAnnotation` is the con