Opinionated, production-ready LLM Agent deployment with enterprise-grade infrastructure
A comprehensive template for building and deploying LLM Agents, including those built using Google Agent Development Kit (ADK) to production. This is a complete, battle-tested foundation with automated CI/CD, managed state persistence, custom observability, and proven cloud infrastructure.
Built for teams who need to move beyond prototypes and ship production AI agents with confidence.
- Opinionated foundation: Single optimized path (GitHub Actions + Terraform) built for extension
- Low-level control: Direct infrastructure management for teams who need flexibility and performance without the CLI abstraction
- Optimized Docker builds: Multi-stage builds with uv (~200MB images, fast rebuilds with layer caching)
- Developer experience: File sync with auto-restart via Docker Compose watch mode for fast feedback
- Code quality: Strict type checking (mypy), 100% test coverage, modern linting (ruff)
- Template-ready: One-command initialization script for rapid project setup
- Automated CI/CD: GitHub Actions with Terraform IaC, smart PR automation with plan comments
- Automated code reviews: Claude Code integration in CI
- Cloud Run deployment: Production-grade hosting with regional redundancy and autoscaling
- Environment isolation: Multi-environment deployments (dev/stage/prod)
- Global scalability: Create multi-region deployments by adding External Application Load Balancer
- Database sessions: Cloud SQL Postgres for durable conversation state
- Artifact storage: GCS-backed persistent storage for session artifacts
- Custom observability: OpenTelemetry instrumentation with full trace-log correlation
- Hardened Cloud SQL: Private IP only, IAM database auth (no passwords), enforced TLS, enforced Auth Proxy (no direct connections)
- Workload Identity Federation: Keyless CI/CD authentication (no service account keys)
- Non-root containers: Security-hardened runtime with least-privilege IAM
- Health checks: Kubernetes-style probes with startup grace periods
Run the agent with no cloud dependencies: Development: Quick Start
Important
Complete deployment first to create required resources (Cloud SQL, Agent Engine, GCS buckets, other agent-specific resources) before running locally with cloud persistence.
Note
The project starts in dev-only mode (single environment) by default. To enable production mode with staged deployments (dev → stage → prod), see Infrastructure: Deployment Modes.
Follow three steps to get started:
- Bootstrap CI/CD — provision WIF, Artifact Registry, GCS state bucket, and GitHub Environments
- Deploy — merge a PR to trigger deployment to Cloud Run with Cloud SQL sessions, Agent Engine memory, and artifact storage
- Run the Agent — start a local agent or test the remote agent via the Cloud Run proxy
See Getting Started for the complete walkthrough.
See docs/ for complete documentation.
- Getting Started - Prerequisites, bootstrap, deploy, run
- Development - Local workflow, Docker, testing, code quality
- Infrastructure - Deployment modes, CI/CD, protection strategies, IaC
- Environment Variables - Complete configuration reference
- Observability - OpenTelemetry traces and logs
- Troubleshooting - Common issues and solutions
- Template Management - Syncing upstream agent-foundation changes