Route Agent Runtime traffic through Agent Gateway

Private Preview — Agent Gateway

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. This feature provides capabilities to govern and secure AI Agents, so the "Agentic AI Services" Service Specific Terms apply. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To request access to use Agent Gateway with Agent Runtime, see the access request page.

This page describes how to route Agent Runtime traffic through Agent Gateway. Agent Gateway is a central networking and security component of the Gemini Enterprise Agent Platform ecosystem. It provides secure and governed connectivity for all agentic interactions, whether they occur between users and agents, agents and tools, or among agents themselves.

Before you begin

• Make sure you are familiar with deploying agents on Agent Runtime.

• Learn about Agent Gateway. You can use Agent Gateway in Agent-to-Anywhere (egress) mode to secure and govern all outbound communications with outbound traffic to tools, models, APIs, and other agents. You use the gateway in Client-to-Agent (ingress) mode to control which clients can access your agents. The gateway lets you choose which IAP policies and Model Armor templates must be applied to these interactions.

• Create a dedicated test project to try this workflow. Avoid using projects that are also intended for other critical workloads.

Limitations

• For a given project and region, there can only be one Agent-to-Anywhere (egress) instance and one Client-to-Agent (ingress) instance of Agent Gateway. All Agent Runtime agents within that same project and region that are configured to use Agent Gateway must use these specific gateway instances.
• The Security Command Center Agent Engine Threat Detection service isn't available when Agent Gateway is enabled for an agent.
• You can't unbind a Runtime agent from an Agent Gateway resource. For this reason, ensure that you use a dedicated test project.

Permissions required

You must grant the Reasoning Engine Service Agent the permission to use the Agent Gateway resource that you'll create.

1. If it doesn't already exist, create the service account. The Reasoning Engine service account is typically created automatically when you first use Reasoning Engine.

   gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT_ID
   

   Replace PROJECT_ID with your project ID.

2. To use the gateway, you require the following permissions:

   • roles/networkservices.agentGateways.get
   • roles/networkservices.agentGateways.use
   • roles/networkservices.operations.get

   Create a custom role with all of these permissions and then grant the role to the Reasoning Engine service account.

   gcloud alpha iam roles create AGENT_GATEWAY_ROLE_NAME \
     --project=AGENT_PROJECT_ID \
     --title="Custom Agent Gateway access role" \
     --description="Custom role for Agent Gateway" \
     --permissions="networkservices.operations.get,networkservices.agentGateways.get,networkservices.agentGateways.use"
   

   Replace the following:

   • AGENT_GATEWAY_ROLE_NAME: The name for the custom role.
   • AGENT_PROJECT_ID: The project ID of the project where you intend to deploy the agent.

3. Assign the role to the Agent Runtime service account.

   gcloud alpha projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:[e-mail]" \
       --role="projects/PROJECT_ID/roles/AGENT_GATEWAY_ROLE_NAME"
   

   Replace the following:

   • PROJECT_ID: Your project ID.
   • PROJECT_NUMBER: Your project number.
   • AGENT_GATEWAY_ROLE_NAME: The name of the custom role you created.

4. Additionally, if you intend to use Model Armor templates for authorization, and these templates are in a different project than the agent (and the gateway), then you must grant the following permissions to both the Reasoning Engine Service Agent and the Agent Gateway service account:

   gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/modelarmor.calloutUser
   gcloud alpha projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/modelarmor.user
    gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/modelarmor.calloutUser
    gcloud alpha projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/modelarmor.user
    

   Replace the following:

   • AGENT_PROJECT_ID: The project ID of the project where you intend to deploy the agent.
   • AGENT_PROJECT_NUMBER: The project number of the project where you intend to deploy the agent.
   • MODEL_ARMOR_PROJECT_ID: The project ID of the project where the Model Armor are created.

Route Agent Runtime traffic through Agent Gateway

To route Agent Runtime traffic through Agent Gateway, perform the following steps:

1. Create an Agent Gateway resource and attach any authorization policies as needed. You can create a gateway either in Agent-to-Anywhere (egress) mode or Client-to-Agent (ingress) mode. Note that the agent and the gateway must be created in the same project and region. For instructions, see Set up Agent Gateway.

   Ensure that the gateway is configured to meet your deployment's needs. For example, if your agent requires LLM access, configure the gateway to allow this access to prevent potential Agent Runtime deployment failures.

2. Specify the gateway resource while deploying your agent. For example, to deploy the agent on Agent Runtime, use client.agent_engines.create to pass in the local_agent object along with any optional configurations.

   remote_agent = client.agent_engines.create(
     agent=local_agent,
     config={
         "agent_gateway_config": {
           "agent_to_anywhere_config": {"agent_gateway": AGENT_GATEWAY_TO_ANYWHERE_RESOURCE_ID},
           # "client_to_agent_config": {"agent_gateway": AGENT_GATEWAY_CLIENT_TO_AGENT_RESOURCE_ID}
         },
         "identity_type": types.IdentityType.AGENT_IDENTITY,
         # Other optional configuration ...
         # "requirements": requirements,
         # "gcs_dir_name": gcs_dir_name,
     },
   )

   Replace AGENT_GATEWAY_TO_ANYWHERE_RESOURCE_ID with the full path of the Agent Gateway you created in Agent-to-Anywhere (egress) mode. For example, projects/PROJECT_NAME/locations/REGION/agentGateways/AGENT_GATEWAY_NAME.

   If you created a gateway in Client-to-Agent (ingress) mode, use the client_to_agent_config field instead and replace AGENT_GATEWAY_CLIENT_TO_AGENT_RESOURCE_ID with the full path of the Agent Gateway you created for ingress.

3. Register your agent with the Agent Registry instance in the same project and region as the agent and the gateway. For more information, see Register an agent.

Restrict Agent Runtime to approved Agent Gateways

You can create custom organization policy constraints to define the set of eligible Agent Gateway resources that can be used while deploying agents.

Note: VPC Service Controls are not supported with Agent Gateway. However, if VPC Service Controls are enforced on the project, then these organization policies are required to ensure that agents only use sanctioned egress paths, preventing data exfiltration through unauthorized gateways.

Create custom organization policy constraints

This example creates custom constraints that only allow traffic to and from a pre-approved list of gateways.

Agent-to-Anywhere

1. To define a custom constraint for Agent-to-Anywhere mode (egress), create a file named constraint-agent-gateway-egress.yaml.

   In the following example, the condition field specifies that the operation is allowed only if an Agent Gateway resource is specified (field is present and not empty) and if the specified gateway is in the pre-approved list.

   name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine
   resource_types:
   - aiplatform.googleapis.com/ReasoningEngine
   condition: >-
   has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) &&
   resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' &&
   (resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [
     'projects/PROJECT_ID_1/locations/REGION/agentGateways/AGENT_GATEWAY_NAME_1',
     'projects/PROJECT_ID_2/locations/REGION/agentGateways/AGENT_GATEWAY_NAME_2',
   ])
   method_types:
   - CREATE
   - UPDATE
   action_type: ALLOW
   display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways
   description: Reasoning Engines can only be bound to a pre-approved list of
   Agent Gateway instances. Binding to any other gateway is denied.
   

   Replace the following:

   • ORGANIZATION_ID: your organization ID.
   • PROJECT_ID: your project ID.
   • REGION: the region where the gateway was created.
   • AGENT_GATEWAY_NAME: your gateway name.

2. Apply the custom constraint.

   gcloud alpha org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH
   

   Replace EGRESS_CONSTRAINT_PATH with the full path to the custom constraint file created in the previous step.

3. Create the organization policy to enforce the constraint. To define the organization policy, create a policy YAML file named policy-agent-gateway-egress.yaml. In this example we enforce this constraint at the project level but you might also set this at the organization or folder level.

   name: projects/PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
   spec:
     rules:
     - enforce: true
   

   Replace PROJECT_ID with your project ID.

4. Enforce the organization policy.

   gcloud alpha org-policies set-policy EGRESS_POLICY_PATH
   

   Replace EGRESS_POLICY_PATH with the full path to the organization policy YAML file created in the previous step. The policy requires up to 15 minutes to take effect.

Client-to-Agent

1. To define a custom constraint for Client-to-Agent mode (ingress), create a file named constraint-agent-gateway-ingress.yaml.

   In the following example, the condition field specifies that the operation is allowed only if an Agent Gateway resource is specified (field is present and not empty) and if the specified gateway is in the pre-approved list.

   name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine
   resource_types:
   - aiplatform.googleapis.com/ReasoningEngine
   condition: >-
   has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) &&
   resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' &&
   (resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [
     'projects/PROJECT_ID_1/locations/REGION/agentGateways/AGENT_GATEWAY_NAME_1',
     'projects/PROJECT_ID_2/locations/REGION/agentGateways/AGENT_GATEWAY_NAME_2',
   ])
   method_types:
   - CREATE
   - UPDATE
   action_type: ALLOW
   display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways
   description: Reasoning Engines can only be bound to a pre-approved list of
   Agent Gateway instances. Binding to any other gateway is denied.
   

   Replace the following:

   • ORGANIZATION_ID: your organization ID.
   • PROJECT_ID: your project ID.
   • REGION: the region where the gateway was created.
   • AGENT_GATEWAY_NAME: your gateway name.

2. Apply the custom constraint.

   gcloud alpha org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH
   

   Replace INGRESS_CONSTRAINT_PATH with the full path to the custom constraint file created in the previous step.

3. Create the organization policy to enforce the constraint. To define the organization policy, create a policy YAML file named policy-agent-gateway-ingress.yaml. In this example we enforce this constraint at the project level but you might also set this at the organization or folder level.

   name: projects/PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
   spec:
     rules:
     - enforce: true
   

   Replace PROJECT_ID with your project ID.

4. Enforce the organization policy.

   gcloud alpha org-policies set-policy INGRESS_POLICY_PATH
   

   Replace INGRESS_POLICY_PATH with the full path to the organization policy YAML file created in the previous step. The policy requires up to 15 minutes to take effect.

For more information about how to use custom organization policy constraints, see Create custom constraints.

What's next

• Monitor traffic through Agent Gateway