Skip to main content

Manage interceptors

This page explains how administrators use DIAL Admin to add and configure interceptors. It covers creating an interceptor, configuring its endpoint, interfaces and parameters, and where to attach it to models or applications. You need access to DIAL Admin with administrator permissions.

DIAL interceptors are pluggable components with the primary goal of implementing a Responsible AI approach and enforcing compliance with organization and external policies and standards (biased answers, data leaks, etc.).

Interceptors provide the ability to delegate content analysis to third-party systems or dedicated models used within an organization, or to carry any other custom implementation.

Selected use cases:

  • Prevent harmful requests from reaching the model
  • Prevent harmful replies from reaching the user
  • Modify the request/response, introduce disclaimers
  • DLP (Data Loss Prevention)
  • Smart information collection
  • Implement caching strategies
  • Application of watermarks

DIAL Interceptors Python SDK makes development of new interceptors easier and enables integration with external systems like Google Model Armor, MS Presidio, and more.

An interceptor is an entity of the DIAL Core runtime configuration that points to a service DIAL Core calls for each request. You define it here, and attach it where it should run.

Types​

You can configure global interceptors that apply on a system level in System Properties and local interceptors that are triggered for specific model or application deployments, or apps created based on application runners.

Execution order​

When interceptors of several kinds are configured for a request, DIAL Core runs them in this sequence:

  • Request: global interceptors, then application type interceptors (those of the application's runner), then local interceptors.
  • Response: local interceptors, then application type interceptors, then global interceptors. The response passes through the interceptors in the reverse order of the request.

Global interceptors receive the original request first and examine the response last. Within each kind, request interceptors run in the order listed (1 → 2 → 3) and response interceptors run in reverse. You set this order by dragging rows in the interceptors grid of a model, an application or an application runner, and in System Properties for global interceptors.

Note

Main screen​

On this screen, you can access all the available interceptors: those stored by DIAL Admin and those defined in the DIAL Core config file. Here, you can manage and add interceptors to your DIAL environment.

Interceptors main screen with the file and platform folders

Folders​

The left panel shows where each interceptor definition is stored. It has two root folders:

  • file: interceptors defined in the DIAL Core configuration file. This folder is read-only. To change these interceptors, edit the DIAL Core config file.
  • platform: interceptors stored in DIAL Core platform storage. This is where you create, edit and delete interceptors in DIAL Admin.

Select a folder to list its interceptors in the grid. See AI Gateway for how DIAL Core combines the two sources, including what happens when a file interceptor and a platform interceptor have the same name.

file folderplatform folder
ColumnsNameName, Author, Created Time, Updated Time
CreateNot available. No Create button.Available.
Duplicate, DeleteNot available.Available in the row's actions menu.
Open an interceptorRead-only: it can't be changed or saved.Editable.

Interceptors grid​

FieldDescription
NameName of the interceptor (e.g. "PII Information Remover").
AuthorUser who created the interceptor. Platform folder only.
Created TimeEntity creation timestamp. Platform folder only.
Updated TimeTimestamp of the latest update of the entity. Platform folder only.

Create​

Select the platform folder first. Interceptors can't be created in the file folder.

Follow these steps to add a new interceptor definition:

  1. Click Create and select Interceptor to invoke the Create Interceptor modal.

  2. Define interceptor parameters:

    ColumnRequiredDescription
    IDYesUnique identifier for the interceptor (e.g. reject-blacklisted-words, audit-logger). This key is used when you attach it to a Model or Application.
    Display NameYesName of the interceptor (e.g. "PII Information Remover") displayed on UI.
    DescriptionNoBrief summary of what this interceptor does and any parameters it uses (e.g. BLACKLIST={"foo","bar"} or Logs request/response payloads).

  3. Once all required fields are filled, click Create. The dialog closes and the new interceptor configuration screen is opened. Once added, a new entry appears in the Interceptors listing. It may take some time for the changes to take effect after saving.

    Create interceptor modal

Duplicate​

Use Duplicate to create a new interceptor with the settings of an existing one. It is available in the actions menu (⋮) of an interceptor in the platform folder. Interceptors in the file folder can't be duplicated.

  1. Click Duplicate in the interceptor's actions menu to open the duplicate modal.

  2. Specify the parameters of the copy:

    FieldRequiredDescription
    IDYesUnique identifier of the copy. It is prefilled with the original ID plus the -copy suffix. If the original ID already contains copy, it is prefilled unchanged, so change it.
    Display NameYesName of the copy displayed on UI. It is prefilled with the original display name.

  3. Click Duplicate. The copy is created in the platform folder and appears in the listing.

The copy keeps all other settings of the original: endpoint, interfaces, defaults, headers, topics, catalog schema and catalog metadata. The author and the creation and update times are not copied.

Delete​

Use the Delete button in the Configuration screen toolbar or in the main screen actions menu to permanently remove the selected interceptor. Delete is available only for interceptors in the platform folder.

Configuration​

Click any interceptor on the main screen to open its configuration details. The screen has three tabs: Properties, Parameter scheme and Catalog metadata. A badge above the interceptor ID shows whether DIAL Core accepted the definition: Valid, or Invalid with a tooltip that names the offending field and the reason. Interceptors from the file folder open in read-only mode.

Properties​

In the Properties tab, you can define metadata and execution endpoints for interceptors.

FieldRequiredEditableDescription
ID-NoUnique key under interceptors in DIAL Core's dynamic settings (e.g. data-clustering, support-bot).
Updated Time-NoDate and time when the interceptor's configuration was last updated.
Creation Time-NoDate and time when the interceptor's configuration was created.
Display NameYesYesName of the interceptor displayed on UI (e.g. "PII Information Remover").
DescriptionNoYesDescription of the interceptor (e.g. BLACKLIST={"foo","bar"}). Helps to identify the interceptor and its purpose.
Override nameNoYesDIAL Core calls the interceptor under this name: the model field of the request body and the X-DIAL-OVERRIDE-NAME header are rewritten to this value before the request reaches the interceptor. It doesn't change routing, only the value the interceptor receives. It applies to chat completions requests; the Responses API flow ignores it.
Base URLNoYesThe root URL of the interceptor service. It serves every entry in Interfaces that has no Base URL of its own.
InterfacesNoYesTyped alternative to Endpoint. See Interfaces. If both are set, Interfaces takes precedence.
EndpointConditionalYesURL of the interceptor's chat completion endpoint. DIAL Core forwards requests to it as is. Required unless Interfaces is used.
Configuration EndpointNoYesThe URL that exposes the configuration of the interceptor. This endpoint returns a JSON schema with configuration parameters that are rendered in the Parameter scheme tab.
DefaultsNoYesThe interceptor configuration can be preset on a per-interceptor basis via the defaults field. Default parameters are applied if a request doesn't contain them in an OpenAI chat/completions API call. An interface with its own Defaults uses those instead. Refer to Interceptors SDK to learn more.
Default headersNoYesHTTP headers DIAL Core adds to a request that doesn't already carry them, on the call to this interceptor. Headers that DIAL Core strips on the way to an interceptor (for example Api-Key) are stripped here too. An interface can add or override headers for itself.
TopicsNoYesSemantic labels (e.g. "finance", "support"). Select existing ones or type to add.
Forward auth tokenNoYesControls whether the user's authorization token is forwarded (in the HTTP header) to the interceptor's completion endpoint. Use this when your interceptor service requires its own authentication. Selector with two options — - None - (default) and Use for this interceptor — chosen in a popup and confirmed with Apply. Choosing Use for this interceptor shows a security warning and asks you to enter the interceptor's display name to confirm.
Catalog schemaNoYesThe catalog schema that defines this interceptor's catalog metadata. Selecting a schema enables the Catalog metadata tab.

Interceptor properties tab

Interfaces​

Interceptors support one interface type, OpenAI Chat Completions. Click Add interface to add it.

When an interface has a Base URL, DIAL Core forwards each request to that Base URL followed by the path the request arrived on, with the deployment ID in the path replaced by the interceptor's own name. An interface without a Base URL uses the interceptor-level Base URL. If neither is set, DIAL Admin doesn't let you save the interface.

FieldRequiredDescription
DefaultsNoBody parameters applied to requests for this interface only. They replace the interceptor-level Defaults instead of merging with them. A parameter the request already carries is never replaced.
ModeNoPassthrough (default) forwards the request in the shape it arrived in. Translator hands it to a service that translates it into another API.
Base URLConditionalThe root URL that the request path is appended to. Required if the interceptor has no Base URL. Available in Passthrough mode.
TranslatorConditionalThe translator that serves this interface. Select a platform translator, or Custom to enter a Base URL and the target interface. Available in Translator mode, and required there. An interface is served by a Base URL or by a translator, never both.
Override pathsNoPer-operation upstream path that replaces the default "Base URL + request path" routing. For interceptors the only operation is postAzureOpenaiChatCompletions, and {id} is replaced with the interceptor's name. Passthrough mode only.
Default headersNoHeaders applied to requests for this interface only, laid over the interceptor-level Default headers.

Refer to DIAL Core documentation to learn more about interfaces and how they work.

Parameter scheme​

In this tab, you can define additional configuration parameters for the interceptor. The parameters displayed in this section are defined by the JSON schema returned by the Configuration Endpoint specified in the Properties tab. If a valid endpoint is specified, the content on this screen is rendered automatically based on the JSON schema returned by that endpoint. Rendered parameters are pre-populated with their default values. If an invalid configuration endpoint is provided, a "No Configuration Scheme" state is shown instead.

Interceptor parameter scheme tab

Catalog metadata​

Catalog metadata describes the interceptor against a catalog schema: a structured set of fields defined centrally. The tab is empty until you select a schema in the Catalog schema field on Properties. Once a schema is selected, its fields are shown for you to complete.

Interceptor catalog metadata

JSON editor​

Advanced users with technical expertise can work with the interceptor properties in a JSON editor view mode. It is useful for advanced scenarios of bulk updates, copy/paste between environments, or tweaking settings not exposed on UI.

Tip

You can switch between UI and JSON only if there are no unsaved changes.

  1. Navigate to Interceptors, select the platform folder, then select the interceptor you want to edit.
  2. Click the JSON Editor toggle (top-right). The UI reveals the raw JSON.
  3. Make changes and click Save to apply them.

Interceptors in the file folder open read-only.

Further reading​