Getting Started
First-time setup: from zero to deployed.
Note
Bootstrap is a one-time setup per GitHub Environment. After successful bootstrap and first deployment, use the feature branch workflow described in Development.
Prerequisites
Required:
- Terraform >= 1.14.0
- Google Cloud SDK (gcloud CLI)
- GitHub CLI (gh)
- Python 3.13+
- uv package manager
- jq command-line JSON processor (for parsing Terraform output)
GCP Project:
- Create a new GCP project (or use existing)
- Enable billing
- Owner role
GitHub Repository:
- Create a new repository from this template
- Admin access (for GitHub Environments and Variables)
Bootstrap CI/CD
Bootstrap creates the infrastructure for automated deployments:
- Workload Identity Federation for keyless GitHub Actions authentication
- Artifact Registry for Docker image storage with cleanup policies
- Remote Terraform state (GCS) for bootstrap and main module — bucket created by pre-bootstrap
- GitHub Environment and Variables for CI/CD
1. Create State Buckets (Pre-Bootstrap)
Pre-bootstrap creates the GCS state buckets used by bootstrap and the main module. Run it before bootstrapping each environment — start with dev only, or provision all three environments at once.
cp terraform/bootstrap/pre/terraform.tfvars.example terraform/bootstrap/pre/terraform.tfvars
# Edit terraform.tfvars: set agent_name and GCP project IDs
terraform -chdir=terraform/bootstrap/pre init
terraform -chdir=terraform/bootstrap/pre apply
See Bootstrap Reference: Pre-Bootstrap for scope options (dev-only, full production, incremental) and how to skip pre-bootstrap if you already have a GCS bucket.
2. Configure
Dev-only mode (default): bootstrap only the dev environment.
cp terraform/bootstrap/dev/terraform.tfvars.example terraform/bootstrap/dev/terraform.tfvars
# Edit terraform.tfvars with your values
Required variables in terraform/bootstrap/dev/terraform.tfvars:
- project - GCP project ID for dev environment
- region - GCP Compute region (e.g., us-central1)
- google_cloud_location - Vertex AI model endpoint location (e.g., global)
- agent_name - Unique identifier (e.g., my-agent) — must match pre-bootstrap
- terraform_state_bucket - Bucket name from pre-bootstrap output (terraform_state_buckets.dev)
- repository_owner - GitHub username or organization
- repository_name - GitHub repository name
Refer to terraform.tfvars.example for required variables you customized for your agent
Note
For production mode (dev → stage → prod), see Infrastructure.
3. Authenticate
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID # Optional
gh auth login
4. Bootstrap
terraform -chdir=terraform/bootstrap/dev init \
-backend-config="bucket=$(terraform -chdir=terraform/bootstrap/pre output -json terraform_state_buckets | jq -r '.dev')"
terraform -chdir=terraform/bootstrap/dev apply
5. Verify
See Bootstrap Reference for complete bootstrap setup instructions.
Deploy
GitHub Actions deploy the agent resources:
- VPC network with Private Services Access for Cloud SQL private IP
- Cloud SQL instance for session persistence (SESSION_SERVICE_URI) with private IP only
- Bastion host running Auth Proxy for local developer access via IAP tunnel
- Agent Engine for memory persistence (MEMORY_SERVICE_URI)
- GCS bucket for artifact storage (ARTIFACT_SERVICE_URI)
- Cloud Run service with Auth Proxy sidecar and direct VPC egress
- Service account with least-privilege IAM bindings
- Additional cloud resources you customized for your agent
1. Create Pull Request
# Create feature branch
git checkout -b feat/initial-setup
# Commit any initial customizations
git add .
git commit -m "feat: initial setup"
# Push branch
git push origin feat/initial-setup
# Create PR
gh pr create --title "feat: initial setup" --body "Initial agent deployment"
2. Review and Merge
- Review the Terraform plan in the PR comments
- Verify the planned infrastructure changes
- Merge the PR (triggers deployment to dev environment)
3. Monitor Deployment
# View workflow runs
gh run list --workflow=ci-cd.yml --limit 5
# Watch logs (use run ID from list)
gh run view <run-id> --log
# Or: view in browser
gh run view <run-id> --web
Deployment flow:
1. Build Docker image
2. Run Terraform plan (infrastructure changes)
3. Deploy to Cloud Run (default environment)
4. Report outputs in job summary
4. Get Deployment Info
Save cloud resource values from the job summary to use in the next step.
Run the Agent
Configure your local .env with cloud resource values from the deployment, then run the agent.
1. Create .env File
2. Add Cloud Resource Values
Add the values from the deployment job summary to .env:
BASTION_INSTANCE=agent-name-dev-bastion
BASTION_ZONE=us-central1-b
SESSION_SERVICE_URI=postgresql+asyncpg://YOUR_SERVICE_ACCOUNT@project.iam:@localhost:5432/agent_sessions
MEMORY_SERVICE_URI=agentengine://projects/YOUR_PROJECT_ID/locations/YOUR_LOCATION/reasoningEngines/YOUR_ENGINE_ID
ARTIFACT_SERVICE_URI=gs://YOUR_BUCKET_NAME
# Add values for resources you customized for your agent
Set TELEMETRY_NAMESPACE to a unique value (e.g., your name) so teammates can filter to your traces in Cloud Trace.
Enable the development web interface in your .env:
See Environment Variables: Cloud Resources for where to find each value and a complete configuration reference.
3. Run the Local Agent
Standard development (Docker Compose mirrors production, connects to cloud resources by reading .env values):
Important
Docker Compose requires roles/iap.tunnelResourceAccessor on your Google account for the IAP tunnel to the bastion host. Grant via GCP Console (IAM) or gcloud projects add-iam-policy-binding.
Local-only (no cloud resource dependency):
Note
uv run server reads .env and attempts to connect to cloud resources with the URIs configured above. To run fully local (SQLite sessions, in-memory storage), comment out SESSION_SERVICE_URI, MEMORY_SERVICE_URI, and ARTIFACT_SERVICE_URI from .env.
Both modes export traces and structured logs to Cloud Trace and Cloud Logging automatically.
See Development for the full local development workflow including testing and code quality.
4. Run the Remote Agent
Authenticate to the deployed agent service using the Cloud Run proxy.
# Service name format: ${AGENT_NAME}-${environment} (e.g., agent-foundation-dev)
gcloud run services proxy <service-name> --project <project-id> --region <region> --port 8000
# In another terminal, test the health endpoint
curl http://localhost:8000/health
# Expected response: {"status": "ok"}
# Stop proxy: Ctrl+C
Tip
Enable the deployed remote agent web interface (optional)
To access the same dev UI available locally, set SERVE_WEB_INTERFACE=TRUE in the dev GitHub Environment variables and re-deploy:
Then re-run the latest CI/CD workflow (Actions tab → CI/CD Pipeline → Re-run jobs).
Once deployed, the web UI is available at http://localhost:8000 via the proxy.
See Cloud Run proxy documentation for details.
Next Steps
Local Development:
- See Development for feature branch workflow, testing, and code quality
Infrastructure & CI/CD:
- See Infrastructure for deployment modes, pipeline behavior, and operations
Observability:
- View traces in Cloud Trace
- View logs in Logs Explorer
- See Observability for query examples