# Esmeralda > Reference blueprint for running AI agents (Google ADK, A2A) and MCP tool servers in production on Google Cloud: a decoupled 6-layer Terragrunt/Terraform architecture (L0 CI/CD, L1 projects, L2 networking, L3 security & PKI, L4 governance with the Central Agent Gateway, L5 workloads) that enables multi-track parallelism across independent engineering teams. Agents run as BYOC images on Vertex AI Agent Engine with SPIFFE Agent Identity; private ingress flows through an internal HTTPS entry point (`*.esmeralda.internal`) with a built-in `direct` backend and swappable gateway adapters (Envoy, Apigee); and the `esmeralda` Python package provides both the agent runtime SDK and the operational CLI (`uv run esmeralda --help`) and MCP server (`uv run esmeralda mcp`). The running narrative follows a loan officer asking *"Can you verify Julian Sterling's income?"*: a CX orchestrator (`cx-mortgage-orchestrator`, Google ADK) delegates over A2A to an AI CoE specialist (`ai-coe-mortgage-specialist`), which invokes three Cloud Run MCP tool servers (`legacy-dms`, `income-verification`, `corporate-email`). Source code: https://github.com/google/esmeralda ## Overview - [Overview: Esmeralda Architecture & Documentation](https://google.github.io/esmeralda/): why enterprise agents stall, how decoupled layers enable multi-track parallelism, Julian Sterling's end-to-end request tour, and the 6 infrastructure layers. ## 1. Workloads, Catalog & Gateways (Layer 5) - [1.0 Overview: Workloads & Service Catalog](https://google.github.io/esmeralda/2-workloads-and-catalog/): meet the cast of Layer 5 workloads, the declarative `catalog` in `env.yaml`, and the dependency graph. - [1.1 Two Teams, Two Agents — Orchestration vs. Specialization (ADK & A2A)](https://google.github.io/esmeralda/2-workloads-and-catalog/03-ai-agents-and-database/): `cx-mortgage-orchestrator` (ADK) and `ai-coe-mortgage-specialist` (A2A) on Vertex AI Agent Runtime (BYOC, SPIFFE Agent Identity, Agent Gateway binding) and the private Cloud SQL task store. - [1.2 Wrapping Enterprise Systems as MCP Tool Servers](https://google.github.io/esmeralda/2-workloads-and-catalog/02-mcp-tool-servers/): FastMCP microservices on private Cloud Run (`legacy-dms`, `income-verification`, `corporate-email`), custom audiences, `tools.json` registration in Agent Registry, and local testing with `uv run esmeralda query`. - [1.3 The Private Front Door & Pluggable Gateways](https://google.github.io/esmeralda/2-workloads-and-catalog/01-ingress-gateways/): the `*.esmeralda.internal` entry point, service catalog, built-in `direct` routing backend, pluggable gateway adapter contract (`envoy`, `apigee`), host-by-host migration, and verification (`uv run esmeralda verify`). - [1.4 Partner API Management & Token Monetization with Apigee X](https://google.github.io/esmeralda/2-workloads-and-catalog/04-apigee-partner-gateway/): Apigee X (`partner.esmeralda.internal` / `10.0.1.3`) PSC NEG plumbing, tiered API Products (`bronze`, `silver`, `gold`), `partner-agents` and `partner-mcp` proxy policies, two-phase `` enforcement, and live partner conformance probes (`uv run esmeralda verify --partner`). - [1.5 One Gateway per Hop](https://google.github.io/esmeralda/2-workloads-and-catalog/05-gateway-per-hop/): the default gateway for every hop (entry point, Central Agent Gateway, Apigee X, Envoy, API Gateway model routing), alternatives and when to choose them, defaults per deployment profile, and the `env.yaml` switch for each hop. ## 2. Governance, Identity & AgentOps (Layer 4) - [2.0 Overview & Release Lifecycle](https://google.github.io/esmeralda/3-agentops-and-lifecycle/): multi-track SDLC, image promotion by digest, and central governance overview. - [2.1 Central Agent Gateway & Private PKI](https://google.github.io/esmeralda/3-agentops-and-lifecycle/01-central-agent-gateway/): how outbound agent egress, SPIFFE identity, the Agent Registry allowlist, private certificates, and BYOC containers fit together. - [2.2 Capability-Based & Semantic Governance](https://google.github.io/esmeralda/3-agentops-and-lifecycle/04-capability-based-governance/): division of responsibilities across Apigee X, GEAP Agent Identity (3LO), and Central Agent Gateway; Unified Access Policies (UAPs) and Natural Language Constraints (NLC). - [2.3 FinOps, Telemetry & Cross-Team Chargeback](https://google.github.io/esmeralda/3-agentops-and-lifecycle/03-centralized-monitoring-and-dashboards/): telemetry sinks, alerts, SLOs, Cloud Monitoring dashboards, and BigQuery token chargeback views. - [2.4 Day-2 Operations with the `esmeralda` CLI & MCP Server](https://google.github.io/esmeralda/3-agentops-and-lifecycle/04-operating-with-agents/): day-2 operations with `uv run esmeralda`, destroy guards, contract checks, and the read-only `esmeralda mcp` server. ## 3. Platform Foundations (Layers 1–3) - [3.0 Overview: Platform Foundations](https://google.github.io/esmeralda/1-platform-foundations/): overview of the foundational layers, architectural decisions, and how `env.yaml` drives them. - [3.1 Projects & FinOps Isolation (Layer 1)](https://google.github.io/esmeralda/1-platform-foundations/01-projects-and-finops/): per-team GCP projects, APIs, billing links, cost labels, and service identities. - [3.2 Private Networking, PSC & DNS (Layer 2)](https://google.github.io/esmeralda/1-platform-foundations/02-private-networking/): Shared VPC, subnets, PSC attachments, `*.esmeralda.internal` private DNS zone, and the reserved entry point IP. - [3.3 Security, SPIFFE Identity & PKI (Layer 3)](https://google.github.io/esmeralda/1-platform-foundations/03-security-iam-and-telemetry/): least-privilege service accounts, SPIFFE Agent Identity grants, CMEK encryption, Secret Manager, and the internal Root CA. ## 4. Esmeralda Library & CLI - [4.0 Overview: Esmeralda Library](https://google.github.io/esmeralda/4-esmeralda-library/): what the `esmeralda` runtime library and CLI do for every agent and operator. - [4.1 Developer Usage Guide](https://google.github.io/esmeralda/4-esmeralda-library/guide/): building ADK and A2A agents, calling MCP servers, local execution, and operating a checkout with `esmeralda mcp`. - [4.2 Package & CLI Reference](https://google.github.io/esmeralda/4-esmeralda-library/reference/): Python modules, CLI subcommands, environment variables, and telemetry schemas. ## 5. Multi-Cloud & Interoperability - [5.0 Why Multi-Cloud Agents](https://google.github.io/esmeralda/5-multi-cloud/): why agents end up on more than one cloud, the four principles (contracts, gateway per hop, attribution from authentication, fail closed), and inbound vs. outbound cross-cloud traffic. - [5.1 Identity Across Clouds](https://google.github.io/esmeralda/5-multi-cloud/01-identity-across-clouds/): workload identity federation, OIDC `iss#sub` verified at the gateway (Apigee cross-cloud shared flow), SPIFFE federation, mTLS, `federated` catalog callers, and fail-closed enforcement. - [5.2 Cross-Cloud Connectivity & Protocols](https://google.github.io/esmeralda/5-multi-cloud/02-cross-cloud-connectivity/): the gateway per hop (Apigee, Envoy, `direct`, Agent Gateway), network options (public endpoints, HA VPN, Cross-Cloud Interconnect), and A2A and MCP as interoperable protocols. - [5.3 Unified Observability & Chargeback](https://google.github.io/esmeralda/5-multi-cloud/03-unified-observability-and-chargeback/): the `esmeralda.usage` record as the normalized schema, producers on other clouds (OTel GenAI span adapter, OpenTelemetry Collector), BigQuery landing, and chargeback by verified team. - [5.4 Bringing an Agent from Another Cloud, End to End](https://google.github.io/esmeralda/5-multi-cloud/04-bringing-an-agent-from-another-cloud/): worked example of a synthetic underwriting agent on another cloud calling `ai-coe-mortgage-specialist`, with catalog entries and usage records. - [5.5 Status & Roadmap](https://google.github.io/esmeralda/5-multi-cloud/05-status-and-roadmap/): what is on `main`, in open pull requests, and planned for multi-cloud support. ## 6. Reference & Contributing - [6.1 Make Targets](https://google.github.io/esmeralda/reference/make-targets/): every Make target, generated from the Makefile. - [6.2 Contributing Guide](https://google.github.io/esmeralda/contributing/): CLA, local testing, docs build, dependency workflow, and conventions. - [AGENTS.md](https://github.com/google/esmeralda/blob/main/AGENTS.md): rules for AI coding agents working in the repository. - [6.3 Code of Conduct](https://google.github.io/esmeralda/code-of-conduct/): community standards.