Interface GuardrailEvaluationResult

Result returned by a guardrail evaluation.

Contains the action to take and optional context about why. This result is attached to response chunk metadata for observability.

Example

// Block with explanation
const result: GuardrailEvaluationResult = {
  action: GuardrailAction.BLOCK,
  reason: 'Content contains prohibited material',
  reasonCode: 'CONTENT_POLICY_001',
  metadata: { category: 'violence', confidence: 0.95 }
};

// Sanitize PII
const result: GuardrailEvaluationResult = {
  action: GuardrailAction.SANITIZE,
  modifiedText: 'Contact me at [EMAIL REDACTED]',
  reasonCode: 'PII_REDACTED'
};
interface GuardrailEvaluationResult {
    action: GuardrailAction;
    reason?: string;
    reasonCode?: string;
    metadata?: Record<string, unknown>;
    details?: unknown;
    modifiedText?: null | string;
    replacementText?: string;
}

Properties

action reason? reasonCode? metadata? details? modifiedText? replacementText?

Properties

action

action: GuardrailAction

The action AgentOS should take based on this evaluation

Optional reason

reason?: string

Human-readable reason for the action. May be shown to end users or logged for audit.

Optional reasonCode

reasonCode?: string

Machine-readable code identifying the policy or rule triggered. Useful for analytics and automated handling.

Optional metadata

metadata?: Record<string, unknown>

Additional metadata for analytics, audit, or debugging. Persisted in response chunk metadata.

Optional details

details?: unknown

Detailed information about the evaluation (e.g., moderation scores, stack traces, matched patterns). Not shown to users.

Optional modifiedText

modifiedText?: null | string

Replacement text when action is GuardrailAction.SANITIZE. For input evaluation: replaces textInput before orchestration. For output evaluation: replaces textDelta (streaming) or finalResponseText (final).

Optional replacementText

replacementText?: string

With GuardrailAction.BLOCK on output (a streamed delta or the final response): a non-empty string is the fixed reply the caller receives in place of the model's, as a FINAL_RESPONSE whose guardrail metadata records the block, instead of an error chunk; an empty string or no value yields the error chunk. A product's safety templates answer this way, so a person reads a fixed text and never a raw failure.

Settings

Member Visibility

Theme

On This Page

actionreasonreasonCodemetadatadetailsmodifiedTextreplacementText