Azure.AI.Language.Conversations 1.0.0-beta.3

Azure Cognitive Language Services Conversations client library for .NET

Azure Conversations - the new version of Language Understanding (LUIS) - is a cloud-based conversational AI service that applies custom machine-learning intelligence to a user's conversational, natural language text to predict overall meaning; and pulls out relevant, detailed information. The service utilizes state-of-the-art technology to create and utilize natively multilingual models, which means that users would be able to train their models in one language but predict in others.

Source code | Package (NuGet) | API reference documentation | Product documentation | Samples

Getting started

Install the package

Install the Azure Cognitive Language Services Conversations client library for .NET with NuGet:

dotnet add package Azure.AI.Language.Conversations --prerelease

Prerequisites

• An Azure subscription
• An existing Text Analytics resource

Note: the new unified Cognitive Language Services are not currently available for deployment.

Authenticate the client

In order to interact with the Conversations service, you'll need to create an instance of the ConversationAnalysisClient class. You will need an endpoint, and an API key to instantiate a client object. For more information regarding authenticating with Cognitive Services, see Authenticate requests to Azure Cognitive Services.

Get an API key

You can get the endpoint and an API key from the Cognitive Services resource in the Azure Portal.

Alternatively, use the Azure CLI command shown below to get the API key from the Cognitive Service resource.

az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>

Create a ConversationAnalysisClient

Once you've determined your endpoint and API key you can instantiate a ConversationAnalysisClient:

Uri endpoint = new Uri("https://myaccount.api.cognitive.microsoft.com");
AzureKeyCredential credential = new AzureKeyCredential("{api-key}");

ConversationAnalysisClient client = new ConversationAnalysisClient(endpoint, credential);

Key concepts

ConversationAnalysisClient

The ConversationAnalysisClient is the primary interface for making predictions using your deployed Conversations models. It provides both synchronous and asynchronous APIs to submit queries.

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime

Examples

The Azure.AI.Language.Conversations client library provides both synchronous and asynchronous APIs.

The following examples show common scenarios using the client created above.

Analyze a conversation

To analyze a conversation, you can call the client.AnalyzeConversation() method which takes a TextConversationItem and ConversationsProject as parameters.

ConversationsProject conversationsProject = new ConversationsProject("Menu", "production");

Response<AnalyzeConversationTaskResult> response = client.AnalyzeConversation(
    "Send an email to Carol about the tomorrow's demo.",
    conversationsProject);

CustomConversationalTaskResult customConversationalTaskResult = response.Value as CustomConversationalTaskResult;
ConversationPrediction conversationPrediction = customConversationalTaskResult.Results.Prediction as ConversationPrediction;

Console.WriteLine($"Top intent: {conversationPrediction.TopIntent}");

Console.WriteLine("Intents:");
foreach (ConversationIntent intent in conversationPrediction.Intents)
{
    Console.WriteLine($"Category: {intent.Category}");
    Console.WriteLine($"Confidence: {intent.Confidence}");
    Console.WriteLine();
}

Console.WriteLine("Entities:");
foreach (ConversationEntity entity in conversationPrediction.Entities)
{
    Console.WriteLine($"Category: {entity.Category}");
    Console.WriteLine($"Text: {entity.Text}");
    Console.WriteLine($"Offset: {entity.Offset}");
    Console.WriteLine($"Length: {entity.Length}");
    Console.WriteLine($"Confidence: {entity.Confidence}");
    Console.WriteLine();

    foreach (BaseResolution resolution in entity.Resolutions)
    {
        if (resolution is DateTimeResolution dateTimeResolution)
        {
            Console.WriteLine($"Datetime Sub Kind: {dateTimeResolution.DateTimeSubKind}");
            Console.WriteLine($"Timex: {dateTimeResolution.Timex}");
            Console.WriteLine($"Value: {dateTimeResolution.Value}");
            Console.WriteLine();
        }
    }
}

The specified parameters can also be used to initialize a AnalyzeConversationOptions instance. You can then call AnalyzeConversation() using the options object as a parameter as shown below.

You can also set the verbose parameter in the AnalyzeConversation() method.

TextConversationItem input = new TextConversationItem(
    participantId: "1",
    id: "1",
    text: "Send an email to Carol about the tomorrow's demo.");
AnalyzeConversationOptions options = new AnalyzeConversationOptions(input)
{
    IsLoggingEnabled = true,
    Verbose = true
};

ConversationsProject conversationsProject = new ConversationsProject("Menu", "production");

Response<AnalyzeConversationTaskResult> response = client.AnalyzeConversation(
    "Send an email to Carol about the tomorrow's demo.",
    conversationsProject,
    options);

CustomConversationalTaskResult customConversationalTaskResult = response.Value as CustomConversationalTaskResult;
ConversationPrediction conversationPrediction = customConversationalTaskResult.Results.Prediction as ConversationPrediction;

Console.WriteLine($"Project Kind: {customConversationalTaskResult.Results.Prediction.ProjectKind}");
Console.WriteLine($"Top intent: {conversationPrediction.TopIntent}");

Console.WriteLine("Intents:");
foreach (ConversationIntent intent in conversationPrediction.Intents)
{
    Console.WriteLine($"Category: {intent.Category}");
    Console.WriteLine($"Confidence: {intent.Confidence}");
    Console.WriteLine();
}

Console.WriteLine("Entities:");
foreach (ConversationEntity entity in conversationPrediction.Entities)
{
    Console.WriteLine($"Category: {entity.Category}");
    Console.WriteLine($"Text: {entity.Text}");
    Console.WriteLine($"Offset: {entity.Offset}");
    Console.WriteLine($"Length: {entity.Length}");
    Console.WriteLine($"Confidence: {entity.Confidence}");
    Console.WriteLine();

    foreach (BaseResolution resolution in entity.Resolutions)
    {
        if (resolution is DateTimeResolution dateTimeResolution)
        {
            Console.WriteLine($"Datetime Sub Kind: {dateTimeResolution.DateTimeSubKind}");
            Console.WriteLine($"Timex: {dateTimeResolution.Timex}");
            Console.WriteLine($"Value: {dateTimeResolution.Value}");
            Console.WriteLine();
        }
    }
}

Analyze a conversation in a different language

The language property in the TextConversationItem can be used to specify the language of the conversation.

TextConversationItem input = new TextConversationItem(
    participantId: "1",
    id: "1",
    text: "Tendremos 2 platos de nigiri de salmón braseado.")
{
    Language = "es"
};
AnalyzeConversationOptions options = new AnalyzeConversationOptions(input);

ConversationsProject conversationsProject = new ConversationsProject("Menu", "production");

Response<AnalyzeConversationTaskResult> response = client.AnalyzeConversation(
    textConversationItem,
    conversationsProject,
    options);

CustomConversationalTaskResult customConversationalTaskResult = response.Value as CustomConversationalTaskResult;
ConversationPrediction conversationPrediction = customConversationalTaskResult.Results.Prediction as ConversationPrediction;

Console.WriteLine($"Project Kind: {customConversationalTaskResult.Results.Prediction.ProjectKind}");
Console.WriteLine($"Top intent: {conversationPrediction.TopIntent}");

Console.WriteLine("Intents:");
foreach (ConversationIntent intent in conversationPrediction.Intents)
{
    Console.WriteLine($"Category: {intent.Category}");
    Console.WriteLine($"Confidence: {intent.Confidence}");
    Console.WriteLine();
}

Console.WriteLine("Entities:");
foreach (ConversationEntity entity in conversationPrediction.Entities)
{
    Console.WriteLine($"Category: {entity.Category}");
    Console.WriteLine($"Text: {entity.Text}");
    Console.WriteLine($"Offset: {entity.Offset}");
    Console.WriteLine($"Length: {entity.Length}");
    Console.WriteLine($"Confidence: {entity.Confidence}");
    Console.WriteLine();

    foreach (BaseResolution resolution in entity.Resolutions)
    {
        if (resolution is DateTimeResolution dateTimeResolution)
        {
            Console.WriteLine($"Datetime Sub Kind: {dateTimeResolution.DateTimeSubKind}");
            Console.WriteLine($"Timex: {dateTimeResolution.Timex}");
            Console.WriteLine($"Value: {dateTimeResolution.Value}");
            Console.WriteLine();
        }
    }
}

Other optional properties can be set such as verbosity and whether service logging is enabled.

Analyze a conversation - Orchestration Project

To analyze a conversation using an orchestration project, you can then call the client.AnalyzeConversation() just like the conversation project. But you have to cast the prediction to OrchestratorPrediction. Also, you have to cast the intent type into the one you need.

Orchestration Project - Conversation Prediction

string respondingProjectName = orchestratorPrediction.TopIntent;
TargetIntentResult targetIntentResult = orchestratorPrediction.Intents[respondingProjectName];

if (targetIntentResult.TargetKind == TargetKind.Conversation)
{
    ConversationTargetIntentResult cluTargetIntentResult = targetIntentResult as ConversationTargetIntentResult;

    ConversationResult conversationResult = cluTargetIntentResult.Result;
    ConversationPrediction conversationPrediction = conversationResult.Prediction;

    Console.WriteLine($"Top Intent: {conversationResult.Prediction.TopIntent}");
    Console.WriteLine($"Intents:");
    foreach (ConversationIntent intent in conversationPrediction.Intents)
    {
        Console.WriteLine($"Intent Category: {intent.Category}");
        Console.WriteLine($"Confidence: {intent.Confidence}");
        Console.WriteLine();
    }

    Console.WriteLine($"Entities:");
    foreach (ConversationEntity entity in conversationPrediction.Entities)
    {
        Console.WriteLine($"Entity Text: {entity.Text}");
        Console.WriteLine($"Entity Category: {entity.Category}");
        Console.WriteLine($"Confidence: {entity.Confidence}");
        Console.WriteLine($"Starting Position: {entity.Offset}");
        Console.WriteLine($"Length: {entity.Length}");
        Console.WriteLine();

        foreach (BaseResolution resolution in entity.Resolutions)
        {
            if (resolution is DateTimeResolution dateTimeResolution)
            {
                Console.WriteLine($"Datetime Sub Kind: {dateTimeResolution.DateTimeSubKind}");
                Console.WriteLine($"Timex: {dateTimeResolution.Timex}");
                Console.WriteLine($"Value: {dateTimeResolution.Value}");
                Console.WriteLine();
            }
        }
    }
}

Orchestration Project - QuestionAnswering Prediction

string respondingProjectName = orchestratorPrediction.TopIntent;
TargetIntentResult targetIntentResult = orchestratorPrediction.Intents[respondingProjectName];

if (targetIntentResult.TargetKind == TargetKind.QuestionAnswering)
{
    Console.WriteLine($"Top intent: {respondingProjectName}");

    QuestionAnsweringTargetIntentResult qnaTargetIntentResult = targetIntentResult as QuestionAnsweringTargetIntentResult;

    KnowledgeBaseAnswers qnaAnswers = qnaTargetIntentResult.Result;

    Console.WriteLine("Answers: \n");
    foreach (KnowledgeBaseAnswer answer in qnaAnswers.Answers)
    {
        Console.WriteLine($"Answer: {answer.Answer}");
        Console.WriteLine($"Confidence: {answer.Confidence}");
        Console.WriteLine($"Source: {answer.Source}");
        Console.WriteLine();
    }
}

Orchestration Project - Luis Prediction

string respondingProjectName = orchestratorPrediction.TopIntent;
TargetIntentResult targetIntentResult = orchestratorPrediction.Intents[respondingProjectName];

if (targetIntentResult.TargetKind == TargetKind.Luis)
{
    LuisTargetIntentResult luisTargetIntentResult = targetIntentResult as LuisTargetIntentResult;
    BinaryData luisResponse = luisTargetIntentResult.Result;

    Console.WriteLine($"LUIS Response: {luisResponse.ToString()}");
}

Troubleshooting

General

When you interact with the Cognitive Language Services Conversations client library using the .NET SDK, errors returned by the service correspond to the same HTTP status codes returned for REST API requests.

For example, if you submit a utterance to a non-existant project, a 400 error is returned indicating "Bad Request".

try
{
    ConversationsProject conversationsProject = new ConversationsProject("invalid-project", "production");
    Response<AnalyzeConversationTaskResult> response = client.AnalyzeConversation(
        "Send an email to Carol about the tomorrow's demo",
        conversationsProject);
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

You will notice that additional information is logged, like the client request ID of the operation.

Azure.RequestFailedException: The input parameter is invalid.
Status: 400 (Bad Request)
ErrorCode: InvalidArgument

Content:
{
  "error": {
    "code": "InvalidArgument",
    "message": "The input parameter is invalid.",
    "innerError": {
      "code": "InvalidArgument",
      "message": "The input parameter \"payload\" cannot be null or empty."
    }
  }
}

Headers:
Transfer-Encoding: chunked
pragma: no-cache
request-id: 0303b4d0-0954-459f-8a3d-1be6819745b5
apim-request-id: 0303b4d0-0954-459f-8a3d-1be6819745b5
x-envoy-upstream-service-time: 15
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
Cache-Control: no-store, proxy-revalidate, no-cache, max-age=0, private
Content-Type: application/json

Setting up console logging

The simplest way to see the logs is to enable console logging. To create an Azure SDK log listener that outputs messages to the console use the AzureEventSourceListener.CreateConsoleLogger method.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

To learn more about other logging mechanisms see here.

Next steps

• View our samples.
• Read about the different features of the Conversations service.
• Try our service demos.

Contributing

See the CONTRIBUTING.md for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.