Build conversational AI with Azure Language Understanding

This official Microsoft skill, published in the microsoft/skills repository under the MIT license, helps you implement Conversational Language Understanding (CLU) in Python with the azure-ai-language-conversations SDK. It centers on ConversationAnalysisClient: analyzing a conversation to get its intent and entities, structuring the conversation payload the service expects, and setting up authentication and client lifecycle the way Microsoft recommends. Its system prompt casts the assistant as an expert Python developer for Azure AI Services and Natural Language Processing, with four standing instructions: use the latest version of the SDK, emphasize ConversationAnalysisClient with DefaultAzureCredential, give clear code examples that show how the conversation payload is structured, and handle exceptions properly.

Use it when you are writing code against ConversationAnalysisClient, building NLP features that need intent and entity analysis of conversational text, or integrating language understanding into an existing application. Two rules apply to every code sample in the skill. First, prefer DefaultAzureCredential over connection strings and account or API keys, because keys bypass Entra audit and rotation. Second, wrap every client in a context manager (with ... as client: for sync code, async with ... as client: for async code, plus async with on the async credential from azure.identity.aio) so HTTP transports, sockets, and token caches are released deterministically. Pick sync or async per module and stay consistent: do not mix azure.ai.language.conversations sync clients with azure.ai.language.conversations.aio async clients in the same call path.

Do not reach for AzureKeyCredential in new code. The skill keeps it only as a legacy path for existing keyed deployments that have not yet migrated to Entra ID, for example regulated environments still completing their Entra rollout. The skill's own limitations also apply: use it only when the task clearly matches its upstream source and your project context, verify generated code, dependencies, credentials, and external service behavior before applying changes, and do not treat its examples as a substitute for environment-specific tests, security review, or approval for destructive or costly actions.

Inputs are the endpoint, project name, and deployment name, read from the environment variables AZURE_CONVERSATIONS_ENDPOINT, AZURE_CONVERSATIONS_PROJECT, and AZURE_CONVERSATIONS_DEPLOYMENT, plus a credential. The request is an analyze_conversation task of kind Conversation: an analysisInput that holds a conversationItem (participantId, id, modality, language, text) and isLoggingEnabled, and parameters with projectName, deploymentName, and verbose. The skill asks you to map participantId and id in the conversationItem clearly. Its basic example sends one text utterance and prints the top intent from the prediction:

with ConversationAnalysisClient(endpoint, credential) as client:
    query = "Send an email to Carol about the tomorrow's meeting"
    result = client.analyze_conversation(
        task={
            "kind": "Conversation",
            "analysisInput": {
                "conversationItem": {
                    "participantId": "1",
                    "id": "1",
                    "modality": "text",
                    "language": "en",
                    "text": query
                },
                "isLoggingEnabled": False
            },
            "parameters": {
                "projectName": project_name,
                "deploymentName": deployment_name,
                "verbose": True
            }
        }
    )

    print(f"Top intent: {result['result']['prediction']['topIntent']}")

Authentication goes through DefaultAzureCredential from azure.identity, or from azure.identity.aio in async code. It works locally with Azure CLI, VS Code, or Developer CLI sign-in and in Azure with managed identity or workload identity, with no code change. In production, setting AZURE_TOKEN_CREDENTIALS=prod, or naming a specific credential in that variable, constrains the credential chain to production-safe credentials. The legacy path uses AzureKeyCredential from azure.core.credentials, with the key read from AZURE_CONVERSATIONS_KEY.