Interface: IGuardrailService
Defined in: packages/agentos/src/safety/guardrails/IGuardrailService.ts:503
Contract for implementing custom guardrail logic.
Guardrails intercept content at two points:
- Input - Before user messages enter the orchestration pipeline
- 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?
optionalconfig: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?
optionalid: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?
optionalstages: 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()?
optionalevaluateInput(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
Input and context to evaluate
Returns
Promise<GuardrailEvaluationResult | null>
Evaluation result, or null to allow without action
Remarks
- Return
BLOCKto prevent the request from being processed - Return
SANITIZEwithmodifiedTextto clean the input - Return
nullorALLOWto let the request through
evaluateOutput()?
optionalevaluateOutput(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
Response chunk and context to evaluate
Returns
Promise<GuardrailEvaluationResult | null>
Evaluation result, or null to allow without action
Remarks
- Return
BLOCKto immediately terminate the stream with an error chunk, or with a FINAL_RESPONSE holdingreplacementTextwhen the result carries a non-empty one - Return
SANITIZEwithmodifiedTextto redact/modify content; on a TOOL_CALL_REQUEST chunk it is applied asBLOCK - Streaming evaluation adds latency; use only when real-time filtering is required