Quotas and system limits

Customer Experience Agent Studio uses quotas and system limits to maintain fair resource allocation, prevent service overloads, and help you manage resource use.

Quotas and system limits are similar but differ in the following ways:

  • Quotas have default values, but you can typically request adjustments.
  • System limits are fixed values that can't be changed.

Google Cloud uses quotas to help maintain fairness and reduce spikes in resource use and availability. A quota restricts how much of a Google Cloud resource your Google Cloud project can use. Quotas apply to a range of resource types, including hardware, software, and network components. For example, quotas can restrict the number of API calls to a service, the number of load balancers used concurrently by your project, or the number of projects that you can create. Quotas protect the community of Google Cloud users by preventing the overloading of services. Quotas also help you to manage your own Google Cloud resources.

The Cloud Quotas system does the following:

In most cases, when you attempt to consume more of a resource than its quota allows, the system blocks access to the resource, and the task that you're trying to perform fails.

Quotas generally apply at the Google Cloud project level. Your use of a resource in one project doesn't affect your available quota in another project. Within a Google Cloud project, quotas are shared across all applications and IP addresses.

For more information, see the Cloud Quotas overview.

Important things to know

  • Multi-region quota mapping: Multi-region and global deployments enforce quotas in a mapped single region. Always select the mapped single region when viewing usage or requesting an adjustment.
  • Project and base_model pooling: Quotas apply per Google Cloud project and mapped region. Runtime model quotas are also tracked per base_model—any agents, guardrails, or tools in the same project and region that share a model pool into one base_model row.
  • Token quotas govern capacity, not billing: RunSession LLM token quotas are throughput guardrails only—CX Agent Studio session pricing includes underlying agent and guardrail token usage, and raising your ces.googleapis.com token quota doesn't add per-token charges. For billing details, see CX Agent Studio pricing.
  • Lead times and alerting: Small quota adjustments often approve automatically, while large production increases require capacity review and should be requested well ahead of load testing or launch. Configure quota usage alerts (for example, at 80% utilization) to catch traffic growth early.

Key terms

  • App (agent application): The top-level container created when you click Create agent in the CX Agent Studio console (Create an agent application; projects/*/locations/*/apps/* in the API). One app holds your root agent, sub-agents, tools, guardrails, evaluations, and versions.
  • RunSession and StreamRunSession: Runtime API methods that process turn-by-turn requests, typically used for text and web chat.
  • BidiRunSession: Runtime API method that opens a persistent two-way stream, typically used for live voice calls and real-time audio.
  • base_model: The quota dimension identifying the specific foundation or composite model ID serving an agent, guardrail, or built-in generative tool.

Multi-region quota mapping

When you deploy an app in a multi-region or call the global endpoint, CX Agent Studio tracks quotas in the following single regions:

Application location Mapped quota region
us (US multi-region) us-central1
eu (EU multi-region) europe-west4
global endpoint us-central1

Runtime session quotas

The following adjustable quotas govern live customer conversations across chat and voice.

Quota Default Type and scope Metric and behavior
RunSession LLM tokens per minute 120,000 Rate quota (per project, region, base_model; resets every minute)

ces.googleapis.com/run_session_llm_token_consumption

Applies to both chat (RunSession, StreamRunSession) and voice (BidiRunSession). Chat sessions have no separate session-rate or concurrency quota. When exceeded, new turns fail with 429 RESOURCE_EXHAUSTED. See How tokens and base_model quotas are counted.

Concurrent BidiRunSession operations per 30 minutes 15 Concurrent quota (per project, region, base_model)

ces.googleapis.com/concurrent_bidi_run_session_operations

Maximum simultaneous active voice or bidirectional streaming sessions. Each open stream holds one slot and releases it on disconnect (30 minutes is the maximum slot lease window). When exceeded, new streams fail with 429 RESOURCE_EXHAUSTED.

How tokens and base_model quotas are counted

A single conversation turn can trigger multiple LLM calls when an agent invokes tools or transfers to a sub-agent, and one app can consume quota across multiple base_model rows at the same time.

Counted toward RunSession LLM tokens per minute (pooled by base_model):

  • Root agent, sub-agents, and agent tools: Input and output tokens across every LLM call in a turn, billed to each agent's configured model. Composite voice models bill only the composite base_model ID rather than underlying speech or sub-models.
  • LLM-based guardrails: Prompt guard, natural-language Rules, and the Generate a response trigger action, billed to a separate default lightweight Gemini base_model (unless pinned through API modelSettings.model on a guardrail policy).
  • Built-in generative tools: Data store query rewriting or summarization and Google Search grounding, billed to their underlying base_model.

Not counted toward RunSession LLM tokens per minute:

  • Deterministic and supervisor guardrails: Blocklist, code Rules, default Safety classifiers, and Supervisor agents (Preview), unless configured to trigger Generate a response.
  • Built-in evaluations (RunEvaluation, Preview): Enforces only Concurrent RunEvaluation operations (custom test scripts that call RunSession or BidiRunSession directly do count as live sessions).
  • Built-in speech and code execution: Built-in Speech-to-Text, Text-to-Speech, and Python tool or callback execution.

Identify and size base_model rows

Default auxiliary models evolve over time, and some console model names map to versioned base_model IDs. Confirm your active rows in a non-production project before launch:

  1. Run representative test sessions with your agents, guardrails, and tools enabled.
  2. After a few minutes, open IAM & Admin > Quotas & System Limits filtered by Metric:ces.googleapis.com/run_session_llm_token_consumption (or check serviceruntime.googleapis.com/quota/rate/net_usage on ces.googleapis.com/Location in Cloud Monitoring) to see each active base_model row and its observed TPM per session.
  3. Request adjustments for those same base_model IDs (even on 0-usage rows) in your production project's mapped region.

For example, a voice app in us using AGENT_MODEL and LLM-based guardrails on GUARDRAIL_MODEL adjusts three rows in us-central1:

Quota Target dimensions How to size
Concurrent BidiRunSession operations region=us-central1, base_model=AGENT_MODEL Peak simultaneous voice calls plus headroom
RunSession LLM tokens per minute region=us-central1, base_model=AGENT_MODEL Peak sessions multiplied by observed AGENT_MODEL TPM per test session, plus headroom
RunSession LLM tokens per minute region=us-central1, base_model=GUARDRAIL_MODEL Peak sessions multiplied by observed GUARDRAIL_MODEL TPM per test session, plus headroom

Management, authoring, and evaluation quotas

The following adjustable quotas govern app administration, CI/CD, Studio AI authoring helpers, standalone tool testing, and evaluations. None of these quotas restrict live customer session traffic.

Quota Default Type and scope Metric and notes
Apps per project per region 1,000 Allocation (per project, region) ces.googleapis.com/apps — Top-level agent applications (App containers); restored when an app is deleted.
API requests per minute 10,800 Rate (per project) api-requests — Covers management, tool, and evaluation RPCs; excludes runtime sessions.
App mutation operations per minute 200 Rate (per project, region) ces.googleapis.com/app_mutation_operations — Write actions that create, edit, delete, deploy, import (ImportApp), or sync an app or its agents, tools, guardrails, or evaluations. Bulk imports and Git sync count as 1 operation per call.
App read operations per minute 600 Rate (per project, region) ces.googleapis.com/app_read_operations — Read actions that view, list, or export (ExportApp) an app or its agents, tools, guardrails, or evaluations. Bulk exports count as 1 operation per call.
App generative operations per minute (Preview) 100 Rate (per project, region) ces.googleapis.com/app_generative_operations — AI-assisted authoring actions in the console or API, such as generating instructions, mock tools, test scenarios, or quality fixes.
ExecuteTool requests per minute 240 Rate (per project, region) ces.googleapis.com/execute_tool_requests — Standalone ToolService calls only (for example, clicking Test tool in the console; excludes tools called inside sessions).
RetrieveTools requests per minute 120 Rate (per project, region) ces.googleapis.com/retrieve_tools_requests — Standalone ToolService calls only.
RetrieveToolSchema requests per minute 120 Rate (per project, region) ces.googleapis.com/retrieve_tool_schema_requests — Standalone ToolService calls only.
Concurrent RunEvaluation operations per 10 minutes (Preview) 20 Concurrent (per project, region) ces.googleapis.com/concurrent_run_evaluation_operations — Simultaneous active evaluation runs (freed on completion).

System limits

CX Agent Studio enforces the following fixed system limits (not adjustable):

System limit Value
Maximum agents per app (root agent plus sub-agents) 100
Maximum tools per app 200
Maximum tools per agent 100
Maximum toolsets per app (multi-operation OpenAPI, MCP, or connector integrations) 100
Maximum guardrails per app 100
Maximum few-shot examples per app 1,000
Maximum variables per app 100
Maximum evaluations per app (Preview) 1,000
Maximum evaluation datasets per app (Preview) 100
Maximum turns per evaluation (Preview) 100
Maximum callbacks per agent 50
Maximum immutable app versions per app 200
Maximum serialized App resource size 10 MiB
Maximum LLM calls (tool or transfer steps) per turn 10
Unary RunSession RPC deadline (default synchronous tool timeout: 30s) 60 seconds
Maximum BidiRunSession stream duration 60 minutes
BidiRunSession client message idle timeout 30 seconds

Agent model inference, built-in Speech-to-Text, built-in Text-to-Speech, RunEvaluation judges, and Python execution don't consume quotas in other APIs in your Google Cloud project. When your agent integrates with the following services, check their quotas separately:

Integrated service When quotas apply in your project
Omnichannel Gateway and Dialogflow Native channel and telephony routing (Omnichannel Gateway), or routing through Dialogflow telephony integrations
Agent Search Querying or summarizing data store tools
Vertex AI and Vertex AI RAG Engine Using built-in Google Search tools (aiplatform.googleapis.com) or connecting an existing corpus to File Search tools
Integration Connectors and Cloud Run Invoking connector tools or Cloud Run webhook tools
Model Armor and Sensitive Data Protection Scanning CX Agent Studio MCP server requests or applying redaction templates

Request a quota adjustment

To adjust most quotas, use the Google Cloud console. For more information, see Request a quota adjustment.

In the Google Cloud console, filter by Service:Gemini Enterprise for Customer Experience API, your mapped single region, and the target runtime Metric: (ces.googleapis.com/run_session_llm_token_consumption or ces.googleapis.com/concurrent_bidi_run_session_operations). Include your peak concurrency and observed TPM per session in the request description.

For CLI commands, alerts, and error diagnosis, see Manage quotas using the gcloud CLI, Set up quota alerts and monitoring, and Troubleshoot quota errors.