Skip to main content

Interface: GuardrailEvaluationResult

Defined in: packages/agentos/src/safety/guardrails/IGuardrailService.ts:120

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

Properties​

action​

action: GuardrailAction

Defined in: packages/agentos/src/safety/guardrails/IGuardrailService.ts:122

The action AgentOS should take based on this evaluation

details?​

optional details: unknown

Defined in: packages/agentos/src/safety/guardrails/IGuardrailService.ts:146

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

metadata?​

optional metadata: Record<string, unknown>

Defined in: packages/agentos/src/safety/guardrails/IGuardrailService.ts:140

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

modifiedText?​

optional modifiedText: string | null

Defined in: packages/agentos/src/safety/guardrails/IGuardrailService.ts:153

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

reason?​

optional reason: string

Defined in: packages/agentos/src/safety/guardrails/IGuardrailService.ts:128

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

reasonCode?​

optional reasonCode: string

Defined in: packages/agentos/src/safety/guardrails/IGuardrailService.ts:134

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

replacementText?​

optional replacementText: string

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

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.