Gemini platform Architecture and Engineering Guide
This skill is the reference system for designing, engineering, and validating enterprise-grade Gemini platform architectures across multi-project hierarchies, hybrid/cross-cloud networks, zero-trust identity boundaries, and inline safety/policy enforcement planes.
Usage Attribution
MUST READ: Before executing any gcloud, REST API, or MCP command, you
MUST read and follow the instructions in
Usage Attribution [blocked].
[!IMPORTANT] Architectural Scope and Reference Discipline: Use
SKILL.mdto select the target topology, egress mode, ingress pattern, and governance plane, then consult the authoritativereferences/*.mdmanual for exact CLI commands, REST/YAML schemas, Common Expression Language (CEL) expressions, and Python Agent Development Kit (ADK) runtime code (references/*.mdis the single source of truth for all implementation syntax). When remote Model Context Protocol (MCP) tools (such as the Google Developer Knowledge MCP server or Google-managed MCP endpoints) are available, prefer remote MCP tool invocation over raw CLI/REST commands. Do not execute unrequested live mutations against customer projects when asked for architectural designs.
[!CAUTION] Human Approval Gate for Sensitive Operations: Always prompt the user for explicit confirmation before executing commands or applying configurations that grant permissive Identity and Access Management (IAM) bindings (
roles/iap.egressor,roles/compute.networkUser,roles/networkservices.admin), modify Organization Policies (constraints/iam.managed.disableAccessPolicyBinding), update Unified Access Policy (UAP) or VPC Service Controls (VPC-SC) policies, or delete resources (RESTDELETE ...?force=trueor CLI--quiet).
Prerequisites, Authentication, Region, and Billing Setup
- Google Cloud SDK, Authentication, and Project Setup:
-
Install the Google Cloud SDK (
gcloud) and authenticate CLI and Application Default Credentials (gcloud auth login && gcloud auth application-default login, or setGOOGLE_APPLICATION_CREDENTIALS). -
Select or create the target project (
gcloud projects create {project_id}/gcloud config set project {project_id}), set the default region (gcloud config set compute/region {region}, defaulting tous-central1; see Google Cloud Locations), and enable required APIs:
-
- Billing, Least-Privilege IAM, and Product Terminology:
- Verify an active billing account is attached (
gcloud billing projects describe {project_id} --format="value(billingEnabled)") across{host_project_id},{gov_project_id},{runtime_project_id}, and{mcp_project_id}(required even when evaluating free-tier allowances; review Google Cloud Pricing). - Grant explicit least-privilege IAM roles (
roles/aiplatform.user,roles/networkservices.admin,roles/compute.networkAdmin,roles/compute.networkUser,roles/iap.egressor, or a custom role withnetworkservices.agentGateways.get,networkservices.agentGateways.use,networkservices.operations.get) rather than primitiveroles/ownerorroles/editor. - Use approved product names: Gemini platform,
Agent Runtime (
reasoningEngines), Agent Gateway (240.0.0.2:443), Agent Connectivity Template (ACT), Agent Registry, and Unified Access Policy (UAP Policy V2) / Semantic Governance Policy (SGP).
- Verify an active billing account is attached (
3-Phase Architect Workflow and Decision Tree
- Phase 1 — Scope Verification and Architecture Discovery:
- Scope Boundaries and Single-Region Discovery: Decline generic Google
Cloud IAM/Compute/Storage debugging unrelated to the Gemini platform
stack or requests to run broad multi-region live project scanning loops,
pointing instead to
gcloud ai reasoning-engines list --region={region}. - Architecture Design and Engineering: Identify the project
hierarchy (
Host,Governance Hub,Runtime Spoke,Tool/MCP Spoke), egress mode (ALL_TRAFFICvsPRIVATE_RANGES_ONLY), policy plane (UAP V2, SGP, Model Armor), and target output format (topology specification,gcloudCLI commands, or REST/YAML manifests).
- Scope Boundaries and Single-Region Discovery: Decline generic Google
Cloud IAM/Compute/Storage debugging unrelated to the Gemini platform
stack or requests to run broad multi-region live project scanning loops,
pointing instead to
- Phase 2 — Draft Architecture Plan and Resource Mapping:
- Synthesize the topology diagram, project/VPC layout, IAM bootstrap matrix, and security controls using the Domain Router and Symptom Matrix, and map each manual's canonical REST/YAML schema and CLI commands into the target deployment artifacts.
- Phase 3 — Post-Deployment and Audit Log Verification:
- Pair every architecture design with the Post-Deployment and Cloud Audit
Log Verification checklist
(
references/topologies_and_project_layouts.md) and runtime query validation (references/agent_runtime_and_identity.md).
- Pair every architecture design with the Post-Deployment and Cloud Audit
Log Verification checklist
(
Domain Router and Symptom Matrix
Each reference manual in references/ is the single source of truth for its
domain's CLI commands, REST/YAML schemas, quotas, and CEL expressions. Always
read the corresponding reference manual before generating configurations or
answering domain-specific questions:


