🤖 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
- Cloud SQL Scaling and Reliability - Instance tiers, backups, HA, connection pooling, monitoring
Security
- Security Posture - Defense-in-depth rationale and architectural security decisions
Operations
- ADK Origin Check Middleware - Origin validation, CORS interaction, and ALLOW_ORIGINS configuration
- OpenTelemetry Architecture - ADK coexistence, instrumentation strategy, dependency management
Development
- Testing Strategy - Detailed testing patterns and organization
- 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