Registry /
gcp / google-cloud-dialogflow-cx
Install & Compatibility
Where this runs
tested against v2.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 3.016s · 97.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.5s · import 1.716s · 95MB
98MB installed
● package 98MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AgentsClient
✓ from google.cloud.dialogflowcx_v3 import AgentsClient
✗ from google.cloud.dialogflowcx_v3beta1 import AgentsClient
Use the stable v3 client unless explicitly needing beta features. The beta client (v3beta1) is subject to backward-incompatible changes without notice.
SessionsClient
✓ from google.cloud.dialogflowcx_v3.services.sessions import SessionsClient
types
✓ from google.cloud.dialogflowcx_v3 import types
✗ from google.cloud.dialogflowcx_v3.types import Session
Common types are directly available under the `v3` or `v3beta1` module, e.g., `types.QueryInput`. Directly importing from `google.cloud.dialogflowcx_v3.types.Session` will raise an `ImportError`.
This quickstart demonstrates how to set up a `SessionsClient` and use it to detect intent from a text input against a specified Dialogflow CX agent. Ensure the Dialogflow CX API is enabled for your Google Cloud project and that you have appropriate authentication configured (e.g., `gcloud auth application-default login`).
import os
import uuid
from google.cloud.dialogflowcx_v3 import types
from google.cloud.dialogflowcx_v3.services.sessions import SessionsClient
# Set environment variables or replace with your actual values
PROJECT_ID = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')
LOCATION_ID = os.environ.get('DIALOGFLOW_LOCATION', 'global') # e.g., 'us-central1'
AGENT_ID = os.environ.get('DIALOGFLOW_CX_AGENT_ID', 'your-agent-id')
# Unique session ID for a conversation
SESSION_ID = str(uuid.uuid4())
def detect_intent_text(project_id: str, location_id: str, agent_id: str, session_id: str, text: str):
"""Detects intent using text input."""
session_path = (
f"projects/{project_id}/locations/{location_id}/agents/{agent_id}/sessions/{session_id}"
)
client_options = None
if location_id != "global":
client_options = {"api_endpoint": f"{location_id}-dialogflow.googleapis.com"}
session_client = SessionsClient(client_options=client_options)
text_input = types.TextInput(text=text)
query_input = types.QueryInput(text=text_input, language_code="en-US")
request = types.DetectIntentRequest(
session=session_path,
query_input=query_input,
)
response = session_client.detect_intent(request=request)
print(f"User query: {response.query_result.text}")
for message in response.query_result.response_messages:
if message.text:
print(f"Agent response: {message.text.text[0]}")
if response.query_result.match.intent:
print(f"Matched intent: {response.query_result.match.intent.display_name}")
if __name__ == '__main__':
# Example usage:
user_input = "Hello, how are you?"
print(f"Attempting to detect intent for: '{user_input}'")
detect_intent_text(PROJECT_ID, LOCATION_ID, AGENT_ID, SESSION_ID, user_input)
print("\nMake sure to set GOOGLE_CLOUD_PROJECT, DIALOGFLOW_LOCATION, and DIALOGFLOW_CX_AGENT_ID environment variables, and enable the Dialogflow CX API in your project.")
Debug
Known issues
breakingThe `google-cloud-dialogflow-cx` library, as part of the `google-cloud-python` ecosystem, regularly updates its supported Python versions. While PyPI currently lists `Python >= 3.9` as required, other packages in the same monorepo have recently dropped support for Python 3.9. Users on older Python versions (e.g., 3.8 and below) should upgrade to ensure compatibility and receive future updates.fixUpgrade Python to 3.9 or newer (e.g., 3.10+). Regularly check the PyPI `Requires-Python` classifier.
affects: < 2.x for Python <3.9, potential future breaking changes for older Pythons
gotchaDialogflow CX offers `v3` (stable) and `v3beta1` (beta) API versions. While `v3beta1` provides access to the latest features, it is explicitly stated to be unstable and subject to backward-incompatible changes without notice or SLA. Always prefer `v3` for production environments unless specific beta features are required.fixImport from `google.cloud.dialogflowcx_v3` for stable API access. Only use `google.cloud.dialogflowcx_v3beta1` if you understand and accept the risks of using a beta API.
affects: All versions (v3beta1 is inherently unstable)
gotchaWhen importing Protobuf `types` (e.g., `QueryInput`, `Agent`), they are typically available directly under the API version module (e.g., `from google.cloud.dialogflowcx_v3 import types`). Attempting to import from a nested `types` submodule (e.g., `from google.cloud.dialogflowcx_v3.types import Session`) will result in an `ImportError`.fixUse `from google.cloud.dialogflowcx_v3 import types` and then refer to types as `types.Session`, `types.QueryInput`, etc.
affects: All versions
gotchaResource names in Dialogflow CX (e.g., for agents, sessions, flows) are full Google Cloud resource paths (e.g., `projects/<PROJECT_ID>/locations/<LOCATION_ID>/agents/<AGENT_ID>`). Incorrectly formatting these strings will lead to API errors, often `INVALID_ARGUMENT`. Ensure all components (project, location, agent IDs) are correctly provided and formatted.fixCarefully construct resource name strings using f-strings or `os.path.join` for clarity. Validate that all required IDs and locations are present and correct.
affects: All versions
gotchaThe client library logs RPC events using standard Python logging. These logs may contain sensitive information and their content/level can change without being considered a breaking API change. By default, logging events are not handled.fixExplicitly configure Python's `logging` module to handle logs from `google.cloud.dialogflowcx_v3` if you need them. Restrict access to stored logs due to potential sensitive information.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'google.cloud.dialogflowcx_v3'
This error typically occurs when the `google-cloud-dialogflow-cx` library is not installed, or when attempting to import modules from an incorrect version or path, such as trying to use Dialogflow ES imports (`dialogflow_v2`) for a Dialogflow CX project.
fixEnsure the `google-cloud-dialogflow-cx` library is correctly installed (`pip install google-cloud-dialogflow-cx`) and use the correct import paths for Dialogflow CX, usually `from google.cloud import dialogflowcx_v3` or `from google.cloud import dialogflowcx_v3beta1` depending on the desired API version.
```python
from google.cloud import dialogflowcx_v3
# Example client initialization
client = dialogflowcx_v3.AgentsClient()
```
google.api_core.exceptions.PermissionDenied: 403 Permission denied (or AttributeError: type object 'ServiceAccountCredentials' has no attribute 'from_json_keyfile_name')
The service account used for authentication lacks the necessary IAM permissions (e.g., 'Dialogflow API Client' or 'Dialogflow API Editor') to access Dialogflow CX resources in the specified project, or the authentication method used is outdated (e.g., using `oauth2client.service_account.ServiceAccountCredentials` instead of `google.auth.load_credentials_from_file`).
fixGrant the service account the appropriate Dialogflow CX roles (e.g., 'Dialogflow API Client', 'Dialogflow API Editor', or a custom role with required permissions) in the Google Cloud project. Also, ensure you are using the `google-auth` library for credentials:
```python
import google.auth
from google.cloud import dialogflowcx_v3
# Option 1: Using GOOGLE_APPLICATION_CREDENTIALS environment variable
# export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/key.json"
client = dialogflowcx_v3.AgentsClient()
# Option 2: Explicitly load credentials
credentials, project_id = google.auth.load_credentials_from_file(
"/path/to/your/key.json"
)
client = dialogflowcx_v3.AgentsClient(credentials=credentials)
``` google.api_core.exceptions.InvalidArgument: 400 Please refer to https://cloud.google.com/dialogflow/cx/docs/concept/region to find the correct endpoint to access resources located in '<YOUR_REGION_ID>'
This error occurs when attempting to interact with a Dialogflow CX agent in a non-global region without specifying the correct regional API endpoint during client initialization.
fixSet the `api_endpoint` in `ClientOptions` to match the region where your Dialogflow CX agent is located. The format is typically `<REGION_ID>-dialogflow.googleapis.com:443`.
```python
from google.cloud.dialogflowcx_v3 import AgentsClient
from google.api_core.client_options import ClientOptions
project_id = "your-gcp-project-id"
location_id = "your-agent-location-id" # e.g., 'us-central1' or 'europe-west1'
client_options = None
if location_id != "global":
client_options = ClientOptions(api_endpoint=f"{location_id}-dialogflow.googleapis.com:443")
client = AgentsClient(client_options=client_options)
``` google.api_core.exceptions.FailedPrecondition: 400 Dialogflow API has not been used in project <PROJECT_ID> before or it is disabled.
The Dialogflow CX API has not been enabled for the Google Cloud project specified, or the project ID provided is incorrect.
fixEnable the Dialogflow API for your Google Cloud project via the Google Cloud Console or using the `gcloud` CLI. Verify that the project ID used in your code matches the one where the API is enabled.
**Via `gcloud` CLI:**
```bash
gcloud services enable dialogflow.googleapis.com --project=<YOUR_PROJECT_ID>
```
**Via Google Cloud Console:**
1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Select your project.
3. Navigate to 'APIs & Services' > 'Enabled APIs & Services'.
4. Click 'ENABLE APIS AND SERVICES' and search for 'Dialogflow API' (or 'Dialogflow CX API').
5. Enable the API.
Upgrade
Version history
2.7.0latest on PyPI · released Jun 25, 2026
Audit
Dependencies
google-api-corerequiredCore utilities for Google Cloud client libraries.
google-authrequiredHandles authentication with Google Cloud services.
proto-plusrequiredProvides Pythonic wrappers around raw Protobuf messages.
protobufrequiredUnderlying Protobuf serialization library.