Skip to main content

Class: PhraseListGuardrail

Defined in: packages/agentos/src/safety/guardrails/builtin/PhraseListGuardrail.ts:159

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.

Examples​

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
  }
}
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;
  }
}
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​

Properties​

config​

readonly config: GuardrailConfig

Defined in: packages/agentos/src/safety/guardrails/builtin/PhraseListGuardrail.ts:161

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

Implementation of​

IGuardrailService.config

id​

readonly id: string

Defined in: packages/agentos/src/safety/guardrails/builtin/PhraseListGuardrail.ts:160

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.

Implementation of​

IGuardrailService.id

stages​

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

Defined in: packages/agentos/src/safety/guardrails/builtin/PhraseListGuardrail.ts:166

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

Implementation of​

IGuardrailService.stages

Accessors​

snapshot​

Get Signature​

get snapshot(): PhraseListSnapshot | null

Defined in: packages/agentos/src/safety/guardrails/builtin/PhraseListGuardrail.ts:185

The list in force: its version and when and by whom it was reviewed.

Returns​

PhraseListSnapshot | null

Methods​

evaluateInput()​

evaluateInput(payload): Promise<GuardrailEvaluationResult | null>

Defined in: packages/agentos/src/safety/guardrails/builtin/PhraseListGuardrail.ts:207

Evaluate user input before orchestration.

Called once per request before the orchestration pipeline starts. Use this to validate, sanitize, or block user messages.

Parameters​

payload​

GuardrailInputPayload

Input and context to evaluate

Returns​

Promise<GuardrailEvaluationResult | null>

Evaluation result, or null to allow without action

Remarks​

  • Return BLOCK to prevent the request from being processed
  • Return SANITIZE with modifiedText to clean the input
  • Return null or ALLOW to let the request through

Implementation of​

IGuardrailService.evaluateInput

evaluateOutput()​

evaluateOutput(payload): Promise<GuardrailEvaluationResult | null>

Defined in: packages/agentos/src/safety/guardrails/builtin/PhraseListGuardrail.ts:212

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​

payload​

GuardrailOutputPayload

Response chunk and context to evaluate

Returns​

Promise<GuardrailEvaluationResult | null>

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

Implementation of​

IGuardrailService.evaluateOutput

reload()​

reload(): Promise<void>

Defined in: packages/agentos/src/safety/guardrails/builtin/PhraseListGuardrail.ts:193

Loads the list again and swaps it in whole. A list that fails to load or compile leaves the last good one in force (and throws, so the caller hears of it).

Returns​

Promise<void>

create()​

static create(opts): Promise<PhraseListGuardrail>

Defined in: packages/agentos/src/safety/guardrails/builtin/PhraseListGuardrail.ts:178

Loads the list and compiles it. Refuses a list that does not load, is empty, or has judge entries and no judge.

Parameters​

opts​

PhraseListGuardrailOptions

Returns​

Promise<PhraseListGuardrail>