Project structure · AI and ML
Python AI agent with LangGraph project structure
Opens with creditsFor Python developers moving from "call a model in a loop" to an agent that can pause, resume and be debugged. It starts from the official LangGraph template (langgraph.json, a src/agent package, unit and integration tests) and grows into a customer support agent with typed state, one file per node and tool, human approval before refunds, evals that score whole trajectories, tracing, auth and a deployable server image.
Curated by Tauseef FayyazIntermediate136 files and foldersPython 3.12, LangGraph 1.2, LangChain 1.4 (langchain-core 1.6)Checked October 2026How it grows
Each stage opens the explorer there
- 1Day 1What the scaffold and your first hour give you30 files and folders
- 2GrowingWhat a real app with features and tests adds+42 files and folders
- ProductionWhat running it for real users adds+30 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+34 files and foldersOpens with credits
How it is organised
- graph.py only wires the graph. Nodes, tools, prompts, routing and state each live in their own module and are tested on their own.
- State is small and typed. Messages append through a reducer; other fields are replaced. Large data stays in tools or a store, not in checkpoints.
- Run settings (model name, limits, store name) go in the Context schema, not in code or state, so assistants can differ without a deploy.
- Tools are the agent's hands: small outputs, clear docstrings, ownership checks on every id the model passes in, and write actions split from read actions.
- Anything that moves money or cannot be undone pauses with interrupt() for a person. Side effects happen after the interrupt, never before.
- Unit tests never call a model: fake chat models and fake APIs cover nodes, routing and tools. Integration tests and evals call real models and run on purpose.
- Evals score trajectories (intent, tools called, approvals) as well as final answers, and every production failure becomes a new eval case.
- Every run is traced. When an answer is wrong, the trace shows which node, prompt or tool caused it.
- Let the LangGraph server handle persistence, threads and streaming in production; your code supplies the graph, auth and custom routes.
At the top of the project
Open one in the explorer for the full story
- support-agent/
- .venv/The virtual environment uv creates from uv.lock.
- .langgraph_api/Local data from `langgraph dev`: threads, runs and checkpoints of the in-memory server.
- langgraph.jsonTells the LangGraph CLI and server where your graphs are, what to install and which env file to load.
- pyproject.tomlPackage metadata, langgraph and python-dotenv dependencies, a dev group with the CLI, pytest, ruff and mypy.
- uv.lockExact versions of every package; the template ships one and uv keeps it current.
- .env.exampleVariables the app reads: LANGSMITH_PROJECT, model provider keys, API URLs.
- .envYour real keys, loaded by langgraph dev through "env" in langgraph.json.
- .gitignoreIgnores .env, .venv, caches and .langgraph_api.
- .codespellignoreWords the spell checker in CI should accept.
- MakefileTemplate targets: test, integration_tests, lint, format, spell_check.
- README.mdWhat the agent does, how to run it, and a Studio screenshot.
- LICENSEThe MIT licence from the template.
- static/Images for the README.1 inside
- src/The src layout: importable code lives only here.1 inside
- tests/Unit tests that never call a model, and integration tests that do.5 inside
- evals/Offline evaluations: datasets of conversations, evaluators, and the script that scores the graph.6 inside
- .vscode/Shared editor settings for the team.2 inside
- scripts/Small command-line helpers that are not part of the agent.1 inside
- .pre-commit-config.yamlHooks on every commit: ruff, ruff format, a secrets scan and a uv lock check.
- AGENTS.mdInstructions for coding agents: commands, where nodes and tools go, run evals before changing prompts.
- .github/CI from the template: unit tests on every push, integration tests on a schedule or by hand.1 inside
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with Python AI agent with LangGraph.
- Roadmap· PythonAI agents and MCP roadmapTool calling, MCP servers, evals
- Roadmap· PythonAI engineering roadmapBuild products on LLMs and generative AI
- Roadmap· LLM appsMLOps and LLMOps roadmapShip, serve and monitor models
- Roadmap· App and agent securityAI security roadmapSecure LLM apps and agents, test models safely
- Cheat sheetAI agents and MCP cheat sheetTool calling, MCP servers, evals.
- Cheat sheetAI evals cheat sheetEvals for LLM apps and agents: golden datasets, metrics, LLM-as-judge and its biases, RAG and agent metrics, offline and online evals, CI, human review, tools.
- Cheat sheetGenAI app architecture cheat sheetHow a production GenAI app fits together: request flow, layers, RAG, agent loop, memory, caching, guards, evals, tracing, folder layout and launch checklist.
- Cheat sheetPrompt Engineering cheat sheetPrompt anatomy, few-shot examples, chain of thought, structured output, long context, prompts for code and study, and testing prompts.
- FYP idea· AdvancedAI Agent Tool Permission Gateway with Human Approval and Audit LogBuild a policy gateway that sits between an AI agent and the tools it can call. It enforces least privilege per tool, checks arguments against rules, acts with the signed-in user's own permissions, asks a person to approve risky actions with a clear preview, caps steps and spend, and writes a tamper-evident log of every call. A practical answer to excessive agency, the OWASP LLM risk that turns a fooled model into real damage.
See 12 moreShow fewer
- FYP idea· AdvancedHuman-Approved AI Agent for Filing and Tracking Citizen Service RequestsFiling a complaint or service request with a city or government office means finding the right portal, filling long forms, attaching documents and then chasing it for weeks. Build an agent that turns a citizen's plain description (in Urdu, Roman Urdu or English) into a correctly filled request, pauses for the citizen to approve every submission, then tracks status and reminds them to follow up. Built and tested against a realistic mock portal you create.
- FYP idea· AdvancedPrompt Injection Red-Team Harness for Tool-Using AI AgentsBuild an open source harness that attacks tool-using AI agents with indirect prompt injections hidden in emails, web pages, files and MCP tool results, then measures both how often attacks succeed and how much useful work the agent still completes. Test three defences on real agents and publish the results as a reusable benchmark for small teams.
- FYP idea· IntermediateDeadline-Tracking Study Agent with Long-Term Memory for University StudentsBuild an AI agent that reads a student's course portal notices, emails and timetable, keeps a long-term memory of their courses, deadlines and preferences, and plans their week, asking for approval before it adds events or sends anything. The project is about memory done properly: per-student storage, correction, privacy and evals that prove the agent remembers the right things.
- QuestionShould I learn LangGraph, CrewAI or the OpenAI Agents SDK first, or build AI agents without a framework?Build one small agent without a framework first: the tool-calling loop is about fifty lines and every framework wraps it. Then learn one framework deeply, chosen by what your project needs: LangGraph for explicit state and approvals, the OpenAI Agents SDK for quick assistants with handoffs, the Claude Agent SDK for agents that work on files.
- QuestionHow do I start learning AI agents as a software engineer?Start with one LLM API and plain code: a loop that calls the model, lets it pick a tool, runs the tool and feeds the result back. Build one small agent that does a real task end to end, add evaluation and guardrails, and only then reach for a framework. Agents are software engineering first.
- QuestionHow do I prove my AI agent project actually works before I show it to anyone?Stop relying on the demo. Write 30 or more test tasks from realistic and messy inputs, check what you can in code (right tool, right arguments, right end state), run each task several times, report how often it succeeds every time, add a few injection attacks, and trace every run. Numbers from that are what make an agent project credible.
- QuestionWhat does an AI evals engineer do?An AI evals engineer designs the tests that tell a team whether an AI system is good enough: the datasets, the scoring (code checks, human review, or a model as a judge), and the process that runs them on every change. It is a real and growing specialism inside AI engineering, and a strong angle for juniors because few people do it well.
- Resource· GuideLangGraph DocumentationThe official docs for LangGraph, the low-level orchestration framework for stateful, long-running agents in Python and JavaScript: graphs of nodes and edges, persistence with checkpointers, interrupts for human approval, memory, streaming and deployment. Free and open source under the MIT licence.
- Resource· PlatformLangSmith DocumentationThe docs for LangSmith, LangChain's platform for tracing, evaluating and monitoring LLM apps and agents. It works with or without LangChain, integrates with OpenAI, Anthropic, the Vercel AI SDK, Pydantic AI and more, and has a free Developer plan for one seat with up to 5,000 base traces a month.
- Resource· GuideLangChain DocumentationThe official docs for LangChain, the open-source framework for building LLM apps and agents. It gives you one interface to many model providers and create_agent, a small configurable agent harness built on LangGraph, with LangSmith for tracing. Read it to judge what a framework adds over plain SDK code.
- Resource· GuideOWASP Top 10 for Agentic ApplicationsThe OWASP Gen AI Security Project's peer-reviewed list of the ten most critical security risks for AI agents, published in December 2025: goal hijack, tool misuse, identity and privilege abuse, agentic supply chain, unexpected code execution, memory poisoning and more, each with real incidents and mitigations. Free.
- Resource· ToolDeepEvalAn open source evaluation framework for LLM apps and agents, built to feel like pytest: write test cases, pick metrics such as task completion, tool correctness and argument correctness, trace agent steps with @observe and run everything with deepeval test run. Python first, with a TypeScript package too.
Checked against 10 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- LangGraph: Run a local server (langgraph new, langgraph dev)
- LangGraph: Application structure
- LangGraph CLI and langgraph.json reference
- LangGraph: Interrupts (human in the loop)
- LangSmith: Evaluate a graph
- Template: new-langgraph-project
- Template: react-agent
- agentevals (trajectory evaluators)
- openevals
- langchain-mcp-adapters
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Best practices
See all- Best Practices for Building AI AgentsHow to design AI agents that finish real tasks: when to use one, tool design, context and memory, control loops, MCP and agent security, and evaluating agent runs.
- Best Practices for Building LLM AppsHow to build LLM apps and agents that hold up in production: prompts, evals, prompt injection, tool permissions, cost, logging and privacy.
- Best Practices for AI Coding AssistantsHow to get reliable code from AI coding assistants and agents: instruction files, task prompts, verification, review, security, dependencies and session hygiene.
Checklists
See all- AI Agent Security ChecklistAn AI agent and MCP security checklist: least-privilege tools, MCP server auth, prompt injection through tool output, approvals, sandboxing, secrets, audit logs and supply chain.
- LLM Evaluation ChecklistAn LLM evaluation checklist: success criteria, eval datasets, code and model graders, judge calibration, agent evals, safety tests and production monitoring, with how to verify each check.
Work with me
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com