An opinionated, commercial-grade blueprint designed to accelerate the path to production for AI Agents.
Architecture | Capabilities | Documentation Hub
"O que está embaixo é como o que está no alto, e o que está no alto é como o que está embaixo."
— A Tábua de Esmeralda (Hermes Trismegisto)
ESMERALDA is an opinionated, commercial-grade reference blueprint designed to accelerate the journey of autonomous AI Agents and MCP servers into production on Google Cloud Platform.
Built around an "Application-First, Decoupled Infrastructure" paradigm, the monorepo establishes a clean boundary between two worlds:
- Above (
/apps): AI and software engineers focus purely on intelligence, Gemini-powered reasoning, and tool integration (MCP & A2A) using the Google ADK — free from cloud infrastructure complexity. - Below (
/infrastructure): Platform engineers maintain a declarative, zero-trust infrastructure stack via Terragrunt & Terraform, featuring multi-environment isolation, cryptographic mTLS (SPIFFE) workload identity, private networking (Shared VPC & PSC), and centralized governance (Agent Gateway, Model Armor & FinOps).
- 🛡️ Enterprise Standard: Zero-trust security by default, SecOps audit trails, and strict enterprise compliance.
- 🤖 Multi-Agent Engine: Seamless agent-to-agent (A2A) collaboration and orchestration governed by Central Gateways and Private Service Connect.
- 🧠 Reasoning & Action Layer: Advanced reasoning powered by Gemini models and open tool standards with MCP.
- ⚡ Deployment Accelerator: End-to-end automation from local development to production through reproducible CI/CD pipelines and built-in observability.
flowchart TD
subgraph Clients["🌐 Ingress & Consumers"]
User["Client / Web UI"]
TestVM["Test Runner VM (IAP Tunnel)"]
end
subgraph Governance["🛡️ Central Governance & Security (Stage 5)"]
AGW["Central Agent Gateway\n(AGENT_TO_ANYWHERE)"]
MA["Model Armor\nGuardrails (PII / Injection)"]
AR["Central Agent Registry\n(Catalog & Endpoints)"]
FinOps["FinOps Telemetry\n& BigQuery Analytics"]
end
subgraph Agents["🧠 AI Reasoning Layer (Stage 4)"]
RootAgent["Root Coordinator Agent\n(Vertex AI Reasoning Engine)"]
A2AAgent["Mortgage Specialist Agent\n(Vertex AI Reasoning Engine / A2A)"]
end
subgraph Tools["🔌 MCP Tool Microservices (Stage 4)"]
DMS["Legacy DMS Server\n(Cloud Run)"]
Income["Income Verification Server\n(Cloud Run)"]
Email["Corporate Email Server\n(Cloud Run)"]
TaskDB[("Cloud SQL\nTask Store")]
end
subgraph Models["⚡ Google Foundation Models"]
Gemini["Gemini 3.7 Flash\n(Vertex AI API)"]
end
User -->|Ingress| RootAgent
TestVM -->|Private DNS| A2AAgent
RootAgent -->|A2A Protocol / PSC| A2AAgent
A2AAgent -->|mTLS SPIFFE / Egress| AGW
AGW -->|Policy Evaluation| MA
AGW -->|Authorized Egress| Gemini
A2AAgent -->|Private HTTP / PSC| DMS
A2AAgent -->|Private HTTP / PSC| Income
A2AAgent -->|Private HTTP / PSC| Email
A2AAgent -->|IAM Auth| TaskDB
AGW -.->|Audit Sinks| FinOps
| Pillar | Capability | Description |
|---|---|---|
| 🤖 Multi-Agent Engine | Agent-to-Agent (A2A) Protocols | Standardized asynchronous and synchronous inter-agent communication, enabling specialized agents to delegate and coordinate complex workflows. |
| 🛡️ Zero-Trust Governance | Central Agent Gateway & SPIFFE Identity | Centralized egress proxy enforcing mTLS cryptographic workload certificates, IAP IAM access boundaries, and Model Armor content sanitization. |
| 🔌 Tool Ecosystem | Model Context Protocol (MCP) | Decoupled, serverless tool microservices exposing corporate systems (DMS, email, payroll) via standardized MCP endpoints over Private Service Connect. |
| 📊 Observability & FinOps | OpenTelemetry & BQ Analytics | Native per-request token usage tracking, audit sinks, automated chargeback SQL views, and Cloud Monitoring golden signal dashboards. |
| 🏗️ Declarative Platform | 5-Stage Terragrunt Progression | Modular infrastructure stack isolating Projects (S1), Networking (S2), Security (S3), Workloads (S4), and Governance (S5) across environments. |
Explore in-depth documentation organized by domain:
- 🏗️ Platform Foundations (Stage 1-3) — Shared VPC, KMS CMEK encryption, IAM hierarchies, and Secret Manager architecture.
- 🤖 Workloads & Service Catalog (Stage 4) — Reasoning Engine deployment specs, MCP server contracts, and Swappable Ingress Gateways.
- 📊 AgentOps, Governance & FinOps (Stage 5) — Centralized monitoring, Multi-repo SDLC, and BigQuery FinOps views.
- 🤝 Contributing Guidelines — Code standards, PR workflow, and testing requirements.