Google Cloud Dialogflow CX

Warnings

• breaking The `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.
• gotcha Dialogflow 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.
• gotcha When 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.
• gotcha Resource 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.
• gotcha The 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.

Install

• pip install google-cloud-dialogflow-cx Install stable version

Imports

• AgentsClient

  from google.cloud.dialogflowcx_v3 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

  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`.

Quickstart

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.")