Add Microsoft Purview DLP real-time protection on agent-hooks

CHANGELOG.md

@@ -84,6 +84,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   cannot be verified (no verdict, no agent identity, or an allow of truncated content) follow the
   fail mode. Requires Node.js 20 or later.
 
+### Added (`@microsoft/agents-a365-tooling`, Purview)
+
+- **Microsoft Purview data loss prevention client (opt-in)** - `PurviewDlpClient.evaluate` sends
+  the text of a prompt (`uploadText`) or a reply (`downloadText`) to the Microsoft Graph
+  `processContent` API (`/me/dataSecurityAndGovernance/processContent`, or `/users/{id}/...`), which
+  applies the tenant's DLP policies for the agent's application and records the interaction for
+  audit. A policy action with `restrictionAction: block` or `action: blockAccess` blocks the content; other actions allow it
+  and are counted. The request is one conversation message with a non-empty name, the conversation's
+  `correlationId` and `sequenceNumber`, the agent (`agents[0]` with its blueprint) and the blueprint's
+  application id as the `applicationLocation`; every call sends a new `client-request-id`.
+- `PurviewDlpTokenResolvers.fromAgenticUser` uses the agentic user's delegated Microsoft Graph token
+  from the Agents SDK connection (`getAgenticUserToken`, needs `Content.Process.User`), cached per
+  tenant, agent, agentic user and scope; `fromAccessTokenProvider` uses a host's token, for `/me` or
+  for a named user. The Graph base URL must be `https`, and the request does not follow a redirect.
+- Processing errors (reported with HTTP 200), non-2xx statuses, timeouts, transport errors and
+  responses of another shape follow `A365_PURVIEW_DLP_FAIL_MODE` (fail open by default); errors name
+  the failure or exception type only, never a response body or token. Text longer than
+  `A365_PURVIEW_DLP_MAX_CONTENT_CHARACTERS` (default 100000) is sent with `isTruncated: true`, and
+  Purview's allow of it follows the fail mode. `protectionScopes/compute` is not used.
+- Configured with `ENABLE_A365_PURVIEW_DLP`, `A365_PURVIEW_DLP_GRAPH_BASE_URL` (default
+  `https://graph.microsoft.com/v1.0`), `A365_PURVIEW_DLP_AUTHENTICATION_SCOPE`,
+  `A365_PURVIEW_DLP_FAIL_MODE`, `A365_PURVIEW_DLP_TIMEOUT_MILLISECONDS` (default 10000),
+  `A365_PURVIEW_DLP_MAX_CONTENT_CHARACTERS` and `A365_PURVIEW_DLP_RESPONSE_MODE` (`audit` or
+  `enforce`, default `audit`), or the matching `ToolingConfiguration` overrides; unknown values of
+  the enable flag and the modes, and number settings that are not whole numbers, are rejected. No new
+  dependency.
+
+### Added (`@microsoft/agents-a365-tooling-extensions-agenthooks`, Purview)
+
+- **`A365PurviewInterceptor`** - An agent-hooks interceptor that evaluates the user's message at
+  `input` (`uploadText`, a block denies it with `purview:block`) and the reply at `output`
+  (`downloadText`: sent in the background and allowed at once in the default `audit` mode, awaited
+  in `enforce` mode), with a callback for each evaluation; `addA365Purview` registers it next to
+  `A365DefenderInterceptor` on one emitter. Contexts that cannot be verified follow the fail mode.
+  Structured content is read lazily within bounds, and content read only in part is evaluated as
+  truncated. `createProtectionEmitter` accepts `purviewConfigProvider`, and its default interceptor timeout
+  covers the Purview timeout when Purview DLP is enabled; Defender-only emitters are unchanged.
+
 ## [1.0.0] - 2026-04-30
 
 ### Breaking Changes (`@microsoft/agents-a365-tooling`)

CLAUDE.md

@@ -83,8 +83,8 @@ packages/
 ├── agents-a365-observability-extensions-langchain/  # LangChain instrumentation
 ├── agents-a365-observability-extensions-openai/  # OpenAI instrumentation
 ├── agents-a365-notifications/              # Agent notification services
-├── agents-a365-tooling/                    # MCP server configuration, Defender RTP client
-├── agents-a365-tooling-extensions-agenthooks/  # agent-hooks interceptor for Defender RTP
+├── agents-a365-tooling/                    # MCP server configuration, Defender RTP and Purview DLP clients
+├── agents-a365-tooling-extensions-agenthooks/  # agent-hooks interceptors for Defender RTP and Purview DLP
 ├── agents-a365-tooling-extensions-claude/  # Claude/Anthropic integration
 ├── agents-a365-tooling-extensions-langchain/  # LangChain integration
 └── agents-a365-tooling-extensions-openai/  # OpenAI Agents SDK integration
@@ -177,6 +177,7 @@ MCP tool server discovery and configuration:
 - **`Utility`**: Header composition, token validation, URL construction
 - **Interfaces**: `MCPServerConfig`, `McpClientTool`, `ToolOptions`
 - **`DefenderRtpClient`**: Microsoft Defender for AI real-time protection (opt-in, `ENABLE_A365_DEFENDER_RTP`). `evaluateHookContext` sends a copy of an agent-hooks/0.1 context, fitted to Defender's request validation, to the Defender prevention endpoint at `input`, `pre_tool_call`, `post_tool_call` and `output`, with the agent identity's app-only token (`DefenderRtpTokenResolvers.fromAgenticConnection`) and a unique `x-ms-correlation-id`, and returns the verdict; failures follow `A365_DEFENDER_RTP_FAIL_MODE`. No agent-hooks dependency: `A365DefenderInterceptor` in `agents-a365-tooling-extensions-agenthooks` drives it from an agent-hooks emitter.
+- **`PurviewDlpClient`**: Microsoft Purview data loss prevention (opt-in, `ENABLE_A365_PURVIEW_DLP`). `evaluate` sends the text of a prompt (`uploadText`) or reply (`downloadText`) to Microsoft Graph `processContent` with the agentic user's delegated token (`PurviewDlpTokenResolvers.fromAgenticUser`, `/me`) or a host token (`fromAccessTokenProvider`) and a new `client-request-id`; a `restrictionAction: block` (or `action: blockAccess`) policy action blocks, and failures (including inline `processingErrors`) follow `A365_PURVIEW_DLP_FAIL_MODE`. `A365PurviewInterceptor` in `agents-a365-tooling-extensions-agenthooks` drives it at `input` and `output` (replies audited in the background by default, `A365_PURVIEW_DLP_RESPONSE_MODE`).
 
 ### Notifications (`@microsoft/agents-a365-notifications`)
 Extends `AgentApplication` with notification handlers via declaration merging:
@@ -216,9 +217,16 @@ The keyword "Kairo" is legacy and should not appear in any code. Flag and remove
 | `ENABLE_A365_DEFENDER_RTP` | Enable Defender real-time protection (`DefenderRtpClient`) | `true`, `false` (default); also 1/0, yes/no, on/off; other values are rejected |
 | `A365_DEFENDER_RTP_ENDPOINT` | Defender prevention endpoint (required when enabled) | URL string |
 | `A365_DEFENDER_RTP_FAIL_MODE` | Behavior when no Defender verdict is obtained | `open` (default), `closed`; other values are rejected |
-| `A365_DEFENDER_RTP_TIMEOUT_MILLISECONDS` | Timeout of each Defender evaluation | Number (default: 10000, at most 2147481647) |
+| `A365_DEFENDER_RTP_TIMEOUT_MILLISECONDS` | Timeout of each Defender evaluation | Whole number (default: 10000, at most 2147481647); other values are rejected |
 | `A365_DEFENDER_RTP_AUTHENTICATION_SCOPE` | Override the Defender API token scope | Scope string |
-| `A365_DEFENDER_RTP_MAX_CONTENT_CHARACTERS` | Max characters of each content string sent to Defender; the request carries at most four times as much content | Number (default: 20000) |
+| `A365_DEFENDER_RTP_MAX_CONTENT_CHARACTERS` | Max characters of each content string sent to Defender; the request carries at most four times as much content | Whole number (default: 20000, at most 2147483647); other values are rejected |
+| `ENABLE_A365_PURVIEW_DLP` | Enable Purview data loss prevention (`PurviewDlpClient`) | `true`, `false` (default); also 1/0, yes/no, on/off; other values are rejected |
+| `A365_PURVIEW_DLP_GRAPH_BASE_URL` | Microsoft Graph base URL of `processContent` | https URL (default: `https://graph.microsoft.com/v1.0`) |
+| `A365_PURVIEW_DLP_AUTHENTICATION_SCOPE` | Override the Microsoft Graph token scope | Scope string (default: `https://graph.microsoft.com/.default`) |
+| `A365_PURVIEW_DLP_FAIL_MODE` | Behavior when no Purview verdict is obtained | `open` (default), `closed`; other values are rejected |
+| `A365_PURVIEW_DLP_TIMEOUT_MILLISECONDS` | Timeout of each Purview evaluation | Whole number (default: 10000, at most 2147481647); other values are rejected |
+| `A365_PURVIEW_DLP_MAX_CONTENT_CHARACTERS` | Max characters of text sent to Purview; longer text is sent truncated and follows the fail mode unless blocked | Whole number (default: 100000, at most 2147483647); other values are rejected |
+| `A365_PURVIEW_DLP_RESPONSE_MODE` | How replies are handled | `audit` (default, never blocked), `enforce`; other values are rejected |
 | `A365_OBSERVABILITY_SCOPES_OVERRIDE` | Override observability auth scopes | Space-separated scope strings |
 | `ENABLE_A365_OBSERVABILITY_EXPORTER` | Enable Agent365 exporter | `true`, `false` (default) |
 | `ENABLE_A365_OBSERVABILITY_PER_REQUEST_EXPORT` | Enable per-request export mode | `true`, `false` (default) |

README.md

@@ -76,7 +76,7 @@ For more detailed build instructions, see the [HOW_TO_BUILD.md](HOW_TO_BUILD.md)
 - **packages/agents-a365-observability-extensions-openai**: OpenAI observability extensions
 - **packages/agents-a365-runtime**: Microsoft Agent 365 Runtime - Core runtime utilities and extensions
 - **packages/agents-a365-tooling**: Microsoft Agent 365 Tooling SDK - Agent tooling and MCP integration
-- **packages/agents-a365-tooling-extensions-agenthooks**: agent-hooks interceptor for Microsoft Defender for AI real-time protection
+- **packages/agents-a365-tooling-extensions-agenthooks**: agent-hooks interceptors for Microsoft Defender for AI real-time protection and Microsoft Purview data loss prevention
 - **packages/agents-a365-tooling-extensions-claude**: Claude/Anthropic tooling extensions
 - **packages/agents-a365-tooling-extensions-langchain**: LangChain tooling extensions
 - **packages/agents-a365-tooling-extensions-openai**: OpenAI tooling extensions

docs/design.md

@@ -186,7 +186,7 @@ Framework-specific instrumentations that integrate with the observability core:
 
 > **Detailed documentation**: [packages/agents-a365-tooling/docs/design.md](../packages/agents-a365-tooling/docs/design.md)
 
-MCP (Model Context Protocol) tool server configuration and discovery, and the Microsoft Defender for AI real-time protection client.
+MCP (Model Context Protocol) tool server configuration and discovery, the Microsoft Defender for AI real-time protection client, and the Microsoft Purview data loss prevention client.
 
 **Key Classes:**
 
@@ -196,6 +196,8 @@ MCP (Model Context Protocol) tool server configuration and discovery, and the Mi
 | `Utility` | Header composition, token validation, URL construction |
 | `DefenderRtpClient` | Send agent-hooks contexts to the Defender prevention endpoint and return its verdict (opt-in, `ENABLE_A365_DEFENDER_RTP`) |
 | `DefenderRtpTokenResolvers` | The agent identity's app-only Defender token from an Agents SDK connection |
+| `PurviewDlpClient` | Send prompt and reply text to Microsoft Purview DLP (Graph `processContent`) and return whether it may proceed (opt-in, `ENABLE_A365_PURVIEW_DLP`) |
+| `PurviewDlpTokenResolvers` | The agentic user's delegated Microsoft Graph token from an Agents SDK connection, or a host's token |
 
 **Interfaces:**
 
@@ -247,7 +249,7 @@ Framework-specific adapters for MCP tool integration, and the agent-hooks adapte
 
 | Package | Purpose | Design Doc |
 |---------|---------|------------|
-| `tooling-extensions-agenthooks` | agent-hooks interceptor for Microsoft Defender for AI real-time protection | [design.md](../packages/agents-a365-tooling-extensions-agenthooks/docs/design.md) |
+| `tooling-extensions-agenthooks` | agent-hooks interceptors for Microsoft Defender for AI real-time protection and Microsoft Purview data loss prevention | [design.md](../packages/agents-a365-tooling-extensions-agenthooks/docs/design.md) |
 | `tooling-extensions-claude` | Claude SDK integration | [design.md](../packages/agents-a365-tooling-extensions-claude/docs/design.md) |
 | `tooling-extensions-langchain` | LangChain integration | [design.md](../packages/agents-a365-tooling-extensions-langchain/docs/design.md) |
 | `tooling-extensions-openai` | OpenAI Agents SDK integration | [design.md](../packages/agents-a365-tooling-extensions-openai/docs/design.md) |