Azure AI Discovery client library for JavaScript - version 1.0.0

This package contains an isomorphic SDK (runs both in Node.js and in browsers) for the Azure AI Discovery service.

The library exposes two clients:

  • WorkspaceClient — work with conversations, investigations, tasks, and tools in a Discovery workspace.
  • BookshelfClient — manage and query knowledge bases in a Discovery bookshelf.

Each client targets its own service endpoint.

Key links:

Getting started

Currently supported environments

See our support policy for more details.

Prerequisites

Install the @azure/ai-discovery package

Install the Discovery client library for JavaScript with npm:

npm install @azure/ai-discovery

Create and authenticate the clients

To create a client object, you will need the service endpoint and a credential. The Azure AI Discovery clients use Microsoft Entra credentials to authenticate. WorkspaceClient and BookshelfClient each target their own endpoint, so create the client(s) you need with the corresponding endpoint. You can find the endpoints for your Discovery resources in the Azure Portal.

You can authenticate with Microsoft Entra ID using a credential from the @azure/identity library or an existing Microsoft Entra token.

To use the DefaultAzureCredential provider shown below, or other credential providers provided with the Azure SDK, please install the @azure/identity package:

npm install @azure/identity

You will also need to register a new Microsoft Entra application and grant access to Azure AI Discovery by assigning a suitable role to your service principal (note: roles such as "Owner" will not grant the necessary permissions).

For more information about how to create a Microsoft Entra application check out this guide.

Using Node.js and Node-like environments, you can use the DefaultAzureCredential class to authenticate the clients.

import { DefaultAzureCredential } from "@azure/identity";
import { WorkspaceClient, BookshelfClient } from "@azure/ai-discovery";

const credential = new DefaultAzureCredential();
// WorkspaceClient exposes conversations, investigations, tasks, and tools.
const workspaceClient = new WorkspaceClient("<workspace-endpoint>", credential);
// BookshelfClient exposes knowledge bases.
const bookshelfClient = new BookshelfClient("<bookshelf-endpoint>", credential);

For browser environments, use the InteractiveBrowserCredential from the @azure/identity package to authenticate.

import { InteractiveBrowserCredential } from "@azure/identity";
import { WorkspaceClient, BookshelfClient } from "@azure/ai-discovery";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const workspaceClient = new WorkspaceClient("<workspace-endpoint>", credential);
const bookshelfClient = new BookshelfClient("<bookshelf-endpoint>", credential);

JavaScript Bundle

To use this client library in the browser, first you need to use a bundler. For details on how to do this, please refer to our bundling documentation.

Key concepts

WorkspaceClient

WorkspaceClient provides access to Discovery workspace features: conversations, investigations, tasks, and tools. Explore the methods on this client to work with resources in a Discovery workspace.

BookshelfClient

BookshelfClient provides access to Discovery bookshelf features: managing and querying knowledge bases. Explore the methods on this client to work with knowledge bases in a Discovery bookshelf.

Examples

List knowledge bases

List the knowledge bases in a Discovery Bookshelf resource with BookshelfClient.

import { BookshelfClient } from "@azure/ai-discovery";
import { DefaultAzureCredential } from "@azure/identity";

const client = new BookshelfClient("<bookshelf-endpoint>", new DefaultAzureCredential());
for await (const knowledgeBase of client.knowledgeBases.list()) {
  console.log(knowledgeBase.name);
}

List tasks in an investigation

List the tasks that belong to an investigation with WorkspaceClient.

import { WorkspaceClient } from "@azure/ai-discovery";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WorkspaceClient("<workspace-endpoint>", new DefaultAzureCredential());
for await (const task of client.tasks.list("<project-name>", "<investigation-name>")) {
  console.log(task.name);
}

Troubleshooting

Logging

Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the AZURE_LOG_LEVEL environment variable to info. Alternatively, logging can be enabled at runtime by calling setLogLevel in the @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

For more detailed instructions on how to enable logs, you can look at the @azure/logger package docs.

Next steps

Have a look at the package samples folder, containing fully runnable code.

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

  • Last updated on