Skip to main content

Interface: IGuardrailService

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

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

Extended by​

Properties​

config?​

optional config: GuardrailConfig

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

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


id?​

optional id: string

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

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.


stages?​

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

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

The stages this guard evaluates, for a guard whose methods say more than its configuration: one that implements both methods but runs on one stage declares that stage. A required guard is held to what it declares, and a stage it does not declare is reported as missing instead of passing on the method's existence. Without it, a stage counts as covered when its method exists.

Methods​

evaluateInput()?​

optional evaluateInput(payload): Promise<GuardrailEvaluationResult | null>

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

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

evaluateOutput()?​

optional evaluateOutput(payload): Promise<GuardrailEvaluationResult | null>

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

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