Skip to main content

Azure Content Safety provider

Overview​

Design goals: This provider bridges Azure Content Safety into Mastra so teams can rely on tenant-hosted moderation resources and Azure-managed authentication instead of external services. It centralizes auth selection, blocklist, threshold, and retry behavior so moderation features that Mastra doesn't implement natively can be consumed uniformly.

Docs guideline: This page assumes a tenant-first deployment model: write as if the Content Safety resource is deployed in the reader's Azure tenant and emphasize Managed Identity-first usage. Include short env-var examples when helpful and cross-link back to the Azure introduction's "Documentation guideline" for global guidance.

Mastra routes every moderation call through src/mastra/providers/azure-content-safety.ts. The module wraps the REST-based Azure AI Content Safety client, enforces configurable retry logic, and exposes helper types such as TextModerationInput and ImageModerationInput so callers can provide text, image URLs/base64 blobs, optional category filters, and signal-aware timeouts.

Authentication and retries​

  • Authentication precedence is explicit: AZURE_CONTENT_SAFETY_USE_MANAGED_IDENTITY=true forces managed identity; otherwise the provider uses API key when AZURE_CONTENT_SAFETY_KEY/CONTENT_SAFETY_KEY is present; if no key exists it falls back to managed identity. The provider caches both the credential and the client (ensureClient) to avoid recreating the ContentSafetyClient for every request.
  • The Azure endpoint is mandatory (AZURE_CONTENT_SAFETY_ENDPOINT or CONTENT_SAFETY_ENDPOINT). A missing value throws before any HTTP traffic, keeping tooling from spinning up without a target.
  • Calls go through executeWithRetry, which implements exponential backoff for HTTP 408/429/5xx responses. The helper also respects the retry-after header, abort signals, and the AZURE_CONTENT_SAFETY_DEBUG_TIMINGS flag for extra logging.

Blocklists, categories, and thresholds​

  • Blocklists come from environment variables (AZURE_CONTENT_SAFETY_BLOCKLIST_NAME). The helper getConfiguredContentSafetyBlocklistNames() parses comma-separated names, while resolveBlocklists and resolveSingleBlocklistName enforce whether a request can omit the blocklist or must pick one when several are configured.
  • Every moderation result returns a list of ContentSafetyCategory entries, each normalized via normalizeCategories so the highest severity comes first. The maxSeverity/flagged properties mirror rawResponse fields so callers can easily gate actions.
  • Blocklist hits are surfaced with ContentSafetyBlocklistHit metadata, allowing tooling to log the blocklist name, entry ID, and textual match.

Text + image helpers​

  • Text moderation payloads accept categories, custom blocklistNames, and a haltOnBlocklistHit flag when one match should stop all scoring. Image moderation also accepts the same categories and leverages the same executeWithRetry/ensureClient plumbing.
  • Image inputs are normalized via normalizeImageInput, which handles URLs, raw base64 strings, and ArrayBuffer/Buffer payloads so callers only need to supply the raw bytes or blob reference.
  • Both helpers surface the authMode (managed-identity vs api-key), the raw Azure REST response, and the highest severity category per call.

Usage notes​

  • Tooling that wires into Azure Content Safety typically obtains the blocklist name from the caller or the configured default (getDefaultContentSafetyBlocklistName).
  • The provider logs timing diagnostics only when either AZURE_CONTENT_SAFETY_DEBUG_TIMINGS or MASTRA_DEBUG_TIMINGS is enabled.
  • For long-running moderation requests, provide an AbortSignal to TextModerationInput/ImageModerationInput so the helper respects cancellation while inside wait or executeWithRetry.