createModerationGuardrail

function createModerationGuardrail(options): Guardrail;

Defined in: src/guardrails/moderation.ts:132

Create a guardrail backed by an async moderation classifier.

Parameters

Returns

Guardrail

Remarks

Pair with mode: 'buffered' and onError: 'block' when a flagged response must never be partially spoken: buffering holds the audio until the verdict is in, and the fail-closed policy means a classifier outage produces silence rather than unfiltered output. With a Live TTS provider 'buffered' is not merely advisable — the default stages: ['final'] has nothing to run at in 'streaming' mode. Set stages: ['chunk', 'final'] if the guardrail has to apply in both.

Example

const agent = new CompositeVoice({
  providers: [...],
  guardrails: {
    mode: 'buffered',
    onError: 'block',
    timeoutMs: 2000,
    filters: [
      createModerationGuardrail({
        replacement: "I'm not able to help with that.",
        async moderate(text, ctx) {
          const res = await fetch('/api/moderate', {
            method: 'POST',
            headers: { 'content-type': 'application/json' },
            body: JSON.stringify({ text }),
            signal: ctx.signal,
          });
          const { flagged, categories } = await res.json();
          return { flagged, categories };
        },
      }),
    ],
  },
});

agent.on('guardrail.blocked', ({ guardrail, reason }) => {
  console.warn(`${guardrail} suppressed a response: ${reason}`);
});