Registry / gcp / google-cloud-dialogflow-cx

google-cloud-dialogflow-cx

JSON →
library2.7.0pypypi✓ verified 21d ago

The `google-cloud-dialogflow-cx` client library provides Pythonic access to the Google Cloud Dialogflow CX API. Dialogflow CX is a conversational AI platform designed for building advanced virtual agents with complex, multi-turn conversations using a visual state-machine approach. This library facilitates interaction with Dialogflow CX agents, sessions, intents, flows, and other resources. It is part of the larger `google-cloud-python` ecosystem, which typically sees frequent updates and releases.

pip install google-cloud-dialogflow-cx
INSTALL
IMPORT
SIG · GOOGLE-CLOUD-DIALO
G
google-cloud-dialogflow-cx
gcppythonv2.7.0
Install
6.5s avg
Import
2366ms
Disk
98MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 3.016s · 97.2MB
glibc
py 3.103.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.
fix
Upgrade 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.
fix
Import 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`.
fix
Use `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.
fix
Carefully 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.
fix
Explicitly 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.
fix
Ensure 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`).
fix
Grant 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.
fix
Set 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.
fix
Enable 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.
Agent activity
30 hits · last 30 days
node
24
OpenAI (training)
1
Resources
google-cloud-dialogflow-cx — pip install google-cloud-dialogflow-cx · libregistry