Microsoft Purview Integration for Microsoft Agent Framework

Common errors

• ModuleNotFoundError: No module named 'agent_framework_purview'

  cause The 'agent_framework_purview' module is not installed or the installation is incomplete.
  fix Install the module using pip: 'pip install agent-framework-purview'.

• ImportError: cannot import name 'PurviewPolicyMiddleware' from 'agent_framework.microsoft'

  cause The 'PurviewPolicyMiddleware' class is not available in the 'agent_framework.microsoft' module, possibly due to an outdated version.
  fix Ensure you have the latest version of 'agent-framework-purview' installed: 'pip install --upgrade agent-framework-purview'.

• PurviewServiceError: 402 Payment Required - tenant lacks proper Purview licensing or consumptive billing setup

  cause The Microsoft Purview service requires appropriate licensing or billing setup, which is missing.
  fix Verify that your Azure subscription has the necessary Purview licensing and billing configurations.

• PurviewServiceError: 429 Too Many Requests - rate limit exceeded

  cause The application has exceeded the allowed number of requests to the Purview service within a given timeframe.
  fix Implement exponential backoff and retry logic to handle rate limiting, and ensure your application adheres to Purview's usage guidelines.

• PurviewServiceError: 401 Unauthorized - token acquisition/validation issues

  cause Authentication to the Purview service failed due to invalid or missing credentials.
  fix Ensure that your application is correctly configured with valid Azure credentials and that the necessary permissions are granted.

Warnings

• breaking This library is in beta (`1.x.x` versions starting with `b`). API surfaces, configuration options, and internal implementations are subject to change without strict adherence to semantic versioning until a stable `1.0.0` release.
  Fix: Monitor GitHub repository and PyPI for updates. Test thoroughly when upgrading between beta versions and before moving to production.
• gotcha Proper Azure authentication setup is crucial. `DefaultAzureCredential` relies on environment variables, Azure CLI login, Managed Identity, etc. Incorrect setup will lead to authentication errors.
  Fix: Ensure environment variables like `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` are correctly configured, or use `az login` (for CLI credential), or configure Managed Identity for Azure-hosted services. Refer to `azure-identity` documentation.
• gotcha This library is an extension of the `agent-framework` core library. It is not standalone and requires `agent-framework` to be installed and used for agent creation and processing.
  Fix: Ensure `agent-framework` is installed alongside `agent-framework-purview`. Understand the `AgentProcessor` patterns for creating and invoking agents.
• gotcha Most interactions with the Purview agent, including its initialization (`AgentProcessor.create_agent`) and invocation (`purview_agent.invoke`), are asynchronous. Users must use `async/await` and run their code within an `asyncio` event loop.
  Fix: Wrap your agent code in an `async` function and run it using `asyncio.run(your_async_function())`.
• gotcha The `PurviewAgentConfig` requires the `azure_purview_account_name` parameter to specify which Purview account to connect to. Failing to provide this will result in configuration errors or inability to connect.
  Fix: Provide the `azure_purview_account_name` in the `config` dictionary when calling `AgentProcessor.create_agent`, or ensure it's loaded from environment variables if the agent's internal configuration supports it.

Install

• pip install agent-framework-purview Install stable (beta) version

Imports

• PurviewAgent

  from agent_framework_purview.purview_agent import PurviewAgent

• AgentProcessor

  from agent_framework.core.processor import AgentProcessor

• DefaultAzureCredential

  from azure.identity.aio import DefaultAzureCredential

Quickstart

This quickstart demonstrates how to initialize the `PurviewAgent` and use it to interact with Azure Purview. It sets up `DefaultAzureCredential` for authentication and configures the agent with the Purview account name. It then invokes the agent to 'find assets' based on a query string. Ensure your Azure environment variables for authentication (e.g., `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`) and `AZURE_PURVIEW_ACCOUNT_NAME` are set.

import os
import asyncio
from agent_framework_purview.purview_agent import PurviewAgent
from agent_framework.core.processor import AgentProcessor
from azure.identity.aio import DefaultAzureCredential

async def main():
    # Ensure AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, etc., are set
    # for DefaultAzureCredential to authenticate. For local development, 
    # 'az login' or environment variables are common. For production, 
    # Managed Identity is recommended.
    credential = DefaultAzureCredential()

    # The Purview Agent requires the Azure Purview account name.
    # Replace 'your_purview_account_name' or set AZURE_PURVIEW_ACCOUNT_NAME env var.
    purview_account_name = os.environ.get(
        "AZURE_PURVIEW_ACCOUNT_NAME", "your_purview_account_name"
    )
    if purview_account_name == "your_purview_account_name":
        print("WARNING: Please set AZURE_PURVIEW_ACCOUNT_NAME environment variable or update the code.")
        return

    purview_agent_config = {
        "azure_purview_account_name": purview_account_name,
        "purview_scope": ["https://purview.azure.net/.default"], # Standard scope
    }

    try:
        purview_agent: PurviewAgent = await AgentProcessor.create_agent(
            PurviewAgent,
            credential=credential,
            config=purview_agent_config
        )

        print(f"Agent created for Purview account: {purview_account_name}")

        # Example invocation: find assets matching a query string
        print("Invoking agent to find assets...")
        response = await purview_agent.invoke(
            "find assets",
            query_string="Sales Data"
        )

        print("\n--- Purview Agent Response ---")
        print(f"Content: {response.content}")
        if response.citations:
            print(f"Citations: {response.citations}")
        else:
            print("No citations found.")

    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        await credential.close()

if __name__ == "__main__":
    asyncio.run(main())