{"id":9538,"library":"azure-ai-language-conversations","title":"Azure AI Language - Conversational Language Understanding","description":"The Azure AI Language - Conversational Language Understanding (CLU) client library for Python allows developers to integrate CLU capabilities into their applications. It enables natural language understanding of conversational inputs, extracting intents, entities, and performing orchestrations across multiple language services. The current version is 1.1.0, and Azure SDKs typically have a frequent release cadence, with minor updates monthly or bi-monthly.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-python/tree/main/sdk/cognitivelanguage/azure-ai-language-conversations","tags":["azure","ai","language","nlp","conversations","clu","microsoft"],"install":[{"cmd":"pip install azure-ai-language-conversations","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core utilities for Azure SDKs","package":"azure-core","optional":false},{"reason":"Required for Azure Active Directory authentication (e.g., DefaultAzureCredential)","package":"azure-identity","optional":true}],"imports":[{"note":"Old Azure SDKs sometimes used a `cognitiveservices` prefix. The modern package structure is `azure.ai.language.conversations`.","wrong":"from azure.cognitiveservices.language.conversations import ConversationAnalysisClient","symbol":"ConversationAnalysisClient","correct":"from azure.ai.language.conversations import ConversationAnalysisClient"},{"note":"Credentials are provided by `azure-core`, not directly by the specific client library.","wrong":"from azure.ai.language.conversations.credentials import AzureKeyCredential","symbol":"AzureKeyCredential","correct":"from azure.core.credentials import AzureKeyCredential"},{"note":"`DefaultAzureCredential` is part of the `azure-identity` library for Azure Active Directory authentication.","wrong":"from azure.ai.language.conversations import DefaultAzureCredential","symbol":"DefaultAzureCredential","correct":"from azure.identity import DefaultAzureCredential"}],"quickstart":{"code":"import os\nfrom azure.ai.language.conversations import ConversationAnalysisClient\nfrom azure.core.credentials import AzureKeyCredential\n# from azure.identity import DefaultAzureCredential # Uncomment for Azure AD authentication\n\n# --- Set these environment variables before running ---\n# export LANGUAGE_ENDPOINT='https://your-language-resource.cognitiveservices.azure.com/'\n# export LANGUAGE_KEY='your-azure-language-resource-key'\n# export CLU_PROJECT_NAME='your-clu-project-name'\n# export CLU_DEPLOYMENT_NAME='your-clu-deployment-name'\n# -----------------------------------------------------\n\nlanguage_endpoint = os.environ.get(\"LANGUAGE_ENDPOINT\", \"\")\nlanguage_key = os.environ.get(\"LANGUAGE_KEY\", \"\")\nclu_project_name = os.environ.get(\"CLU_PROJECT_NAME\", \"\")\nclu_deployment_name = os.environ.get(\"CLU_DEPLOYMENT_NAME\", \"\")\n\nif not all([language_endpoint, language_key, clu_project_name, clu_deployment_name]):\n    print(\"ERROR: Please set the environment variables LANGUAGE_ENDPOINT, LANGUAGE_KEY, CLU_PROJECT_NAME, and CLU_DEPLOYMENT_NAME.\")\n    print(\"Refer to the comments in the quickstart code for examples.\")\n    exit(1)\n\n# Authenticate with AzureKeyCredential\n# For production scenarios, consider using DefaultAzureCredential from azure.identity for Azure AD authentication:\n# client = ConversationAnalysisClient(endpoint=language_endpoint, credential=DefaultAzureCredential())\nclient = ConversationAnalysisClient(\n    endpoint=language_endpoint,\n    credential=AzureKeyCredential(language_key)\n)\n\ntext = \"How do I get to the nearest ATM?\"\n\nprint(f\"\\nAnalyzing conversation: '{text}' for project '{clu_project_name}' (deployment '{clu_deployment_name}')\")\n\ntry:\n    response = client.analyze_conversation(\n        task={\n            \"kind\": \"Conversation\",\n            \"analysisInput\": {\n                \"conversationItem\": {\n                    \"participantId\": \"1\",\n                    \"id\": \"1\",\n                    \"text\": text\n                }\n            },\n            \"parameters\": {\n                \"projectName\": clu_project_name,\n                \"deploymentName\": clu_deployment_name,\n                \"verbose\": True # Set to False for less detailed output\n            }\n        }\n    )\n\n    result = response.as_dict()\n    prediction = result[\"result\"][\"prediction\"]\n    \n    if prediction[\"projectKind\"] == \"Conversation\":\n        print(\"  Top intent:\", prediction[\"topIntent\"])\n        print(\"  Entities:\")\n        for entity in prediction[\"entities\"]:\n            print(f\"  - {entity['category']}: {entity['text']} (confidence: {entity['confidence']:.2f})\")\n    else:\n        # This branch handles orchestrator projects or other unknown kinds\n        print(f\"  Prediction project kind: {prediction['projectKind']}. Full prediction: {prediction}\")\n\nexcept Exception as e:\n    print(f\"\\nAn error occurred: {e}\")\n    print(\"Please ensure your environment variables are correct and the CLU project is deployed.\")","lang":"python","description":"This quickstart demonstrates how to initialize the `ConversationAnalysisClient` and perform a basic conversation analysis to extract intents and entities from a given text using a deployed Conversational Language Understanding (CLU) project. It uses `AzureKeyCredential` for authentication, requiring an endpoint and an API key for your Azure Language resource, along with the CLU project and deployment names."},"warnings":[{"fix":"Ensure your `language_endpoint` variable starts with `https://` (e.g., `https://your-resource.cognitiveservices.azure.com/`).","message":"The Azure Language resource endpoint must include the `https://` scheme. Omitting it will lead to `ValueError: Invalid URL` errors.","severity":"gotcha","affected_versions":"All 1.x versions"},{"fix":"Correct usage: `ConversationAnalysisClient(endpoint=my_endpoint, credential=AzureKeyCredential(my_key))`.","message":"The `ConversationAnalysisClient` constructor expects `credential` to be an instance of a credential type (e.g., `AzureKeyCredential(key)`) not just the key string itself. Swapping `endpoint` and `credential` arguments is also a common mistake.","severity":"gotcha","affected_versions":"All 1.x versions"},{"fix":"Refer to the latest official Azure AI Language documentation or SDK examples for the specific `task` input structure, especially when upgrading or encountering `BadRequest` errors.","message":"The structure of the `task` dictionary passed to `analyze_conversation` (and `analyze_conversation_orchestration`) can change between minor versions or if using preview API versions. Always consult the official documentation for the exact payload required for your service version.","severity":"breaking","affected_versions":"Potentially across minor versions (e.g., 1.0.0 to 1.1.0) or between preview and GA APIs."},{"fix":"For asynchronous operations, use `from azure.ai.language.conversations.aio import ConversationAnalysisClient` and wrap your calls in an `async def` function, using `await client.analyze_conversation(...)`.","message":"Azure SDKs often provide both synchronous (default) and asynchronous clients. If you're building an async application, ensure you import `ConversationAnalysisClient` from `azure.ai.language.conversations.aio` and use `await` with its methods.","severity":"gotcha","affected_versions":"All 1.x versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Verify that `LANGUAGE_KEY` and `LANGUAGE_ENDPOINT` environment variables match your Azure Language resource. Check the resource's Access Control (IAM) settings for appropriate permissions if using Azure AD authentication.","cause":"The Azure Language resource key or endpoint is incorrect, expired, or the principal lacks necessary permissions (e.g., 'Cognitive Services User').","error":"azure.core.exceptions.ClientAuthenticationError: Authentication failed: You don't have permission to perform this action. Request ID: ..."},{"fix":"Ensure your `LANGUAGE_ENDPOINT` environment variable (or hardcoded endpoint) includes `https://` at the beginning, e.g., `https://your-resource.cognitiveservices.azure.com/`.","cause":"The `endpoint` provided to the client constructor is missing the `https://` protocol prefix.","error":"ValueError: Invalid URL 'your-endpoint.cognitiveservices.azure.com': No schema supplied. Perhaps you meant https://your-endpoint.cognitiveservices.azure.com/"},{"fix":"Inspect the full `response.as_dict()` output to understand the actual structure. This might indicate a service-side error (check `response.error`) or an API version mismatch. Update your parsing logic or client library version if an API model has changed.","cause":"The structure of the response object from the `analyze_conversation` method did not contain the expected 'prediction' key. This can happen if the service returns an error or if the response model changes.","error":"KeyError: 'prediction'"},{"fix":"Install the package using `pip install azure-ai-language-conversations`. If using virtual environments, ensure you've activated the correct one.","cause":"The `azure-ai-language-conversations` package is not installed or the Python environment is incorrect.","error":"ModuleNotFoundError: No module named 'azure.ai.language.conversations'"},{"fix":"Ensure you instantiate the credential correctly: `credential=AzureKeyCredential(language_key)`. Do not use `credential=language_key` or `credential=AzureKeyCredential` without the key in parentheses.","cause":"This typically occurs if you pass the `AzureKeyCredential` object directly to the `credential` argument without instantiating it with the key, or if you accidentally call it like a function.","error":"TypeError: 'AzureKeyCredential' object is not callable"}]}