azure-ai-language-conversations-py
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
Install
npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
git clone https://github.com/microsoft/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole microsoft/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Azure AI Language Conversations for Python
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:
- Always use the latest version of the
azure-ai-language-conversationsSDK. - Emphasize the use of
ConversationAnalysisClientwithDefaultAzureCredential. - Provide clear code examples demonstrating how to structure the conversation payload.
- Handle exceptions properly.
Authentication & Lifecycle
🔑 Two rules apply to every code sample below:
- Prefer
DefaultAzureCredential. It works locally (Azure CLI / VS Code / Developer CLI) and in Azure (managed identity, workload identity) with no code change. Avoid connection strings, account/API keys — they bypass Entra audit and rotation.
- Local dev:
DefaultAzureCredentialworks as-is.- Production: set
AZURE_TOKEN_CREDENTIALS=prod(orAZURE_TOKEN_CREDENTIALS=<specific_credential>) to constrain the credential chain to production-safe credentials.- 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:andasync with DefaultAzureCredential() as credential:(fromazure.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.conversationssync clients withazure.ai.language.conversations.aioasync 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) orasync with ConversationAnalysisClient(...) as client:(async). For asyncDefaultAzureCredentialfromazure.identity.aio, also useasync with credential:so tokens and transports are cleaned up. - Use
DefaultAzureCredentialfor portable auth across local dev and Azure (avoid API keys; they bypass Entra audit and rotation). - Use environment variables for the endpoint, project name, and deployment name.
- Clearly map the
participantIdandidin theconversationItempayload.
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']}")
Reference Files
| File | Contents |
|---|---|
| references/capabilities.md | Additional non-hero capabilities, operation-group coverage, and production checklists. |
| references/non-hero-scenarios.md | Dedicated non-hero examples for secondary/advanced scenarios. |
Files (skills)
-
references
-
capabilities.md 1.1 KB
Loading… -
non-hero-scenarios.md 5.3 KB
Loading…
-
-
SKILL.md 5.4 KB
--- name: azure-ai-language-conversations-py description: 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. license: MIT metadata: author: Microsoft version: "1.0.0" --- # Azure AI Language Conversations for Python ## 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. Always use the latest 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`.** It works locally (Azure CLI / VS Code / Developer CLI) and in Azure (managed identity, workload identity) with no code change. Avoid connection strings, account/API keys — they bypass Entra audit and rotation. > - Local dev: `DefaultAzureCredential` works as-is. > - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=<specific_credential>`) to constrain the credential chain to production-safe credentials. > 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. ```python 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 (avoid API keys; they bypass Entra audit and rotation). - 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 ```python 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']}") ``` ## Reference Files | File | Contents | |------|----------| | [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | | [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. |
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.