esmeralda / src
llms.txt25 starsChanged 8 days agoApache-2.0View on GitHub
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…
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- apps/agents/AGENTS.mdAGENTS.md
- apps/services/AGENTS.mdAGENTS.md
- infrastructure/AGENTS.mdAGENTS.md
- packages/esmeralda/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
The file
Files
llms.txt
# 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 `<LLMTokenQuota>` enforcement, and live partner conformance probes (`uv run esmeralda verify --partner`). ## 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. Reference & Contributing - [5.1 Make Targets](https://google.github.io/esmeralda/reference/make-targets/): every Make target, generated from the Makefile. - [5.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. - [5.3 Code of Conduct](https://google.github.io/esmeralda/code-of-conduct/): community standards.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.