sickn33/agentic-awesome-skills/azure-ai-language-conversations-py

Azure AI Language Conversations for Python

When to Use

Use this skill when you need implement Conversational Language Understanding (CLU) using the azure-ai-language-conversations Python SDK. Use when working with ConversationAnalysisClient to analyze conversation intent and entities, building NLP features, or integrating language understanding into applications.

System Prompt

You are an expert Python developer specializing in Azure AI Services and Natural Language Processing. Your task is to help users implement Conversational Language Understanding (CLU) using the azure-ai-language-conversations SDK.

When responding to requests about Azure AI Language Conversations:

1. Select and pin a supported, tested version of the azure-ai-language-conversations SDK.
2. Emphasize the use of ConversationAnalysisClient with DefaultAzureCredential.
3. Provide clear code examples demonstrating how to structure the conversation payload.
4. Handle exceptions properly.

Authentication & Lifecycle

🔑 Two rules apply to every code sample below:

1. Prefer `DefaultAzureCredential`. Configure the intended credential and least-privilege data-plane roles for the target resource. API keys are supported where enabled; they require secret storage and rotation and do not provide per-user Entra identity.

- Local dev: sign in using an enabled developer credential and verify the selected tenant/account.

- Production: set AZURE_TOKEN_CREDENTIALS=prod (or AZURE_TOKEN_CREDENTIALS=<specific_credential>) only with an azure-identity version supporting that setting; otherwise use an explicit managed/workload identity credential.

2. Wrap every client in a context manager so HTTP transports, sockets, and token caches are released deterministically:

- Sync: with <Client>(...) as client:

- Async: async with <Client>(...) as client: and async with DefaultAzureCredential() as credential: (from azure.identity.aio)

Snippets may abbreviate this setup, but production code should always follow both rules.

ConversationAnalysisClient accepts a TokenCredential such as DefaultAzureCredential. Use the token credential — it works locally (Azure CLI / VS Code / Developer CLI) and in Azure (managed identity, workload identity) with no code change.

Legacy: API Key (existing keyed deployments)

New code should use DefaultAzureCredential. Use AzureKeyCredential only if you have an existing keyed deployment that hasn't been migrated to Entra ID yet — for example, regulated environments still completing their Entra rollout.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations import ConversationAnalysisClient
endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
key = os.environ["AZURE_CONVERSATIONS_KEY"]
with ConversationAnalysisClient(endpoint, AzureKeyCredential(key)) as client:
    # See "Basic Conversation Analysis" below for the analyze_conversation payload
    ...

Best Practices

• Pick sync OR async 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. Choose one mode per module.
• Always use context managers for clients and async credentials. Wrap every client in with ConversationAnalysisClient(...) as client: (sync) or async with ConversationAnalysisClient(...) as client: (async). For async DefaultAzureCredential from azure.identity.aio, also use async with credential: so tokens and transports are cleaned up.
• Use `DefaultAzureCredential` for portable auth across local dev and Azure with the correct tenant, identity and roles; store and rotate supported API keys when needed.
• Use environment variables for the endpoint, project name, and deployment name.
• Clearly map the participantId and id in the conversationItem payload.

Examples

Basic Conversation Analysis

import os
from azure.identity import DefaultAzureCredential
from azure.ai.language.conversations import ConversationAnalysisClient
endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
project_name = os.environ["AZURE_CONVERSATIONS_PROJECT"]
deployment_name = os.environ["AZURE_CONVERSATIONS_DEPLOYMENT"]
# DefaultAzureCredential works locally and in Azure with no code change.
credential = DefaultAzureCredential()
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']}")
credential.close()

Obtain permission to send conversation text to Azure. Minimize personal data and set appropriate retention/logging controls; isLoggingEnabled=False is not a complete privacy guarantee. Intent predictions are probabilistic and must not directly authorize sensitive actions.

Limitations

• Use this skill only when the task clearly matches its upstream source and local project context.
• Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
• Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.