This document guides you through the process of configuring VPC
connectivity when deploying an Agent Gateway so that it can
privately communicate with a VPC network in your organization.

Setting up VPC connectivity lets you do the following:

- **Enforce VPC egress for traffic** : Route traffic originating from your agents through your Private Service Connect network attachment into your VPC network using `PRIVATE_RANGES_ONLY` or `ALL_TRAFFIC` mode.
- **Static source IP address range**: Egress traffic uses the private IP address range of your Private Service Connect network attachment subnet as its source IP address. This static source IP range lets you configure firewall policies for your VPC network to govern traffic coming from the gateway.
- **Custom DNS resolution**: Resolve internal private domain names and external domain names directly from your agents using Cloud DNS peering.
- **Perimeter security**: Protect agent communications using VPC Service Controls service perimeters.
- **Private or self-signed certificate validation**: Connect to destinations that use private CAs or self-signed certificates.

To configure VPC connectivity, you create an
*Agent Gateway connectivity template*
(`AgentConnectivityTemplate`) where you define and manage egress networking
settings for your Agent Gateway instances.

## How VPC connectivity works

When you deploy an Agent Gateway with a connectivity
template, the gateway uses a Private Service Connect interface to
route outbound agent traffic into your designated VPC network.

### VPC egress modes

You configure how the gateway routes traffic through your network attachment
using the `vpcEgress` setting in your connectivity template.

- **Traffic to private IP address ranges (`PRIVATE_RANGES_ONLY`)**: Routes
  traffic destined only for private IP address ranges into your
  VPC network. Outbound traffic is routed into your VPC network
  only if the destination IP address falls into one of the following ranges:

  - **RFC 1918** : `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
  - **RFC 6598** : `100.64.0.0/10`
  - **Class E** : `240.0.0.0/4`
  - **`private.googleapis.com`** : `199.36.153.8/30`
  - **`restricted.googleapis.com`** : `199.36.153.4/30`
  - **PSC endpoints for Google APIs**: If you deploy a custom Private Service Connect endpoint for Google APIs using an internal private IP address in your VPC network, traffic to this endpoint is routed through your VPC network. Ensure that Cloud DNS peering is configured in the connectivity template so that Agent Gateway correctly resolves Google API domains to your internal PSC endpoint IP address.

  Requests to standard public Google APIs are handled automatically using
  Private Google Access, and internet-bound traffic is routed directly
  through Agent Gateway rather than through your
  VPC network.
- **Traffic to all IP address ranges (`ALL_TRAFFIC`)**: Routes all outbound
  traffic originating from your agents through your VPC
  network, including public internet, external SaaS APIs, and non-RFC 1918
  addresses.

  - **Routing and security** : Because this setting routes all outbound traffic into your VPC, you're responsible for managing its routing and security. Ensure that your VPC network has a default route (`0.0.0.0/0`) to forward this traffic to your outbound gateways or security appliances (such as next-hop firewalls or Cloud Interconnect interfaces).
  - **Public internet egress** : The Agent Gateway sends outbound traffic into your VPC network, where it exits to the public internet through a [Cloud NAT
    gateway](https://docs.cloud.google.com/nat/docs/overview) on the Private Service Connect network attachment subnet. If you assign [static external IP
    addresses](https://docs.cloud.google.com/nat/docs/ports-and-addresses#addresses) to the Cloud NAT gateway, remote services can allowlist your agents' egress traffic based on these source IP addresses.
  - **VPC Service Controls** : Egress mode must be set to `ALL_TRAFFIC` to support VPC Service Controls service perimeters.

### DNS resolution and traffic routing

By default, Agent Gateway resolves domain names using public
recursive DNS. If your agents need to access internal workloads, private tools,
or Google APIs hosted on private domain names in your VPC
network (such as `corp.internal.` or PSC endpoints), you can
configure Cloud DNS peering to forward DNS queries to your
network's private Cloud DNS managed zones.

The following table summarizes Cloud DNS peering requirements and
traffic routing behavior for different destinations when VPC
connectivity is configured in `ALL_TRAFFIC` mode:

| Traffic destination | Cloud DNS peering required? | DNS resolution | Egress path |
|---|---|---|---|
| **Private IP services** (RFC 1918 / internal) | **Yes** (for example, `corp.internal.`) | Resolves using Cloud DNS peering with your target VPC network's private Cloud DNS managed zone. | Traffic enters your VPC network through the network attachment to connect to internal workloads. |
| **Public hostnames with private IPs** (Split-horizon DNS) | **No** | Resolves using standard public recursive DNS at the gateway proxy without requiring Cloud DNS peering. | Traffic enters your VPC network through the network attachment to connect to internal workloads. |
| **Public internet \& SaaS APIs** (External domains) | **No** | Resolves using standard public recursive DNS at the gateway proxy without requiring Cloud DNS peering. | Traffic enters your VPC network through the network attachment and exits to the public internet using Cloud NAT configured on the subnet. |
| **Google Cloud APIs** (standard, without VPC Service Controls) | **No** | Resolves using standard public recursive DNS at the gateway proxy without requiring Cloud DNS peering. | Traffic enters your VPC network through the network attachment and is routed privately using Private Google Access enabled on the subnet, without using Cloud NAT or DNS peering. |
| **Google Cloud APIs** (with VPC Service Controls) | **Yes** (for `googleapis.com.`) | Resolves to the restricted Google API range (`199.36.153.4/30`) or internal Private Service Connect endpoints using a private Cloud DNS zone. | Traffic enters your VPC network through the network attachment to enforce VPC Service Controls perimeter security rules^[1](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-vpc-connectivity#vpcsc-note)^. |
[**Table:** DNS resolution and traffic routing in `ALL_TRAFFIC` mode]

^1^ If requests fail with VPC Service Controls violations such as
`NETWORK_NOT_IN_SAME_SERVICE_PERIMETER` or
`SECURITY_POLICY_VIOLATED` on `compute.googleapis.com` or
`dns.googleapis.com` that reference the host project, verify that the
host project is in the same perimeter as the gateway project.

### TLS certificate requirements

When routing egress traffic over HTTPS, Agent Gateway validates
the destination server's TLS certificate chain during the TLS handshake.
Certificate requirements for HTTPS connections depend on whether your target
endpoints use publicly trusted Certificate Authorities (CAs) or
private/self-signed CAs.

- **Public CAs** : By default, Agent Gateway trusts
  certificates issued by [publicly trusted Certificate Authorities
  (CAs)](https://docs.cloud.google.com/load-balancing/docs/backend-authenticated-tls-backend-mtls#public-roots-of-trust)
  that meet standard [server certificate
  requirements](https://docs.cloud.google.com/load-balancing/docs/backend-authenticated-tls-backend-mtls#certificate-requirements)
  (including a Subject Alternative Name (SAN) matching the target hostname).

- **Private CAs and self-signed certificates** : If your target destination
  (agents, tools, or MCP servers in your VPC network) uses a
  private CA or internal PKI, you can configure custom trust anchors using
  the `tlsConfig` setting in your connectivity template.

  By referencing a Certificate Manager `TrustConfig` resource, you
  can configure Agent Gateway to trust only specific private
  CAs, or combine private root CAs with publicly trusted CAs
  (`PUBLICLY_TRUSTED_ROOTS`). This establishes trust for both public and
  private endpoints.

  If your agents connect to Google Cloud APIs (`*.googleapis.com`) or
  other public HTTPS endpoints, you must set `additionalRoots`
  to`PUBLICLY_TRUSTED_ROOTS`; without this setting,
  Agent Gateway doesn't trust Google-signed certificates for
  `googleapis.com`.

  Note the following limitations when using `tlsConfig`:
  - When using `trustConfig`s to route traffic to destinations that use private CAs, you must rotate the PEM files manually. Automated rotation of PEM files using secret managers, such as [Google Cloud's
    Secret Manager](https://docs.cloud.google.com/secret-manager/docs/overview), is not supported.
  - The `trustConfig` field is immutable once configured on a connectivity template, and Agent Gateway doesn't automatically pick up changes made to `tlsConfig` (such as updating `additionalRoots`) on an attached connectivity template. For instructions on updating TLS settings, see [Updating VPC egress
    settings](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-vpc-connectivity#updating-egress-settings).

If Agent Gateway is unable to [validate the certificate
chain](https://docs.cloud.google.com/load-balancing/docs/backend-authenticated-tls-backend-mtls#validation-steps),
the connection fails.

## Required roles and permissions

To configure VPC connectivity for Agent Gateway,
ensure that the identity used for provisioning and the gateway service agent
have the required roles.

### Standalone project deployments

In a standalone project where the gateway, network attachment, and
VPC network reside in the same project, standard
Agent Gateway permissions apply. For details, see
[Required permissions](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-agent-gateway#required-roles).

### Shared VPC or cross-project deployments

In a [Shared VPC](https://docs.cloud.google.com/vpc/docs/shared-vpc) deployment, you can provision
the Agent Gateway in either a service project or the host
project. If you provision the gateway in the host project (where the
Shared VPC network, subnet, and network attachment also reside),
[standalone project permissions](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-vpc-connectivity#standalone-project-permissions) apply.

If you provision the Agent Gateway in a service project while the
target VPC network, network attachment, or private DNS zones
reside in the host project (`TARGET_VPC_PROJECT_ID`),
identities in the service project don't automatically have permissions to
validate, attach to, or peer with networking and DNS resources in the host
project. Grant the following roles on the host project in addition to
[standard Agent Gateway
permissions](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-agent-gateway#required-roles):

| Principal or identity | Grant on project | Required IAM role | Purpose |
|---|---|---|---|
| **Provisioning identity^1^** (User account or deployment service account) | Host project (<var translate="no">TARGET_VPC_PROJECT_ID</var>) | - Compute Network Viewer (`roles/compute.networkViewer`) - DNS Reader (`roles/dns.reader`) - Network Connectivity Regional Endpoint Admin (`roles/networkconnectivity.regionalEndpointAdmin`) - Network Connectivity Consumer Network Admin (`roles/networkconnectivity.consumerNetworkAdmin`) | Allows backend validation of the target VPC network, subnets, network attachment, and private DNS zones during gateway creation or updates. |
| **Network attachment creator** (Administrator creating the PSC attachment) | Host project (<var translate="no">TARGET_VPC_PROJECT_ID</var>) | - Compute Network User (`roles/compute.networkUser`) | Allows using a Shared VPC subnet in the host project to create a Private Service Connect network attachment. |
| **Network attachment in the service project (Recommended)** ||||
| **Agent Gateway Service Agent^2^** | Host project (<var translate="no">TARGET_VPC_PROJECT_ID</var>) | - Compute Network User (`roles/compute.networkUser`) - DNS peer (`roles/dns.peer`) | Allows the Agent Gateway service agent to use the host project subnet for the network attachment, connect the Private Service Connect interface to route egress traffic, and peer with private Cloud DNS zones in the host project. |
| **Network attachment in the host project** ||||
| **Agent Gateway Service Agent^2^** | Host project (<var translate="no">TARGET_VPC_PROJECT_ID</var>) | - Compute Network Admin (`roles/compute.networkAdmin`), or a custom role with: - `compute.networkAttachments.get` - `compute.networkAttachments.update` - `compute.regionOperations.get` - DNS peer (`roles/dns.peer`) | Allows the Agent Gateway service agent to update the host project network attachment to allow the connection from the Agent Gateway tenant project, to route egress traffic, and peer with private Cloud DNS zones in the host project. |
[**Table:** Permissions needed for Shared VPC and cross-project deployments]

^1^ For the provisioning identity, basic project-level roles such as
Viewer (`roles/viewer`) or Editor (`roles/editor`) on the
host project are also sufficient.

^2^ The Agent Gateway Service Agent is formatted as:
`service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com`, where
`AGENT_GATEWAY_PROJECT_NUMBER` is the project
number of the project where you provision the Agent Gateway. For
Shared VPC deployments, this project can be either a service project or
the host project.

If you connect multiple Agent Runtime service projects to an
Agent Gateway host project, you must also grant cross-project
access on the gateway project to each Agent Runtime service agent. For
large-scale deployments, see [Scale Agent Runtime service projects with a
Google group](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-vpc-connectivity#scale-runtime-service-projects).

## Configure VPC connectivity

> [!IMPORTANT]
> **Important:** If you have an existing Agent Gateway that was created without an Agent Gateway connectivity template, you must delete the gateway and recreate it with a new connectivity template.

To deploy an Agent Gateway with a connectivity template,
complete the steps in the following sections.

### Create a Private Service Connect network attachment

Create a Private Service Connect network attachment in your target
VPC network.

Ensure that your network attachment meets the following requirements:

- **Connection preference** : Configure the network attachment to [automatically accept connections](https://docs.cloud.google.com/vpc/docs/about-network-attachments#connection-policies) (`--connection-preference=ACCEPT_AUTOMATIC`).
- **Same VPC network requirement** : The network attachment subnet and the target network configured for DNS peering (`targetNetwork`) *must be in the exact same VPC network*. If the network attachment's subnet belongs to a different network than the DNS peering target network, configuration validation fails.
- **VPC network MTU support** : Agent Gateway supports a [maximum transmission unit (MTU)](https://docs.cloud.google.com/vpc/docs/mtu) of up to 1,500 bytes for the VPC network that contains the network attachment's subnet. If that VPC network uses a larger MTU, such as jumbo frames, then [contact Cloud Customer Care](https://docs.cloud.google.com/support/docs/customer-care-procedures) to align the Agent Gateway producer service with your custom VPC MTU.
- **Subnet requirements** : Note the following requirements for the network attachment subnet:
  - **Subnet range** : The network attachment subnet supports all [valid
    ranges](https://docs.cloud.google.com/vpc/docs/subnets#valid-ranges).
  - **Subnet size** : Agent Gateway requires a minimum `/28` subnet for the network attachment. A `/28` subnet provides 12 usable IP addresses, which is sufficient for a single Agent Gateway instance. If you plan to connect multiple gateways to the same network attachment or subnet, use a larger subnet (such as `/26` or `/24`) to avoid IP address exhaustion.
  - **Private Google Access requirement** : You must enable [Private Google Access](https://docs.cloud.google.com/vpc/docs/configure-private-google-access) (`private_ip_google_access = true`) on the subnet hosting the network attachment.
- **Shared VPC deployments** : For Shared VPC deployments, see [Shared VPC deployment topologies](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-vpc-connectivity#shared-vpc-topologies).

Note the complete resource URI of the network attachment (for example,
`projects/NETWORK_ATTACHMENT_PROJECT_NUMBER/regions/NETWORK_ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT_NAME`).
You'll need it when you create the connectivity template resource in a later
step.

### Optional: Set up DNS peering

DNS peering lets Agent Gateway resolve DNS names using records
from a Cloud DNS private managed zone in your VPC network.
DNS peering is required only when your agents need to resolve private internal
domain names (such as `corp.internal.`) or enforce VPC Service Controls for
Google APIs (`googleapis.com.`). It is not required for public internet domains
or standard Google APIs without VPC Service Controls.

Agent Gateway supports [transitive DNS
peering](https://docs.cloud.google.com/dns/docs/zones/zones-overview#dns_peering_limitations_and_key_points)
only up to a single transitive hop, which means a maximum of three
VPC networks. For example, `vpc-net-a` (the
Agent Gateway tenant network) can peer to `vpc-net-b` (attached
network), which in turn peers to `vpc-net-c` (remote network) to resolve DNS
queries across the chain.

To set up DNS peering, perform the following steps:

1. [Set up your private DNS zone](https://docs.cloud.google.com/dns/docs/zones/zones-overview) in your
   target VPC network. To add DNS records to your private DNS
   zone, see [Add a resource record set](https://docs.cloud.google.com/dns/docs/records#add-rrset).

2. Gather the following information to configure the connectivity template to
   enable peering:

   - **Target network URI (`targetNetwork`)** : Note the full resource URI of
     the target VPC network in the following format:
     `projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME`.
     The target network is always the VPC network that
     *contains the subnet referenced by the network attachment*. If the
     target network is a Shared VPC network, then make sure to use
     the corresponding Shared VPC host project ID.

   - **Domain names** : One or more domain suffixes for DNS peering. Each
     domain must end with a trailing dot (`.`) (for example,
     `corp.internal.` or `googleapis.com.`).

     For additional guidance on how to configure the `domains` field, see
     [DNS peering domain patterns](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-vpc-connectivity#dns-peering-domain-patterns). For
     cross-project deployments such as Shared VPC, see
     [Cross-project DNS zone and peering requirements](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-vpc-connectivity#dns-zone-type).

### Optional: Set up TLS trust configuration

If your target destination uses a private CA or self-signed certificate, you
need to create a `TrustConfig` resource in Certificate Manager.
The `TrustConfig` resource defines the trust anchors and certificates that
Agent Gateway uses to validate TLS connections.

1. Prepare your certificate files in PEM format:

   - **Trust store** : Root or intermediate CA certificates in PEM format. Agent Gateway trusts any server certificate whose chain of trust leads to one of these CA certificates. *The trust store must
     contain at least one root or intermediate CA certificate.*
   - **Allowlisted certificates (Optional)**: Server certificates in PEM format that you want to explicitly trust, such as a self-signed certificate.
2. Run the following command to create the `TrustConfig` resource. The
   `TrustConfig` must be created in the same project and region as the
   Agent Gateway and the connectivity template.

   ```
   gcloud certificate-manager trust-configs create TRUST_CONFIG_NAME \
       --location=LOCATION \
       --trust-store="trust-anchors=ROOT_CERT_FILE" \
       --allowlisted-certificates=ALLOWLISTED_CERT_FILE
   ```

   Replace the following:
   - `TRUST_CONFIG_NAME`: A name for the `TrustConfig` resource.
   - `LOCATION`: The region for the trust config (for example, `europe-west1`). This must be the same region as the Agent Gateway and the connectivity template.
   - `ROOT_CERT_FILE`: The path to your PEM-encoded root or intermediate CA certificate.
   - `ALLOWLISTED_CERT_FILE`: (Optional) The path to a PEM-encoded certificate that you want to explicitly trust. If you aren't using allowlisted certificates, omit this flag.

   For more information on managing trust configs, see [Create and manage trust
   configs](https://docs.cloud.google.com/certificate-manager/docs/trust-configs).

### Deploy the Agent Gateway

1. **Create the connectivity template configuration file**:

   Create a YAML file named `agw-connectivity-template.yaml`:

       name: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
       accessPath: AGENT_TO_ANYWHERE
       deploymentModel: CENTRALIZED
       egressNetworkConfig:
         networkAttachment: projects/NETWORK_ATTACHMENT_PROJECT_NUMBER/regions/NETWORK_ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT_NAME
         dnsPeeringConfig:
           domains:
             - DOMAIN_NAME
           targetNetwork: projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME
         vpcEgress: VPC_EGRESS_MODE
         tlsConfig:
           trustConfig: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/trustConfigs/TRUST_CONFIG_NAME
           additionalRoots: ADDITIONAL_ROOTS_OPTION

   Replace the following:
   - `AGENT_GATEWAY_PROJECT_NUMBER`: The project number
     of the Google Cloud project where you provision the
     Agent Gateway. To retrieve your project number, run:
     `gcloud projects describe PROJECT_ID --format="value(projectNumber)"`.

   - `LOCATION`: The region for the connectivity
     template (for example, `europe-west1`).

   - `CONNECTIVITY_TEMPLATE_NAME`: The name of the
     connectivity template resource.

   - `accessPath`: The [governed access
     path](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-agent-gateway#choose-mode) for the
     connectivity template. Set to `AGENT_TO_ANYWHERE` (connectivity
     templates are supported only for egress gateways).

   - `deploymentModel`: The deployment model for the gateway. Set to
     `CENTRALIZED`.

   - `networkAttachment`: The full resource URI of the
     Private Service Connect network attachment:

     - `NETWORK_ATTACHMENT_PROJECT_NUMBER`: The project number of the project where you created the network attachment. This project might be the same as the Agent Gateway project, or a different project if you provision the Agent Gateway in a Shared VPC service project and create the network attachment in the Shared VPC host project.
     - `NETWORK_ATTACHMENT_REGION`: The region that contains the network attachment.
     - `NETWORK_ATTACHMENT_NAME`: The network attachment name.

     > [!NOTE]
     > **Note:** The `networkAttachment` field is immutable once configured on both the connectivity template and the Agent Gateway. You can't change the network attachment of an existing gateway by switching to a different connectivity template.

   - `DOMAIN_NAME`: (Optional) One or more domain
     suffixes for DNS peering (for example, `corp.internal.`,
     `googleapis.com.`, or `.`). Add a list item under `domains` for each
     domain suffix that you want to peer. Each value must end with a trailing
     dot (`.`) and have a corresponding private Cloud DNS managed zone
     authorized for the target network.

     For additional guidance on how to configure the `domains` field, see
     [DNS peering domain patterns](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-vpc-connectivity#dns-peering-domain-patterns).
   - `targetNetwork`: (Optional) The full resource URI of the target
     VPC network for DNS peering. The target network is always
     the VPC network that contains the subnet referenced by
     the network attachment:

     - `TARGET_VPC_PROJECT_ID`: The project ID of the project that owns the target VPC network. If the network that contains the subnet referenced by the network attachment is a Shared VPC network, then `TARGET_VPC_PROJECT_ID` is the Shared VPC host project ID. Always specify `targetNetwork` using the project ID rather than the project number.
     - `TARGET_VPC_NETWORK_NAME`: The name of the target VPC network.
   - `VPC_EGRESS_MODE`: Set the [egress routing
     mode](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-vpc-connectivity#how-it-works). Set to either `PRIVATE_RANGES_ONLY` or
     `ALL_TRAFFIC`.

   - `tlsConfig`: (Optional) The TLS configuration for server
     certificate validation when connecting to private endpoints over
     HTTPS:

     - `TRUST_CONFIG_NAME`: The name of the Certificate Manager `TrustConfig` resource containing your private CA certificates or trust anchors.
     - `ADDITIONAL_ROOTS_OPTION`: Specifies whether to trust publicly trusted CA roots in addition to your custom trust config:
     - Set to `PUBLICLY_TRUSTED_ROOTS` (default) to trust both certificates validated by the `trustConfig` parameter and all publicly trusted CAs. You must set `additionalRoots` to `PUBLICLY_TRUSTED_ROOTS` if your agents also connect to Google Cloud APIs (`*.googleapis.com`) or other public HTTPS endpoints; without this setting, Agent Gateway won't trust Google-signed certificates for `googleapis.com`.
     - Set to `NO_ADDITIONAL_ROOTS` to trust only the certificates validated by the `trustConfig` parameter.

     > [!NOTE]
     > **Note:** The `trustConfig` field is immutable once configured on a connectivity template, and Agent Gateway doesn't automatically pick up in-place changes to `tlsConfig` (such as updating `additionalRoots`) while the connectivity template is attached to a gateway. To update TLS settings, see [Updating
     > VPC egress settings](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-vpc-connectivity#updating-egress-settings).

2. **Create the connectivity template**:

   Run the following command to create the connectivity template:

   ```
   gcloud network-services agent-connectivity-templates import CONNECTIVITY_TEMPLATE_NAME \
       --source="agw-connectivity-template.yaml" \
       --location=LOCATION
   ```

   Replace the following:
   - `CONNECTIVITY_TEMPLATE_NAME`: The name of the connectivity template resource.
   - `LOCATION`: The location where you want to create the connectivity template resource. For example, `europe-west1`.
3. **Define the Agent Gateway resource**:

   Define a new Agent Gateway resource in `AGENT_TO_ANYWHERE`
   mode by creating a gateway YAML configuration file (for example,
   `my-agent-gateway-vpc-egress.yaml`) that references the connectivity
   template:

       name: AGENT_GATEWAY_NAME
       protocols:
         - MCP
       googleManaged:
         governedAccessPath: AGENT_TO_ANYWHERE
       agentConnectivityTemplate: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
       registries:
         - AGENT_REGISTRY_PATH

   Replace the following:
   - `AGENT_GATEWAY_NAME`: The name of the
     Agent Gateway resource.

   - `AGENT_GATEWAY_PROJECT_NUMBER`: The project number
     of the Google Cloud project where you provision the
     Agent Gateway and connectivity template. For
     Shared VPC deployments, this project can be either a service
     project or the host project. To retrieve your project number, run:
     `gcloud projects describe PROJECT_ID --format="value(projectNumber)"`.

   - `LOCATION`: The location of the connectivity
     template (for example, `europe-west1`).

   - `CONNECTIVITY_TEMPLATE_NAME`: The name of the
     connectivity template resource.

     - `AGENT_REGISTRY_PATH`: The path to the regional Agent Registry instance in the same project and region as the gateway, formatted as `//agentregistry.googleapis.com/projects/PROJECT_ID/locations/LOCATION`. For guidance, see [Plan your Agent Gateway
       deployment](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-agent-gateway#plan-agw).
4. **Import and deploy Agent Gateway**:

   Run the following command to create the Agent Gateway
   resource based on the YAML specification:

   ```
   gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
       --source="my-agent-gateway-vpc-egress.yaml" \
       --location=LOCATION
   ```

   Replace `LOCATION` with the location where you want
   to create the Agent Gateway resource. For example,
   `europe-west1`.

## Architecture and networking considerations

This section provides architectural guidance and advanced networking patterns
for deploying Agent Gateway with VPC connectivity.

### Updating VPC egress settings

A connectivity template can't be modified in place while it is referenced by an
Agent Gateway, and Agent Gateway doesn't
automatically pick up changes made to an attached connectivity template:

- **Updating DNS peering, VPC egress mode, or TLS settings
  (`tlsConfig`)** : On a connectivity template, the `tlsConfig.trustConfig`
  field is immutable once configured, and in-place updates to `tlsConfig`
  (such as adding or changing `additionalRoots`) aren't picked up by an
  attached Agent Gateway. To update the DNS peering
  configuration, VPC egress mode, or `tlsConfig` settings on an
  existing gateway, create a new connectivity template that uses the *same*
  `networkAttachment` with the updated settings, and update the
  Agent Gateway to reference the new template (or unbind and
  rebind the connectivity template).

- **Changing the network attachment** : The `networkAttachment` itself is
  immutable once configured on both the connectivity template and the
  Agent Gateway. To switch to a different network attachment
  (or target VPC network), you must create a new connectivity
  template and a new Agent Gateway.

### Shared VPC deployment topologies

In a [Shared VPC](https://docs.cloud.google.com/vpc/docs/shared-vpc) architecture, you can provision
the Agent Gateway in either a service project or the host
project. When you provision the Agent Gateway in a service
project, you can create the network attachment in either the service project
(recommended) or the host project:

- **Recommended: Network attachment in service project** :
  1. [Create the subnet](https://docs.cloud.google.com/vpc/docs/create-modify-vpc-networks#add-subnets) in the host project.
  2. [Create the network attachment](https://docs.cloud.google.com/vpc/docs/create-manage-network-attachments#create-network-attachments) in the service project, referencing the host project's subnet.
- **Network attachment in host project** :
  1. [Create the subnet](https://docs.cloud.google.com/vpc/docs/create-modify-vpc-networks#add-subnets) in the host project.
  2. [Create the network attachment](https://docs.cloud.google.com/vpc/docs/create-manage-network-attachments#create-network-attachments) in the host project.

### VPC Service Controls compliance

To enforce VPC Service Controls perimeters for agent communications, ensure the
following:

- Set `vpcEgress` to `ALL_TRAFFIC` in your connectivity template.

- Direct Google API requests to either the `restricted.googleapis.com` IP range
  (`199.36.153.4/30`) or to an internal Private Service Connect
  endpoint for Google APIs.

- Configure DNS resolution for `googleapis.com`. Create a private
  Cloud DNS zone in your VPC network mapping
  `*.googleapis.com` to `restricted.googleapis.com`, and include
  `googleapis.com.` in the `domains` field of your connectivity template.

  For more details about DNS configuration, see [Configure DNS for
  googleapis.com](https://docs.cloud.google.com/vpc/docs/configure-private-google-access#dns-config-google-apis)
  in the Private Google Access documentation.
- For Shared VPC deployments, the host project that owns the
  network attachment's subnet and the `dnsPeeringConfig.targetNetwork` must
  be in the same service perimeter as the project where you deploy the
  Agent Gateway. This applies even when you create the
  network attachment in the service project, because the subnet and
  VPC network still belong to the host project. If your
  private DNS zones are hosted in a separate DNS project, include that
  project in the perimeter too.

### DNS peering domain patterns

This section describes domain resolution patterns and options for configuring
the `domains` field in a connectivity template.

**Domain name configuration** : Configure the `domains` field in the connectivity
template based on the following considerations:

- **Private internal domains** : To resolve private internal services hosted in
  your VPC network (for example, `service.corp.internal`),
  specify your internal domain suffix (such as `corp.internal.`). An
  exact-match private Cloud DNS managed zone for this domain must be
  authorized for the target VPC network.

- **Split-horizon DNS (Public domain with RFC 1918 IP)** : If you use a public
  DNS zone to host records pointing to internal private IPs (such as
  `mcp.example.com` resolving to an RFC 1918 address for
  Certificate Manager public certificates), the gateway
  resolves these records automatically using public recursive DNS without
  requiring DNS peering.

- **Google Cloud APIs with VPC Service Controls** : When `ALL_TRAFFIC` is
  configured to enforce VPC Service Controls, Google API requests must resolve
  to the `restricted.googleapis.com` IP range (`199.36.153.4/30`) or to
  internal PSC endpoints. Create a private Cloud DNS zone in your
  VPC network mapping `*.googleapis.com` to
  `restricted.googleapis.com`, and include `googleapis.com.` in the `domains`
  field of your connectivity template.

- **Multi-domain resolution patterns**: If your deployment requires resolving
  multiple private domain suffixes, choose one of the following patterns:

  - **Peer multiple individual domains** : Specify a list of domain suffixes in the `domains` field of `dnsPeeringConfig` (for example, `corp.internal.`, `prod.internal.`, and `googleapis.com.`). Each domain in the list must end with a trailing dot (`.`) and have a corresponding private Cloud DNS managed zone authorized for the target VPC network.
  - **Consolidated parent suffix (Recommended)** : Consolidate internal services under a shared parent domain suffix (such as `*.internal.` or `*.corp.internal.`) and include that parent domain in the `domains` list.
  - **Catch-all root peering with a Private Forwarding Zone** : Include `"."`
    in the `domains` field of the connectivity template, and configure a
    Cloud DNS **Private Forwarding Zone** for the root domain
    (`.`) in your VPC network pointing to an upstream
    recursive resolver (such as `8.8.8.8` or an internal enterprise
    resolver). More specific private zones in your
    VPC match first by longest suffix match, while
    unmatched public queries resolve through the upstream forwarder.

    > [!CAUTION]
    > **Caution:** Avoid configuring an *authoritative* private zone for the root domain (`.`). An authoritative root zone only resolves records defined within it and returns `NXDOMAIN` for all other domains, which can prevent external SaaS endpoints and Google Cloud APIs from resolving.

### Cross-project DNS zone and peering requirements

The connectivity template's `dnsPeeringConfig` setting doesn't support direct
cross-project Cloud DNS peering. When you import the connectivity template,
validation fails if the subnet referenced by the `networkAttachment` belongs to
a different VPC network than `targetNetwork`, or if you rely on
cross-project DNS zone binding from a service or external project.

The managed zone for the domain must be created in the *host project* that owns
`targetNetwork`. The managed zone can be any of the following zone types:

- **Authoritative private zone**
- **Forwarding zone**
- **Cloud DNS peering zone** : Must be associated with the host project VPC network and target a destination VPC network. The destination VPC must resolve the query directly using an authoritative private zone. Forwarding the query to another DNS peering zone (chaining) is unsupported and results in an `NXDOMAIN` error.

### Scale Agent Runtime service projects with a Google group

If you connect multiple Agent Runtime service projects to an
Agent Gateway host project and grant cross-project access to each
service agent individually, you must update the host project's
IAM policy every time you add a project. In large-scale
deployments, you might also reach
[IAM policy limits](https://docs.cloud.google.com/iam/quotas#limits) as you add role bindings.

To avoid updating the host project's IAM policy for every
new service project, you can instead manage access through a single Google
security group:

1. **Create a security group** : [Create a security
   group](https://docs.cloud.google.com/identity/docs/how-to/update-group-to-security-group) either [in the
   Google Admin
   console](https://knowledge.workspace.google.com/admin/groups/control-access-to-sensitive-data-with-security-groups)
   or by running the [`gcloud identity groups
   create`](https://docs.cloud.google.com/sdk/gcloud/reference/identity/groups/create) command.

   > [!NOTE]
   > **Note:** To add [service
   > agents](https://docs.cloud.google.com/iam/docs/service-account-types#service-agents) to a Google group, you must turn on the [external
   > members](https://support.google.com/a/answer/167097#zippy=%2Ccan-external-users-participate-in-groups) option for the group.

2. **Grant the group access to the
   Agent Gateway host project** : Bind the group to the Network
   Services Viewer role (`roles/networkservices.viewer`) on
   `AGENT_GATEWAY_PROJECT_ID`:

   ```
   gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
       --member="group:GROUP_EMAIL" \
       --role="roles/networkservices.viewer"
   ```

   Replace the following:
   - `AGENT_GATEWAY_PROJECT_ID`: The project ID of the Agent Gateway host project.
   - `GROUP_EMAIL`: The email address of your security group (for example, `agw-cross-project-runtime@example.com`).
3. **Add each service project's Agent Runtime service agent to the group** :
   For each Agent Runtime service project, add its service agent to
   the security group by running the [`gcloud identity groups memberships
   add`](https://docs.cloud.google.com/sdk/gcloud/reference/identity/groups/memberships/add) command
   as follows:

   ```
   gcloud identity groups memberships add \
       --group-email="GROUP_EMAIL" \
       --member-email="service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com"
   ```

   Replace `AGENT_RUNTIME_PROJECT_NUMBER` with the
   project number of the Agent Runtime service project.

## What's next

Guide

### [Route Agent Runtime traffic through Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-gateway-runtime-deploy)


Learn how to route Agent Runtime traffic through Agent Gateway for secure and governed connectivity.

Codelab

### [Codelab: Govern agentic workloads with Agent Platform](https://codelabs.developers.google.com/cloudnet-agent-gateway)


Learn how to govern agentic workloads with Agent Gateway on Gemini Enterprise Agent Platform.

Codelab

### [Codelab: Agent Gateway egress from Agent Runtime to VPC networks](https://codelabs.developers.google.com/agw-cuj-arun-egress-vpc)


Learn about Agent Gateway egress governance for AI agents accessing destinations in a VPC network.

Guide

### [Delegate authorization for Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/delegate-authorization)


Learn how to delegate authorization for Agent Gateway to IAP, Model Armor, or your own custom authorization service.

Guide

### [Manage Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/manage-agent-gateways)


Learn how to view, update, disassociate, and delete Agent Gateway resources.

Guide

### [Monitor Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/monitor-agent-gateway)


Learn how to monitor Agent Gateway.

Guide

### [Route Gemini Enterprise traffic through Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-ge-deploy)


Learn how to route Gemini Enterprise traffic through Agent Gateway.