Hosted agent content safety overview

Content safety guardrails in Microsoft Foundry screen supported content at the hosted agent boundary. This article explains what a guardrail evaluates, how synchronous and deferred streaming differ, how guardrails affect latency, and what your application needs to handle.

This article covers content safety behavior. It doesn't cover network egress controls or replace authorization, data loss prevention, tool permissions, or human approval for consequential actions.

Important

Agent guardrails are in preview.

Guardrail application

Hosted agents can use guardrails at the model and agent layers. These layers protect different boundaries:

Layer	Content evaluated	Use this layer when
Model deployment	Prompts and completions sent through that model deployment	You need a policy for direct model calls
Hosted agent	Supported input, output, tool-call, and tool-response intervention points across the agent runtime	You need a policy at the agent boundary, including content that might not map to one model call

A hosted agent guardrail is optional. If the agent definition omits rai_config, the agent runs without a content safety guardrail at the hosted-agent boundary. If you include rai_config without rai_policy_name, the platform uses the account-scoped Microsoft.DefaultV2 policy. An agent-boundary policy is independent of any content filter that a model deployment applies to its own model calls.

Apply a guardrail at the agent boundary when you need a consistent policy for user input and final agent output. Apply controls at additional intervention points when your scenario requires them.

Intervention points

An agent guardrail can evaluate content at four intervention points:

Intervention point	Content evaluated	Expected behavior when blocking is enabled
User input	Content submitted to the hosted agent	Foundry blocks the request before the agent runs.
Tool call (preview)	The tool name, arguments, and content the agent proposes to send	Foundry doesn't execute the tool call. The agent stops until it receives another user input.
Tool response (preview)	Content returned by a supported tool before the agent consumes it	Foundry stops the agent and prevents the response from being saved to agent memory.
Output	Final content produced for your application	Foundry applies the policy using the configured streaming and protocol behavior.

Tool-call and tool-response controls apply only to supported tools. For the current list, see Intervention points.

Content safety guardrails don't determine whether an agent is authorized to call a tool or perform an action. Use tool permissions, managed identities, network controls, data controls, and human approval when your scenario requires them.

Scope and limitations

Agent guardrails apply to agents developed in Foundry Agent Service. They don't apply to other agents registered in the Foundry Control Plane. The guardrail system also doesn't process prompts and completions handled by audio transcription models.

Protocol configuration affects whether content is screened:

Protocol	Content safety behavior
Responses	Set the agent's RAI policy. Foundry knows the request and response shapes and locates the text to screen.
Invocations	Set the RAI policy and invocations moderation settings that identify text in your custom request and response shapes. Without those settings, the attached policy doesn't screen content.
Invocations WebSocket	Content safety moderation isn't available.

For the Invocations protocol, content can pass unscreened if the body can't be parsed as configured or the configured paths and stream selectors don't select text. Request and response size limits can also affect screening. For configuration requirements and current limits, see Add guardrails to a hosted agent.

Tool-call and tool-response controls work only with tools that support moderation. Availability can also vary by region and model. Verify both supported tools and tool availability for your agent.

Output streaming behavior

The hosted agent runtime supports two output-moderation modes. The mode is part of the Responsible AI policy attached to the agent.

Mode	Service behavior	Streaming behavior	Your responsibility
Default (synchronous prevention)	Foundry holds selected output for evaluation before release	Foundry buffers output while it waits for a moderation result, then releases approved content	Handle protocol-specific blocks and service errors
Asynchronous filter (deferred detection)	Foundry streams output while moderation runs	If a later result identifies a violation, the stream stops and returns a protocol-specific moderation signal	Handle content that the application already displayed or processed

Use Default mode when preventing unapproved content from reaching your users is more important than minimizing time to first text.

Use Asynchronous filter mode when streaming responsiveness is more important and your application can safely handle a violation after some content has already been released.

Default mode

Default mode uses synchronous prevention:

Foundry evaluates user input before the agent runs.
The agent begins producing output.
Foundry buffers enough output for the moderation service to evaluate it.
Foundry releases only the content covered by an approved result.
If the result identifies a violation, Foundry stops the response and returns a content-filter error.

For content selected for screening, this mode provides the strongest prevention boundary, but it can increase time to first visible text.

Asynchronous filter mode

Asynchronous filter mode uses deferred detection:

Foundry evaluates user input before the agent runs.
The agent begins producing output.
Foundry streams output while moderation continues.
If a later result identifies a violation, Foundry stops subsequent output and returns a moderation signal in the protocol's response format.
Your application handles any content already displayed, stored, or passed to another component.

Asynchronous filter mode reduces moderation-related buffering before first text, but it doesn't guarantee that every character already released was approved.

If your application uses this mode:

Treat streamed output as provisional until moderation completes.
Avoid using provisional output to perform consequential actions.
Stop processing when Foundry reports a violation.
Replace or remove content already displayed when required by the scenario.
Preserve the request ID, agent name and version, region, and event timestamps for investigation.

Latency

In Default mode, Foundry waits for the agent to generate enough content for evaluation, evaluates the buffered content, and then releases approved output. Your client might receive a connection or initial stream event before it receives visible text. You can think of the delay as:

Time to first visible text = content generation time + moderation processing time + buffering and release time

Actual latency depends on:

Enabled controls and intervention points.
Content length and the agent's output rate.
Region and available moderation capacity.
Retries, timeouts, and service failures.

Measure end-to-end time to first visible text with representative inputs for your agent, policy, and region. A model-only latency measurement doesn't represent the complete hosted agent guardrail path. For testing guidance, see Debug a hosted agent.

Hosted agent latency diagnostics don't report guardrail processing as a separate timing. Output-policy buffering is included in x-ms-debug-latency-container-response-ms with request transfer, connection setup, agent handling, and retries.

Asynchronous filter mode removes the synchronous moderation holdback and can reduce time to first visible text. In exchange, content can reach your application before a violation is available.

Blocks and errors

Block behavior depends on the intervention point, protocol, and response mode:

Scenario	Client-visible behavior
Blocked input for Responses or Invocations	Foundry returns HTTP 400 with the error code `content_filter` before the agent runs. A streamed Responses request emits no events.
Blocked nonstreaming Responses or buffered Invocations output	Foundry returns HTTP 400 with the error code `content_filter` and a message that identifies the output stage.
Blocked streamed Responses or Invocations output	The HTTP status remains 200 because headers are already sent. Foundry ends the server-sent event stream with a terminal `error` event whose code is `content_filter`.

Don't use the HTTP status alone to determine whether streamed output passed the policy. Parse terminal events supported by the hosted-agent protocol. Stop processing after a block, apply your product-specific handling to content already released, and don't automatically resubmit the same content.

Policy and service failures

Verify that the policy exists on the same Foundry resource as the hosted agent, and test the deployed agent before relying on it. A nonexistent policy can fail open: the agent can deploy as active while no content filtering is applied. For the Invocations protocol, also verify that the moderation paths and selectors match actual request, response, and event shapes.

Error details vary by hosted-agent protocol and response mode. Handle only fields defined by the protocol and API version your application uses.

Use these articles to configure guardrails and understand supported controls:

Feedback

Was this page helpful?

Last updated on 2026-10-22