Registry /
azure / azure-ai-language-conversations
Install & Compatibility
Where this runs
tested against v1.1.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.910 runs
installs and imports cleanly · install 0.0s · import 0.427s · 25.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.4s · import 0.388s · 26MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ConversationAnalysisClient
✓ from azure.ai.language.conversations import ConversationAnalysisClient
✗ from azure.cognitiveservices.language.conversations import ConversationAnalysisClient
Old Azure SDKs sometimes used a `cognitiveservices` prefix. The modern package structure is `azure.ai.language.conversations`.
AzureKeyCredential
✓ from azure.core.credentials import AzureKeyCredential
✗ from azure.ai.language.conversations.credentials import AzureKeyCredential
Credentials are provided by `azure-core`, not directly by the specific client library.
DefaultAzureCredential
✓ from azure.identity import DefaultAzureCredential
✗ from azure.ai.language.conversations import DefaultAzureCredential
`DefaultAzureCredential` is part of the `azure-identity` library for Azure Active Directory authentication.
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.
import os
from azure.ai.language.conversations import ConversationAnalysisClient
from azure.core.credentials import AzureKeyCredential
# from azure.identity import DefaultAzureCredential # Uncomment for Azure AD authentication
# --- Set these environment variables before running ---
# export LANGUAGE_ENDPOINT='https://your-language-resource.cognitiveservices.azure.com/'
# export LANGUAGE_KEY='your-azure-language-resource-key'
# export CLU_PROJECT_NAME='your-clu-project-name'
# export CLU_DEPLOYMENT_NAME='your-clu-deployment-name'
# -----------------------------------------------------
language_endpoint = os.environ.get("LANGUAGE_ENDPOINT", "")
language_key = os.environ.get("LANGUAGE_KEY", "")
clu_project_name = os.environ.get("CLU_PROJECT_NAME", "")
clu_deployment_name = os.environ.get("CLU_DEPLOYMENT_NAME", "")
if not all([language_endpoint, language_key, clu_project_name, clu_deployment_name]):
print("ERROR: Please set the environment variables LANGUAGE_ENDPOINT, LANGUAGE_KEY, CLU_PROJECT_NAME, and CLU_DEPLOYMENT_NAME.")
print("Refer to the comments in the quickstart code for examples.")
exit(1)
# Authenticate with AzureKeyCredential
# For production scenarios, consider using DefaultAzureCredential from azure.identity for Azure AD authentication:
# client = ConversationAnalysisClient(endpoint=language_endpoint, credential=DefaultAzureCredential())
client = ConversationAnalysisClient(
endpoint=language_endpoint,
credential=AzureKeyCredential(language_key)
)
text = "How do I get to the nearest ATM?"
print(f"\nAnalyzing conversation: '{text}' for project '{clu_project_name}' (deployment '{clu_deployment_name}')")
try:
response = client.analyze_conversation(
task={
"kind": "Conversation",
"analysisInput": {
"conversationItem": {
"participantId": "1",
"id": "1",
"text": text
}
},
"parameters": {
"projectName": clu_project_name,
"deploymentName": clu_deployment_name,
"verbose": True # Set to False for less detailed output
}
}
)
result = response.as_dict()
prediction = result["result"]["prediction"]
if prediction["projectKind"] == "Conversation":
print(" Top intent:", prediction["topIntent"])
print(" Entities:")
for entity in prediction["entities"]:
print(f" - {entity['category']}: {entity['text']} (confidence: {entity['confidence']:.2f})")
else:
# This branch handles orchestrator projects or other unknown kinds
print(f" Prediction project kind: {prediction['projectKind']}. Full prediction: {prediction}")
except Exception as e:
print(f"\nAn error occurred: {e}")
print("Please ensure your environment variables are correct and the CLU project is deployed.")
Debug
Known issues
gotchaThe Azure Language resource endpoint must include the `https://` scheme. Omitting it will lead to `ValueError: Invalid URL` errors.fixEnsure your `language_endpoint` variable starts with `https://` (e.g., `https://your-resource.cognitiveservices.azure.com/`).
affects: All 1.x versions
gotchaThe `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.fixCorrect usage: `ConversationAnalysisClient(endpoint=my_endpoint, credential=AzureKeyCredential(my_key))`.
affects: All 1.x versions
breakingThe 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.fixRefer to the latest official Azure AI Language documentation or SDK examples for the specific `task` input structure, especially when upgrading or encountering `BadRequest` errors.
affects: Potentially across minor versions (e.g., 1.0.0 to 1.1.0) or between preview and GA APIs.
gotchaAzure 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.fixFor 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(...)`.
affects: All 1.x versions
Errors
Common errors & fixes
azure.core.exceptions.ClientAuthenticationError: Authentication failed: You don't have permission to perform this action. Request ID: ...
The Azure Language resource key or endpoint is incorrect, expired, or the principal lacks necessary permissions (e.g., 'Cognitive Services User').
fixVerify 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.
ValueError: Invalid URL 'your-endpoint.cognitiveservices.azure.com': No schema supplied. Perhaps you meant https://your-endpoint.cognitiveservices.azure.com/
The `endpoint` provided to the client constructor is missing the `https://` protocol prefix.
fixEnsure your `LANGUAGE_ENDPOINT` environment variable (or hardcoded endpoint) includes `https://` at the beginning, e.g., `https://your-resource.cognitiveservices.azure.com/`.
KeyError: 'prediction'
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.
fixInspect 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.
ModuleNotFoundError: No module named 'azure.ai.language.conversations'
The `azure-ai-language-conversations` package is not installed or the Python environment is incorrect.
fixInstall the package using `pip install azure-ai-language-conversations`. If using virtual environments, ensure you've activated the correct one.
TypeError: 'AzureKeyCredential' object is not callable
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.
fixEnsure you instantiate the credential correctly: `credential=AzureKeyCredential(language_key)`. Do not use `credential=language_key` or `credential=AzureKeyCredential` without the key in parentheses.
Upgrade
Version history
1.1.0latest on PyPI · released Jun 14, 2023
Audit
Dependencies
azure-corerequiredCore utilities for Azure SDKs
azure-identityoptionalRequired for Azure Active Directory authentication (e.g., DefaultAzureCredential)