azure-ai-discovery 1.0.0

Microsoft Corporation Azure AI Discovery Client Library for Python

Azure AI Discovery client library for Python

The Azure AI Discovery client library for Python provides two clients for interacting with Azure AI Discovery services:

• WorkspaceClient — manage investigations, conversations, tasks, and tools in a Discovery workspace.
• BookshelfClient — manage knowledge bases, including indexing and search.

Source code | Package (PyPI) | Samples

Getting started

Install the Package

python -m pip install azure-ai-discovery

Prerequisites

• Python 3.9 or later is required to use this package.
• You need an Azure subscription to use this package.
• An existing Azure AI Discovery workspace or bookshelf instance.

Authenticate the Client

Both clients use Azure Active Directory (AAD) token authentication. Use the azure-identity library to obtain credentials:

pip install azure-identity

from azure.ai.discovery import WorkspaceClient, BookshelfClient
from azure.identity import DefaultAzureCredential

workspace_client = WorkspaceClient(
    endpoint="https://<workspaceName>.workspace.discovery.azure.com",
    credential=DefaultAzureCredential(),
)

bookshelf_client = BookshelfClient(
    endpoint="https://<bookshelfName>.bookshelf.discovery.azure.com",
    credential=DefaultAzureCredential(),
)

Key concepts

WorkspaceClient

The WorkspaceClient provides access to Discovery workspace operations, organized into four operation groups:

• Investigations — create and manage research investigations within a project. Each investigation can have a Discovery Engine that autonomously explores data and generates insights.
• Conversations — interact with the Discovery Engine through conversational sessions tied to an investigation.
• Tasks — create, assign, and track units of work within an investigation, such as research steps or follow-up actions.
• Tools — run compute jobs on supercomputer node pools and monitor their status and resource usage.

BookshelfClient

The BookshelfClient provides access to knowledge base management:

• Knowledge Bases — create, update, get, list, and delete knowledge bases backed by storage assets, run indexing as a long-running operation, and execute long-running search queries.

Examples

The following sections provide code snippets covering common scenarios. For complete runnable samples, see the Samples directory.

Create and Manage an Investigation

from azure.ai.discovery import WorkspaceClient
from azure.ai.discovery.models import Investigation
from azure.identity import DefaultAzureCredential

client = WorkspaceClient(
    endpoint="https://<workspaceName>.workspace.discovery.azure.com",
    credential=DefaultAzureCredential(),
)

# Create an investigation
investigation = client.investigations.create_or_replace(
    project_name="my-project",
    investigation_name="sample-investigation",
    resource=Investigation(
        description="Investigating anomalies in dataset X",
        display_name="Sample Investigation",
    ),
)
print(f"Created investigation: {investigation.name}")

# Start the Discovery Engine
engine = client.investigations.start_discovery_engine(
    project_name="my-project",
    investigation_name="sample-investigation",
)
print(f"Discovery Engine status: {engine.discovery_engine_status}")

Create and Manage Tasks

from azure.ai.discovery import WorkspaceClient
from azure.ai.discovery.models import Task, TaskAssignee, TaskComment
from azure.identity import DefaultAzureCredential

client = WorkspaceClient(
    endpoint="https://<workspaceName>.workspace.discovery.azure.com",
    credential=DefaultAzureCredential(),
)

# Create a task
task = client.tasks.create(
    project_name="my-project",
    investigation_name="sample-investigation",
    body=Task(
        title="Analyze compound interactions",
        priority="High",
        description="Review the interaction data for compounds A and B",
        assigned_to=TaskAssignee(id="researcher-agent", type="Application"),
        investigation_id="/projects/my-project/investigations/sample-investigation",
    ),
)
print(f"Created task: {task.title} ({task.status})")

# Add a comment
client.tasks.add_comment(
    project_name="my-project",
    investigation_name="sample-investigation",
    task_name=task.name,
    body=TaskComment(
            created_by="sample-user",
            created_by_type="User",
            text="Initial analysis shows promising results.",
        ),
)

Run a Tool on Compute

from azure.ai.discovery import WorkspaceClient
from azure.identity import DefaultAzureCredential

client = WorkspaceClient(
    endpoint="https://<workspaceName>.workspace.discovery.azure.com",
    credential=DefaultAzureCredential(),
)

poller = client.tools.begin_run(
    project_name="my-project",
    tool_id="/subscriptions/.../tools/my-tool",
    node_pool_ids=["/subscriptions/.../nodePools/my-pool"],
    command='echo "Hello from Discovery"',
)
result = poller.result()
print(f"Run completed: {result.status}")

Manage Knowledge Bases

from azure.ai.discovery import BookshelfClient
from azure.ai.discovery.models import KnowledgeBase, SearchRequest, StorageAssetReference
from azure.identity import DefaultAzureCredential

client = BookshelfClient(
    endpoint="https://<bookshelfName>.bookshelf.discovery.azure.com",
    credential=DefaultAzureCredential(),
)

# List knowledge bases (ItemPaged — transparent paging)
for kb in client.knowledge_bases.list():
    print(f"Knowledge base: {kb.name}")

# Create or update a knowledge base (long-running)
poller = client.knowledge_bases.begin_create_or_update(
    knowledge_base_name="my-kb",
    resource=KnowledgeBase(
        description="Research data for compound analysis",
        copilot_instruction="Use this to query information about compound interactions.",
        storage_asset_references=[
            StorageAssetReference(
                id="/subscriptions/.../storageAssets/my-asset",
                user_assigned_identity="/subscriptions/.../userAssignedIdentities/my-id",
            ),
        ],
    ),
)
kb = poller.result()
print(f"Created knowledge base: {kb.name}")

# Run indexing (long-running)
client.knowledge_bases.begin_start_indexing(
    knowledge_base_name="my-kb",
    node_pool_id="/subscriptions/.../nodePools/my-pool",
    project_id="/subscriptions/.../projects/my-project",
).result()

# Search the knowledge base (long-running)
client.knowledge_bases.begin_search(
    knowledge_base_name="my-kb",
    body=SearchRequest(query="What are common drug interactions?"),
).result()

Troubleshooting

Logging

This library uses the standard logging library for logging. HTTP session information (URLs, headers, etc.) is logged at the DEBUG level.

Detailed DEBUG level logging, including request/response bodies and unredacted headers, can be enabled on a client with the logging_enable argument:

client = WorkspaceClient(
    endpoint="https://<workspaceName>.workspace.discovery.azure.com",
    credential=DefaultAzureCredential(),
    logging_enable=True,
)

Or on a single operation:

investigation = client.investigations.get(
    project_name="my-project",
    investigation_name="my-investigation",
    logging_enable=True,
)

General

Azure AI Discovery clients raise exceptions defined in azure-core. For example, if you try to get an investigation that does not exist, ResourceNotFoundError is raised:

from azure.core.exceptions import ResourceNotFoundError

try:
    client.investigations.get(
        project_name="my-project",
        investigation_name="nonexistent",
    )
except ResourceNotFoundError as e:
    print(f"Investigation not found: {e.message}")

Next steps

• Samples — runnable code examples for common scenarios.
• Azure AI Discovery documentation

Contributing

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 https://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 [e-mail] with any additional questions or comments.

Release History

1.0.0 (2026-07-25)

General availability release of azure-ai-discovery. API version 2026-06-01 is now the default for both WorkspaceClient and BookshelfClient.

Features Added

• Workspace:
  • New paged list response models: PagedConversation, PagedInvestigation.
  • New StorageMountProtocol enum for controlling storage mount protocols.
  • New tools.cancel_run_lro long-running cancellation flow (in addition to the existing immediate cancel_run).
  • Investigation update is now exposed via a documented sample.
• Bookshelf: knowledge-base surface is significantly redesigned around a single KnowledgeBasesOperations group that exposes the full lifecycle in one place:
  • Lifecycle: create_or_update, get, delete, plus get_operation_status for polling long-running operations.
  • Indexing: start_indexing and cancel_indexing, with results modeled via KnowledgeBaseIndexingOperationResponse, IndexingOperationResult, IndexingMetrics, and LastIndexingRun.
  • Search: new search operation taking SearchRequest and returning SearchResponse, including SearchResultItem with Citation and CitationType for citation-aware results.
  • LRO results: status responses now use KnowledgeBaseOperationResponse / KnowledgeBaseSearchOperationResponse; create/update returns the KnowledgeBase resource.
  • New enum KnowledgeBaseOperationType.

Breaking Changes

Note: these are breaking changes only relative to the 1.0.0b1 preview release. As a first stable (GA) release, 1.0.0 is the new compatibility baseline going forward.

• Bookshelf: the KnowledgeBaseVersionsOperations operation group is removed. Knowledge-base versioning has been folded into the unified KnowledgeBasesOperations group; callers using client.knowledge_base_versions.<method> must migrate to the equivalent method on client.knowledge_bases.
• Bookshelf: the models KnowledgeBaseOperationStatus and KnowledgeBaseVersion are removed. Operation-status payloads are now typed as KnowledgeBaseOperationResponse, KnowledgeBaseIndexingOperationResponse, or KnowledgeBaseSearchOperationResponse depending on the operation; create/update returns the KnowledgeBase resource.
• The preview API version 2026-02-01-preview is no longer listed as a supported value for the api_version kwarg. Both WorkspaceClient and BookshelfClient now default to 2026-06-01. Pinning to the removed preview value is not supported in the GA SDK.
• Workspace: the investigations long-running operation status model, previously generated as ResourceOperationStatusInvestigationInvestigationError, has been renamed to InvestigationOperationStatus. The payload is unchanged; only the model name differs.

Other Changes

• Regenerated against Azure/azure-rest-api-specs PR #42884 (commit fbe3c49c541a2932f4a4cb348fb0798988f4aca4).
• Development Status classifier flipped from 4 - Beta to 5 - Production/Stable.
• Emitter @azure-tools/typespec-python at 0.63.3; the four hand-written client _patch.py overrides that expose transport and api_version as explicit keyword-only parameters remain in place pending future emitter support.

1.0.0b1 (2026-05-16)

Initial beta release of the Azure AI Discovery client library for Python.

Features Added

• Added WorkspaceClient for managing Discovery workspace resources, with operation groups for:
  • investigations — create, list, get, and delete investigations, and start/stop/get/update the per-investigation Discovery Engine.
  • conversations — create, list, get, update, and delete conversations that interact with the Discovery Engine.
  • tasks — create, list (with $filter support), get, update, comment on, start, and delete tasks; record execution history.
  • tools — run tools on supercomputer node pools, monitor run status with log retrieval, cancel runs, and query compute usage.
• Added BookshelfClient for managing knowledge bases, with operation groups for:
  • knowledge_bases — list available knowledge bases.
  • knowledge_base_versions — create or update, get, list, delete, and retrieve the latest version of a knowledge base; start, cancel, and monitor indexing.
• Added shared model types under azure.ai.discovery.models covering investigations, conversations, tasks, tools, knowledge bases, and the Discovery Engine.