Class PhraseListGuardrail

Contract for implementing custom guardrail logic.

Guardrails intercept content at two points:

  1. Input - Before user messages enter the orchestration pipeline
  2. Output - Before agent responses are streamed to the client

Both methods are optional—implement only what you need.

Example: Basic content filter

class ContentFilterGuardrail implements IGuardrailService {
  async evaluateInput({ input }: GuardrailInputPayload) {
    if (input.textInput?.includes('prohibited')) {
      return {
        action: GuardrailAction.BLOCK,
        reason: 'Input contains prohibited content',
        reasonCode: 'CONTENT_BLOCKED'
      };
    }
    return null; // Allow
  }
}

Example: Mid-stream "changing mind" (cost ceiling)

class CostCeilingGuardrail implements IGuardrailService {
  config = { evaluateStreamingChunks: true };
  private tokenCount = 0;

  async evaluateOutput({ chunk }: GuardrailOutputPayload) {
    if (chunk.type === 'TEXT_DELTA') {
      this.tokenCount += chunk.textDelta?.length ?? 0;
      if (this.tokenCount > 5000) {
        // "Change mind" - stop mid-stream
        return {
          action: GuardrailAction.BLOCK,
          reason: 'Response exceeded cost ceiling'
        };
      }
    }
    return null;
  }
}

Example: PII redaction mid-stream

class PIIRedactionGuardrail implements IGuardrailService {
  config = { evaluateStreamingChunks: true, maxStreamingEvaluations: 100 };

  async evaluateOutput({ chunk }: GuardrailOutputPayload) {
    if (chunk.type === 'TEXT_DELTA' && chunk.textDelta) {
      const redacted = chunk.textDelta.replace(
        /\b\d{3}-\d{2}-\d{4}\b/g,
        '[SSN REDACTED]'
      );
      if (redacted !== chunk.textDelta) {
        return {
          action: GuardrailAction.SANITIZE,
          modifiedText: redacted,
          reasonCode: 'PII_REDACTED'
        };
      }
    }
    return null;
  }
}

Implements

Accessors

snapshot

Methods

create reload evaluateInput evaluateOutput

Properties

id config stages

Accessors

snapshot

Methods

Static create

reload

evaluateInput

evaluateOutput

  • evaluateOutput(__namedParameters): Promise<null | GuardrailEvaluationResult>

  • Evaluate agent output before streaming to client.

    Called for each chunk of a guarded output stream (the turn's, and the continuation after an external tool result) that carries isFinal: true (the FINAL_RESPONSE, an ERROR the turn yields), for each TEXT_DELTA chunk when GuardrailConfig.evaluateStreamingChunks is set (real-time filtering), and for each TOOL_CALL_REQUEST chunk when GuardrailConfig.evaluateToolCalls is set. Other chunks are not passed to it, nor is the ERROR that processRequest() yields from its own catch.

    Parameters

    Returns Promise<null | GuardrailEvaluationResult>

    Evaluation result, or null to allow without action

    Remarks

    • Return BLOCK to immediately terminate the stream with an error chunk, or with a FINAL_RESPONSE holding replacementText when the result carries a non-empty one
    • Return SANITIZE with modifiedText to redact/modify content; on a TOOL_CALL_REQUEST chunk it is applied as BLOCK
    • Streaming evaluation adds latency; use only when real-time filtering is required

Properties

Readonly id

id: string

A stable id for this guard. A required guard is named by it (AgentOSConfig.requiredGuardrails), and it travels with every verdict as metadata.guardrailId. Without one, a registered guard is known by its descriptor's id.

Readonly config

config: GuardrailConfig

Configuration for evaluation behavior. Controls streaming vs final-only evaluation and rate limiting.

Readonly stages

stages: readonly ("output" | "input")[]

The stages this guard evaluates; a required guard is held to them (IGuardrailService.stages).

Settings

Member Visibility

Theme

On This Page

snapshotcreatereloadevaluateInputevaluateOutputidconfigstages