{"id":49429432,"url":"https://github.com/chuckconway/ai-agent-blueprint","last_synced_at":"2026-04-29T11:06:26.280Z","repository":{"id":352741202,"uuid":"1216426283","full_name":"chuckconway/ai-agent-blueprint","owner":"chuckconway","description":"Production-ready starter template for AI agent web applications. FastAPI + React + Agno SDK with full quality tooling.","archived":false,"fork":false,"pushed_at":"2026-04-20T22:51:14.000Z","size":120,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T00:35:06.113Z","etag":null,"topics":["ai-agent","blueprint","claude-code","fastapi","react","template","typescript"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chuckconway.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-20T22:29:32.000Z","updated_at":"2026-04-20T22:51:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chuckconway/ai-agent-blueprint","commit_stats":null,"previous_names":["chuckconway/ai-agent-blueprint"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/chuckconway/ai-agent-blueprint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chuckconway%2Fai-agent-blueprint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chuckconway%2Fai-agent-blueprint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chuckconway%2Fai-agent-blueprint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chuckconway%2Fai-agent-blueprint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chuckconway","download_url":"https://codeload.github.com/chuckconway/ai-agent-blueprint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chuckconway%2Fai-agent-blueprint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32422642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T06:29:02.080Z","status":"ssl_error","status_checked_at":"2026-04-29T06:29:00.631Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","blueprint","claude-code","fastapi","react","template","typescript"],"created_at":"2026-04-29T11:06:24.813Z","updated_at":"2026-04-29T11:06:26.269Z","avatar_url":"https://github.com/chuckconway.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Agent Blueprint\n\n**Build AI-powered web applications that work — and keep working as they grow.**\n\nA production-ready starter template for AI agent applications. Clone it, point your AI coding assistant at it, and start building. The blueprint handles the architecture, quality guardrails, and infrastructure so you can focus on your idea.\n\n## Getting Started\n\nThe easiest way to use this blueprint is to **tell your AI coding assistant to set it up for you.** If you're using [Claude Code](https://claude.ai/code), [Cursor](https://cursor.com), or a similar AI coding tool, just say:\n\n\u003e \"Use https://github.com/chuckconway/ai-agent-blueprint as the template for my new project. Set it up and get it running.\"\n\nYour AI assistant will read the blueprint, understand the structure, install what's needed, and get everything running. The [CLAUDE.md](CLAUDE.md) file in this repo is specifically designed to give AI assistants all the context they need to work within this project's conventions.\n\nThat's the recommended path. Your AI assistant knows how to handle the technical setup so you can focus on what you're building.\n\nIf you want to understand what's happening under the hood, or if your AI assistant needs a reference, the full manual setup instructions are below.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eManual Setup Instructions\u003c/strong\u003e (click to expand)\u003c/summary\u003e\n\n### What You'll Need to Install\n\nBefore you begin, you'll need a few tools on your computer. If any of these are new to you, don't worry — each link below has step-by-step installation guides for Windows, Mac, and Linux.\n\n| Tool | What It Is | Where to Get It |\n|------|-----------|----------------|\n| **Git** | Version control — tracks changes to your code so you can undo mistakes and collaborate | [git-scm.com/downloads](https://git-scm.com/downloads) |\n| **Docker** | Runs your app and its services (database, cache) in isolated containers so everything works the same on every computer | [docker.com/get-started](https://www.docker.com/get-started/) |\n| **Node.js** | Runs the frontend (web interface) development tools. Installing Node.js also installs **npm**, which manages frontend code packages | [nodejs.org](https://nodejs.org/) — download the LTS (Long Term Support) version |\n| **Python 3.12+** | The programming language the backend is written in | [python.org/downloads](https://www.python.org/downloads/) |\n| **uv** | A fast tool for installing Python packages (similar to pip, but much faster) | [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/) |\n\n### Step 1: Create Your Project\n\nOn this GitHub page, click the green **\"Use this template\"** button near the top of the page, then click **\"Create a new repository.\"** Give your project a name and click **Create repository**.\n\nNow you need to download your new project to your computer. Open a **terminal** (on Mac: search for \"Terminal\" in Spotlight; on Windows: search for \"Command Prompt\" or \"PowerShell\" in the Start menu) and type:\n\n```bash\ngit clone https://github.com/YOUR-USERNAME/my-project.git\ncd my-project\n```\n\nReplace `YOUR-USERNAME/my-project` with whatever you named your repository.\n\n### Step 2: Configure Your Settings\n\nYour project needs a few settings — most importantly, an API key for the AI provider you want to use.\n\n**What's an API key?** It's like a password that lets your application talk to an AI service (Claude, GPT, or Gemini). You get one by creating an account with the AI provider:\n- **Anthropic (Claude)**: [console.anthropic.com](https://console.anthropic.com/)\n- **OpenAI (GPT)**: [platform.openai.com](https://platform.openai.com/)\n- **Google (Gemini)**: [aistudio.google.com](https://aistudio.google.com/)\n\nOnce you have your API key, run this in your terminal:\n\n```bash\ncp env.example .env\n```\n\nThis creates a settings file called `.env` from the included example. Open `.env` in any text editor (even Notepad works) and fill in:\n\n- **`LLM_PROVIDER`** — which AI to use: `anthropic`, `openai`, or `google`\n- **The matching API key** — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GOOGLE_API_KEY`\n\nEverything else has sensible defaults that work out of the box.\n\n### Step 3: Start the Backend\n\nThis one command starts your database, cache, API server, and background worker all at once:\n\n```bash\ndocker compose up\n```\n\nThe first time you run this, Docker downloads everything it needs. This can take a few minutes depending on your internet speed. After the first time, it starts in seconds.\n\nYou'll see a stream of log messages in the terminal. That's normal — it's showing you what each service is doing. Leave this terminal window open.\n\n### Step 4: Start the Frontend\n\nOpen a **second terminal window** (keep the first one running) and type:\n\n```bash\ncd my-project/ui\nnpm install\nnpm run dev\n```\n\n- `npm install` downloads the frontend's code packages. You only need to do this once.\n- `npm run dev` starts the web interface development server.\n\nYou'll see a message saying the server is running, usually at `http://localhost:5173`.\n\n### Step 5: Open Your App\n\nOpen your web browser and go to **http://localhost:5173**\n\nYou'll see a login page. Enter:\n- **Email**: `dev@example.com`\n- **Password**: `dev`\n\nYou're in. You'll see a chat interface. Type a message and your AI agent will respond.\n\n### Installing the Superpowers Plugin (Optional)\n\nIf you're using [Claude Code](https://claude.ai/code) as your AI coding assistant, the [Superpowers](https://github.com/obra/superpowers) plugin gives your assistant structured workflows for brainstorming, debugging, testing, and code review. To install it, run this in your terminal:\n\n```bash\nclaude plugins install superpowers@claude-plugins-official\n```\n\nThis is optional but recommended if you're using Claude Code for development.\n\n\u003c/details\u003e\n\n---\n\n## Why This Exists\n\nBuilding with AI agents is deceptively easy to start and surprisingly hard to sustain. Here's what typically happens:\n\n1. **Day 1**: You get a chat interface working. The AI responds. It feels magical.\n2. **Week 2**: You add features. Things start breaking in unexpected ways. The AI agent calls the wrong tool. Responses are slow. You're not sure where to put new code.\n3. **Month 2**: The codebase is a maze. Every change breaks something else. You're afraid to deploy. Your AI agent works great in testing and fails in production. Technical debt is piling up faster than features.\n\nThis isn't a skill problem — it's a structure problem. Without the right foundations, even experienced engineers end up with fragile, hard-to-change code. And if you're building with AI coding assistants (Claude Code, Cursor, Copilot), the problem compounds: **an AI assistant without guardrails will write working code that slowly becomes unworkable code.**\n\n## What This Blueprint Gives You\n\n### An AI Agent That Does Things (Not Just Chats)\n\nMost AI demos stop at chat. Real AI applications need agents that can **take actions** — look up data, call APIs, run calculations, interact with your business logic. This blueprint includes:\n\n- **Tool system**: Teach your agent new capabilities by writing a Python function and adding a decorator. That's it.\n- **Streaming responses**: Users see the AI thinking and responding in real-time, not staring at a loading spinner.\n- **Provider flexibility**: Start with Claude, switch to GPT, try Gemini — change one setting, not your codebase.\n- **Interceptor pipeline**: Add logging, content filtering, or usage tracking without touching your agent logic.\n\n### Quality Guardrails That Run Automatically\n\nThis is where the blueprint pays for itself. When you're building with AI coding assistants, the assistant doesn't inherently know your project's rules. It will write code that works *right now* but violates patterns that matter *over time*. The blueprint includes **18 automated checks** that run before every commit:\n\n- **Code formatting and style** — enforced automatically, not by code review arguments\n- **Type safety** — catches bugs before they reach production\n- **Architecture enforcement** — prevents the spaghetti code that makes projects unmaintainable\n- **Dead code detection** — keeps the codebase lean\n- **Quality ratchet** — code quality can only improve over time, never degrade\n\nHere's the thing: **you don't need to understand any of these tools.** They run silently in the background. If your AI assistant tries to write code that breaks the rules, the checks catch it and the assistant fixes it before you ever see it. It's like having a senior engineer reviewing every line, 24/7.\n\n**Without these guardrails**, AI-assisted code tends to accumulate shortcuts — unused imports, untyped functions, circular dependencies, overly complex logic. Each one is small. Together, after a few months, they make the codebase hostile to change. The blueprint prevents that drift from day one.\n\n### A Web Application, Not Just a Backend\n\nYou get a complete, working application:\n\n- **Login page** → authenticate → **Chat interface** → talk to your AI agent\n- Built with React, TypeScript, and Tailwind CSS — the same stack used by most modern web applications\n- Mobile-friendly, dark theme, clean design\n- Ready to extend with your own pages and features\n\n### A Database and Background Jobs\n\nMost AI apps need to remember things and do work in the background. Included:\n\n- **PostgreSQL** for storing users, conversations, and your application data\n- **Safe database changes** — a migration system that lets you update your database without breaking your running application\n- **Background task queue** — for long-running operations that shouldn't block a user's request (sending emails, processing documents, calling slow APIs)\n\n### Deployment-Ready Infrastructure\n\nWhen you're ready to go live:\n\n- **Docker** packages your entire application into a container that runs anywhere\n- **Docker Compose** runs everything locally with one command\n- **Kubernetes manifests** are included for when you're ready to deploy to production cloud infrastructure\n\n## Who This Is For\n\n- **Builders who work with AI coding assistants** — The guardrails keep your AI assistant productive without letting it create a mess.\n- **Developers starting a new AI project** — Skip weeks of infrastructure setup. Start building features on day one.\n- **Teams that want consistency** — Every project built from this blueprint follows the same conventions, making it easy to switch between projects or onboard new people.\n- **Non-engineers building AI products** — You don't need to be a software engineer to use this. If you can work with an AI coding assistant, the blueprint provides the structure. You bring the ideas.\n\n---\n\n## What You'll Customize\n\nThe blueprint is opinionated but not rigid. Here's what you'll change as you build your product:\n\n| What | Where | Example |\n|------|-------|---------|\n| Add agent capabilities | `src/app/agent/example_tools.py` | \"Look up a customer\", \"Send an email\", \"Query our database\" |\n| Add pages | `ui/src/features/` | Dashboard, settings, admin panel |\n| Add data models | `src/app/core/models/` | Products, orders, documents — whatever your app needs |\n| Add API endpoints | `src/app/api/routes/` | New endpoints for your frontend |\n| Add background jobs | `src/app/worker/tasks/` | Nightly reports, data sync, document processing |\n| Switch authentication | `.env` → `AUTH_PROVIDER=google` | Google sign-in for real users |\n| Switch AI provider | `.env` → `LLM_PROVIDER=openai` | Change with one line, no code changes |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eProject Structure\u003c/strong\u003e (click to expand)\u003c/summary\u003e\n\n```\nsrc/app/\n  api/          # Web endpoints, authentication, request handling\n  agent/        # AI agent: tools, streaming, provider adapters\n  core/         # Your business logic, data models, database\n  worker/       # Background tasks and scheduled jobs\n\nui/             # React web application\nmigrations/     # Database schema changes\nscripts/        # Quality checks and development tools\nskills/         # AI assistant workflow definitions\nk8s/            # Production deployment manifests\ndocs/           # Architecture docs, lessons learned\n```\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) for detailed descriptions of each layer and how data flows through the system.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTech Stack\u003c/strong\u003e (click to expand)\u003c/summary\u003e\n\n| Layer | What It Does | Technology |\n|-------|-------------|-----------|\n| **API** | Handles web requests, authentication | Python, FastAPI |\n| **Agent** | AI orchestration, tool calling, streaming | Agno SDK (supports Anthropic, OpenAI, Google) |\n| **Database** | Stores your application data | PostgreSQL, SQLAlchemy |\n| **Task Queue** | Background job processing | SAQ with Redis |\n| **Frontend** | The web interface your users see | React, TypeScript, Tailwind CSS |\n| **Quality** | Automated code checks | 18 tools that run silently before every commit |\n| **CI/CD** | Automated testing and deployment | GitHub Actions, Docker |\n| **Deployment** | Running in production | Docker Compose or Kubernetes |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEngineering Practices\u003c/strong\u003e (click to expand)\u003c/summary\u003e\n\nYou don't need to understand these to use the blueprint — they work automatically. But if you're curious about *why* it's structured the way it is:\n\n- **Layered architecture** — Code is organized into layers with strict rules about which layer can talk to which. This prevents the tangled dependencies that make projects unmaintainable.\n- **Quality ratchet** — Code quality metrics are tracked and can only improve, never degrade. Every commit leaves the codebase a little better than it found it.\n- **Local CI = Remote CI** — The same checks run on your machine before you push and on the server after you push. No surprises.\n- **Compound learning** — When you solve a hard problem, the solution is captured so the same mistake never happens twice.\n- **Tracer bullets** — Build a thin slice through all layers first, verify it works, then expand. This catches problems early when they're cheap to fix.\n\nThese practices are documented in [CLAUDE.md](CLAUDE.md), which your AI coding assistant reads automatically. It follows the rules so you don't have to enforce them manually.\n\n\u003c/details\u003e\n\n## Documentation\n\n- **[CLAUDE.md](CLAUDE.md)** — The rules your AI assistant follows. This is the most important file in the project — it's what makes the guardrails work.\n- **[ARCHITECTURE.md](ARCHITECTURE.md)** — How the pieces fit together. Read this if you want to understand the system design.\n- **[docs/lessons-learned/](docs/lessons-learned/)** — A place to capture debugging insights so the same mistake never happens twice.\n\n## Based On\n\nThis blueprint is built from patterns proven in production and documented in the [Agent Engineering Playbook](https://github.com/chuckconway/agent-engineering-playbook).\n\n## License\n\nMIT — use it for anything.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchuckconway%2Fai-agent-blueprint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchuckconway%2Fai-agent-blueprint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchuckconway%2Fai-agent-blueprint/lists"}