GovUK.Dfe.AI.Agents.Guardrails 0.0.1-prerelease.1665

GovUK.Dfe.AI.Agents.Guardrails

Makes sure every model deployment, or agent version, your GovUK.Dfe.AI.Agents agents use has an Azure AI Foundry guardrail. Foundry then blocks:

• harmful content (hate, sexual, violence, self-harm)
• jailbreak attempts
• instructions hidden in documents and tool output
• protected material

Set up

dotnet add package GovUK.Dfe.AI.Agents.Guardrails

"AiAgents": {
  "Guardrails": {
    "SubscriptionId": "<subscription id>",
    "ResourceGroup": "<resource group>",
    "Name": "briefing-guardrail",
    "Deployments": [ "gpt-5.1" ]
  }
}

builder.Services.AddAgents(builder.Configuration, agents => agents
    .AddAgents(BriefingAgents.All)
    .AddGuardrails());

Apply once, check everywhere

• Scope: both roles are on the Foundry resource, not the project: guardrails and deployments belong to the resource. Agents still need only Foundry User on the project.
• Infrastructure as code instead: create the guardrail in Bicep or Terraform and skip ApplyAsync; apps still check it, with only Reader.
• Missing or weakened: startup fails, saying what's wrong ("RequireAtStartup": false only warns).
• Resource Manager unreachable: startup warns, so an outage doesn't stop new instances ("FailWhenUnreachable": true fails instead).

Models through a connection

When Foundry:DefaultModel is <connection>/<model>, the deployments aren't in your Foundry resource, so put the guardrail on the agents:

"Guardrails": {
  "SubscriptionId": "<subscription id>",
  "ResourceGroup": "<resource group>",
  "Name": "briefing-guardrail",
  "Targets": "Agents"
}

• No Deployments; ApplyAsync creates or updates only the guardrail and blocklists.
• Every agent version the app creates gets the guardrail, by its full Resource Manager ID (it becomes Foundry:Guardrail).
• The startup check confirms each pinned or externally managed version has it, e.g. agent 'rsd-trust-agent' version 4 uses no guardrail. Fix by provisioning a new version.
• "Targets": "Deployments, Agents" does both.

Settings

Blocklists

Block your own terms, such as project code names or case reference formats:

"Blocklists": {
  "case-references": { "Terms": [ "Project Falcon" ], "Patterns": [ "CASE-\\d{6}" ] }
}

ApplyAsync creates each blocklist with exactly these entries, for prompts and answers. The startup check reports a blocklist that's detached or missing entries, by count only. Load sensitive terms from Key Vault, not appsettings.json.

When a guardrail blocks something

The run fails with an inner AgentGuardrailException (Stage: prompt, answer or evidence), counted by dfe.ai_agents.guardrail.blocks. In parallel and sequential runs, the agent gets a fallback result instead. Core reports blocks with or without this package.

Checking input in the app

A Foundry guardrail doesn't cover everything an agent is sent:

• Evidence passed in an agent's input is never scanned for planted instructions: Foundry only scans documents in Chat Completions requests and the output of its own tools (Azure AI Search, OpenAPI and others).
• A model behind your own gateway (an API Management connection) gets no Foundry guardrail at all: Microsoft leaves safety for those models to you (Bring your own model). The startup check can confirm the guardrail is on an agent version while nothing enforces it.

So the app can check each run's input itself, after redaction and before anything is sent. A match blocks the run like a guardrail block, with the reason in AgentGuardrailException.Reason:

• Identity: ScanPrompts and ScanEvidence need Cognitive Services User on the Foundry resource, at https://<resource>.cognitiveservices.azure.com/ (or ContentSafetyEndpoint).
• Cost: the two scans run side by side, about 100–200 ms for a typical run; blocklists cost nothing.
• Fails closed: if input can't be scanned, e.g. because the role is missing, the run fails rather than sending it.
• Release gate: test cases with "guardrailMustBlock": true prove each check works.
• Your own: register an IInputShield instead, for other checks.

Not included

PII filtering: Foundry's PII filter needs a preview API, and this package uses GA APIs only. If you need it, turn it on in the Foundry portal; the startup check leaves it alone.