agent-framework-purview 1.0.0b260521

Meta

• License: MIT License
• Author: Microsoft
• Requires: Python >=3.10

Classifiers

• Development Status
  • 4 - Beta
• Framework
  • Pydantic :: 2
• Intended Audience
  • Developers
• License
  • OSI Approved :: MIT License
• Programming Language
  • Python :: 3
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13
  • Python :: 3.14
• Typing
  • Typed

Microsoft Agent Framework – Purview Integration (Python)

agent-framework-purview adds Microsoft Purview (Microsoft Graph dataSecurityAndGovernance) policy evaluation to the Microsoft Agent Framework. It lets you enforce data security / governance policies on both the prompt (user input + conversation history) and the model response before they proceed further in your workflow.

Status: Preview

Key Features

• Middleware-based policy enforcement (agent-level and chat-client level)
• Blocks or allows content at both ingress (prompt) and egress (response)
• Works with any Agent / agent orchestration using the standard Agent Framework middleware pipeline
• Supports both synchronous TokenCredential and AsyncTokenCredential from azure-identity
• Configuration via PurviewSettings / PurviewAppLocation
• Built-in caching with configurable TTL and size limits for protection scopes in PurviewSettings
• Background processing for content activities and offline policy evaluation

When to Use

Add Purview when you need to:

• Prevent sensitive data leaks: Inline blocking of sensitive content based on Data Loss Prevention (DLP) policies.
• Enable governance: Log AI interactions in Purview for Audit, Communication Compliance, Insider Risk Management, eDiscovery, and Data Lifecycle Management.
• Prevent sensitive or disallowed content from being sent to an LLM
• Prevent model output containing disallowed data from leaving the system
• Apply centrally managed policies without rewriting agent logic

---

Prerequisites

• Microsoft Azure subscription with Microsoft Purview configured.
• Microsoft 365 subscription with an E5 license and pay-as-you-go billing setup.
  • For testing, you can use a Microsoft 365 Developer Program tenant. For more information, see Join the Microsoft 365 Developer Program.

Authentication

PurviewClient uses the azure-identity library for token acquisition. You can use any TokenCredential or AsyncTokenCredential implementation.

• Entra registration: Register your agent and add the required Microsoft Graph permissions (dataSecurityAndGovernance) to the Service Principal. For more information, see Register an application in Microsoft Entra ID and dataSecurityAndGovernance resource type. You'll need the Microsoft Entra app ID in the next step.

• Graph Permissions:

• ProtectionScopes.Compute.All : userProtectionScopeContainer

• Content.Process.All : processContent

• ContentActivity.Write : contentActivity

• Purview policies: Configure Purview policies using the Microsoft Entra app ID to enable agent communications data to flow into Purview. For more information, see Configure Microsoft Purview.

Scopes

PurviewSettings.get_scopes() derives the Graph scope list (currently https://graph.microsoft.com/.default style).

---

Quick Start

importasyncio
fromagent_frameworkimport Agent, Message, Role
fromagent_framework.openaiimport OpenAIChatCompletionClient
fromagent_framework.microsoftimport PurviewPolicyMiddleware, PurviewSettings
fromazure.identityimport InteractiveBrowserCredential

async defmain():
	client = OpenAIChatCompletionClient() # uses environment for endpoint + deployment

	purview_middleware = PurviewPolicyMiddleware(
		credential=InteractiveBrowserCredential(),
		settings=PurviewSettings(app_name="My Sample App")
	)

	agent = Agent(
		client=client,
		instructions="You are a helpful assistant.",
		middleware=[purview_middleware]
	)

	response = await agent.run(Message("user", ["Summarize zero trust in one sentence."]))
	print(response)

asyncio.run(main())

If a policy violation is detected on the prompt, the middleware terminates the run and substitutes a system message: "Prompt blocked by policy". If on the response, the result becomes "Response blocked by policy".

---

Configuration

PurviewSettings

PurviewSettings(
 app_name="My App", # Required: Display / logical name
 app_version=None, # Optional: Version string of the application
 tenant_id=None, # Optional: Tenant id (guid), used mainly for auth context
 purview_app_location=None, # Optional: PurviewAppLocation for scoping
 graph_base_uri="https://graph.microsoft.com/v1.0/",
 blocked_prompt_message="Prompt blocked by policy", # Custom message for blocked prompts
 blocked_response_message="Response blocked by policy", # Custom message for blocked responses
 ignore_exceptions=False, # If True, non-payment exceptions are logged but not thrown
 ignore_payment_required=False, # If True, 402 payment required errors are logged but not thrown
 cache_ttl_seconds=14400, # Cache TTL in seconds (default 4 hours)
 max_cache_size_bytes=200 * 1024 * 1024 # Max cache size in bytes (default 200MB)
)

Caching

The Purview integration includes built-in caching for protection scopes responses to improve performance and reduce API calls:

• Default TTL: 4 hours (14400 seconds)
• Default Cache Size: 200MB
• Cache Provider: InMemoryCacheProvider is used by default, but you can provide a custom implementation via the CacheProvider protocol
• Cache Invalidation: Cache is automatically invalidated when protection scope state is modified
• Exception Caching: 402 Payment Required errors are cached to avoid repeated failed API calls

You can customize caching behavior in PurviewSettings:

fromagent_framework.microsoftimport PurviewSettings

settings = PurviewSettings(
 app_name="My App",
 cache_ttl_seconds=14400, # 4 hours
 max_cache_size_bytes=200 * 1024 * 1024 # 200MB
)

Or provide your own cache provider:

fromtypingimport Any
fromagent_framework.microsoftimport PurviewPolicyMiddleware, PurviewSettings, CacheProvider
fromazure.identityimport DefaultAzureCredential

classMyCustomCache(CacheProvider):
 async defget(self, key: str) -> Any | None:
 # Your implementation
 pass

 async defset(self, key: str, value: Any, ttl_seconds: int | None = None) -> None:
 # Your implementation
 pass

 async defremove(self, key: str) -> None:
 # Your implementation
 pass

credential = DefaultAzureCredential()
settings = PurviewSettings(app_name="MyApp")

middleware = PurviewPolicyMiddleware(
 credential=credential,
 settings=settings,
 cache_provider=MyCustomCache()
)

To scope evaluation by location (application, URL, or domain):

fromagent_framework.microsoftimport (
	PurviewAppLocation,
	PurviewLocationType,
	PurviewSettings,
)

settings = PurviewSettings(
	app_name="Contoso Support",
	purview_app_location=PurviewAppLocation(
		location_type=PurviewLocationType.APPLICATION,
		location_value="<app-client-id>"
	)
)

Customizing Blocked Messages

By default, when Purview blocks a prompt or response, the middleware returns a generic system message. You can customize these messages by providing your own text in the PurviewSettings:

fromagent_framework.microsoftimport PurviewSettings

settings = PurviewSettings(
	app_name="My App",
	blocked_prompt_message="Your request contains content that violates our policies. Please rephrase and try again.",
	blocked_response_message="The response was blocked due to policy restrictions. Please contact support if you need assistance."
)

Exception Handling Controls

The Purview integration provides fine-grained control over exception handling to support graceful degradation scenarios:

fromagent_framework.microsoftimport PurviewSettings

# Ignore all non-payment exceptions (continue execution even if policy check fails)
settings = PurviewSettings(
 app_name="My App",
 ignore_exceptions=True # Log errors but don't throw
)

# Ignore only 402 Payment Required errors (useful for tenants without proper licensing)
settings = PurviewSettings(
 app_name="My App",
 ignore_payment_required=True # Continue even without Purview Consumptive Billing Setup
)

# Both can be combined
settings = PurviewSettings(
 app_name="My App",
 ignore_exceptions=True,
 ignore_payment_required=True
)

Selecting Agent vs Chat Middleware

Use the agent middleware when you already have / want the full agent pipeline:

fromagent_frameworkimport Agent
fromagent_framework.openaiimport OpenAIChatCompletionClient
fromagent_framework.microsoftimport PurviewPolicyMiddleware, PurviewSettings
fromazure.identityimport DefaultAzureCredential

credential = DefaultAzureCredential()
client = OpenAIChatCompletionClient()

agent = Agent(
	client=client,
	instructions="You are helpful.",
	middleware=[PurviewPolicyMiddleware(credential, PurviewSettings(app_name="My App"))]
)

Use the chat middleware when you attach directly to a chat client (e.g. minimal agent shell or custom orchestration):

importos
fromagent_frameworkimport Agent
fromagent_framework.openaiimport OpenAIChatCompletionClient
fromagent_framework.microsoftimport PurviewChatPolicyMiddleware, PurviewSettings
fromazure.identityimport DefaultAzureCredential

credential = DefaultAzureCredential()

client = OpenAIChatCompletionClient(
	model=os.environ["AZURE_OPENAI_MODEL"],
	azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
	credential=credential,
	middleware=[
		PurviewChatPolicyMiddleware(credential, PurviewSettings(app_name="My App (Chat)"))
	],
)

agent = Agent(client=client, instructions="You are helpful.")

The policy logic is identical; the difference is only the hook point in the pipeline.

---

Middleware Lifecycle

1. Before agent execution (prompt phase): all context.messages are evaluated.
   • If no valid user_id is found, processing is skipped (no policy evaluation)
   • Protection scopes are retrieved (with caching)
   • Applicable scopes are checked to determine execution mode
   • In inline mode: content is evaluated immediately
   • In offline mode: evaluation is queued in background
2. If blocked: context.result is replaced with a system message and context.terminate = True.
3. After successful agent execution (response phase): the produced messages are evaluated using the same user_id from the prompt phase.
4. If blocked: result messages are replaced with a blocking notice.

The user identifier is discovered from Message.additional_properties['user_id'] during the prompt phase and reused for the response phase, ensuring both evaluations map consistently to the same user. If no user_id is present, policy evaluation is skipped entirely.

You can customize the blocking messages using the blocked_prompt_message and blocked_response_message fields in PurviewSettings. For more advanced scenarios, you can wrap the middleware or post-process context.result in later middleware.

---

Exceptions

Exception	Scenario
PurviewPaymentRequiredError	402 Payment Required - tenant lacks proper Purview licensing or consumptive billing setup
PurviewAuthenticationError	Token acquisition / validation issues
PurviewRateLimitError	429 responses from service
PurviewRequestError	4xx client errors (bad input, unauthorized, forbidden)
PurviewServiceError	5xx or unexpected service errors

Exception Handling

All exceptions inherit from PurviewServiceError. You can catch specific exceptions or use the base class:

fromagent_framework.microsoftimport (
 PurviewPaymentRequiredError,
 PurviewAuthenticationError,
 PurviewRateLimitError,
 PurviewRequestError,
 PurviewServiceError
)

try:
 # Your code here
 pass
except PurviewPaymentRequiredError as ex:
 # Handle licensing issues specifically
 print(f"Purview licensing required: {ex}")
except (PurviewAuthenticationError, PurviewRateLimitError, PurviewRequestError, PurviewServiceError) as ex:
 # Handle other errors
 print(f"Purview enforcement skipped: {ex}")

---

Notes

• User Identification: Provide a user_id per request (e.g. in Message(..., additional_properties={"user_id": "<guid>"})) for per-user policy scoping. If no user_id is provided, policy evaluation is skipped entirely.
• Blocking Messages: Can be customized via blocked_prompt_message and blocked_response_message in PurviewSettings. By default, they are "Prompt blocked by policy" and "Response blocked by policy" respectively.
• Streaming Responses: Post-response policy evaluation presently applies only to non-streaming chat responses.
• Error Handling: Use ignore_exceptions and ignore_payment_required settings for graceful degradation. When enabled, errors are logged but don't fail the request.
• Caching: Protection scopes responses and 402 errors are cached by default with a 4-hour TTL. Cache is automatically invalidated when protection scope state changes.
• Background Processing: Content Activities and offline Process Content requests are handled asynchronously using background tasks to avoid blocking the main execution flow.

Verified details

These details have been verified by PyPI

Maintainers

👁 Avatar for edvan_msft from gravatar.com
edvan_msft 👁 Avatar for gilesodigwe from gravatar.com
gilesodigwe 👁 Avatar for microsoft from gravatar.com
microsoft 👁 Avatar for moonbox3 from gravatar.com
moonbox3

Unverified details

These details have not been verified by PyPI

Project links

• homepage
• issues
• release_notes
• source

• Download URL: agent_framework_purview-1.0.0b260521.tar.gz
• Upload date: May 22, 2026
• Size: 27.9 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: uv/0.11.6 {"installer":{"name":"uv","version":"0.11.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Hashes for agent_framework_purview-1.0.0b260521.tar.gz

Algorithm	Hash digest
SHA256	d7aa309c1a22e15e71a6317b2ae261257fe7df01741ee0b9e6d363390bfea66d
MD5	f8171c53b40bdcf7824e960d83c78a80
BLAKE2b-256	50b613e4339f683e910c3332dceb35dbbf46e2acf65588e0ac0c0bc5009772d0

See more details on using hashes here.

• Download URL: agent_framework_purview-1.0.0b260521-py3-none-any.whl
• Upload date: May 22, 2026
• Size: 27.3 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? No
• Uploaded via: uv/0.11.6 {"installer":{"name":"uv","version":"0.11.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Hashes for agent_framework_purview-1.0.0b260521-py3-none-any.whl

Algorithm	Hash digest
SHA256	36f6226158560f1c667b6c7d6e0ca5faa15f0b2bc050e3ce5aaeb519443f659c
MD5	e11713734ac17ad7761fafb4527ed3f3
BLAKE2b-256	aff8d83fd884ef9b0b9e9a7799b6f6c8b60af63c8cfa467dd85bacaa17e5e107

See more details on using hashes here.