🤖 Agent Foundation Documentation
Opinionated, production-ready LLM Agent deployment with enterprise-grade infrastructure.
This template provides a complete foundation for building and deploying LLM Agents to production. Get automated CI/CD, managed state persistence, custom observability, and proven cloud infrastructure out of the box.
Built for teams who need to move beyond prototypes and ship production AI agents with confidence.
Key Features
- 🐳 Optimized Docker builds - Multi-stage builds with uv (~200MB images, 5-10s rebuilds)
- 🏗️ Automated CI/CD - GitHub Actions + Terraform with smart PR automation
- 🌎 Multi-environment deployments - Production-grade dev/stage/prod isolation
- 💾 Database sessions - Cloud SQL Postgres for durable conversation state
- 🔭 Custom observability - OpenTelemetry with full trace-log correlation
- 🏰 Hardened Cloud SQL - Private IP only, IAM database auth, enforced TLS and Auth Proxy
- 🔐 Workload Identity Federation - CI/CD authentication (no service account keys)
Documentation Guide
First Time Setup
- Getting Started - Prerequisites, bootstrap, deploy, run
- Environment Variables - Complete configuration reference
Development
- Development - Local workflow, Docker, testing, code quality
- Infrastructure - Deployment modes, CI/CD, protection strategies, IaC
Operations
- Observability - OpenTelemetry traces and logs
- Troubleshooting - Common issues and solutions
Syncing Upstream Changes
- Template Management - Syncing upstream agent-foundation changes
References
Deep dives for optional follow-up:
Infrastructure
- Bootstrap - Complete bootstrap setup for both deployment modes
- Protection Strategies - Branch, tag, environment protection
- Deployment Modes - Multi-environment strategy and infrastructure
- CI/CD Workflows - Workflow architecture and mechanics
- Claude PR Review - Automated PR review setup: GitHub App, model auth paths, and workflow behavior
- Cloud SQL Scaling and Reliability - Instance tiers, backups, HA, connection pooling, monitoring
- Cloud Run Concurrency Tuning - Async runtime model and concurrency sizing
Security
- Security Posture - Defense-in-depth rationale and architectural security decisions
Operations
- ADK Origin Check Middleware - Origin validation, CORS interaction, and ALLOW_ORIGINS configuration
- Image Digest Resolution - Index vs platform digests, provenance verification, and digest-based debugging
- OpenTelemetry Architecture - ADK coexistence, instrumentation strategy, dependency management
Development
- Testing Strategy - Lane taxonomy and the unit-test guide
- Integration Tests - The Postgres + FastAPI lane: coverage, running locally, and CI
- Smoke Tests - The post-deploy lane: live-URL checks, authentication, running locally, and CI
- Agent Evals - The full agent-evaluation surface: formats, commands, metrics, and user simulation
- Code Quality - Tool usage and exclusion strategies
- Cloud Backend Options - Advanced options for uv run server with cloud backends
- Docker Compose Workflow - Watch mode, volumes, and configuration
- Dockerfile Strategy - Multi-stage builds and optimization
- MkDocs Setup - Documentation site setup and customization