Skip to main content

Interface: ICrossAgentGuardrailService

Defined in: packages/agentos/src/safety/guardrails/ICrossAgentGuardrailService.ts:127

Cross-agent guardrail service for multi-agent supervision.

Extends IGuardrailService to enable observation and intervention in other agents' output streams. Use this for:

  • Supervisor patterns: A supervisor agent monitors worker agents
  • Quality gates: Enforce quality standards across an agency
  • Policy enforcement: Apply organization-wide rules to all agents
  • Safety monitoring: Detect and prevent harmful outputs from any agent

Examples​

class QualityGateGuardrail implements ICrossAgentGuardrailService {
  // Observe all agents in the agency
  observeAgentIds = [];
  canInterruptOthers = true;

  async evaluateCrossAgentOutput({ sourceAgentId, chunk, context }) {
    if (chunk.type === 'FINAL_RESPONSE') {
      const quality = await assessQuality(chunk.finalResponseText);
      if (quality.score < 0.5) {
        return {
          action: GuardrailAction.BLOCK,
          reason: 'Response did not meet quality standards',
          metadata: { qualityScore: quality.score, agent: sourceAgentId }
        };
      }
    }
    return null;
  }
}
class SensitiveDataGuardrail implements ICrossAgentGuardrailService {
  // Only observe agents handling sensitive data
  observeAgentIds = ['data-analyst', 'report-generator'];
  canInterruptOthers = true;
  config = { evaluateStreamingChunks: true };

  async evaluateCrossAgentOutput({ chunk }) {
    if (chunk.textDelta && containsPII(chunk.textDelta)) {
      return {
        action: GuardrailAction.SANITIZE,
        modifiedText: redactPII(chunk.textDelta)
      };
    }
    return null;
  }
}

Extends​

Properties​

canInterruptOthers?​

optional canInterruptOthers: boolean

Defined in: packages/agentos/src/safety/guardrails/ICrossAgentGuardrailService.ts:158

Whether this guardrail can interrupt other agents' streams.

When true:

When false (default):

  • Guardrail can only observe and log (FLAG action)
  • BLOCK/SANITIZE actions are downgraded to FLAG

Default​

false

config?​

optional config: GuardrailConfig

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

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

Inherited from​

IGuardrailService.config

observeAgentIds?​

optional observeAgentIds: string[]

Defined in: packages/agentos/src/safety/guardrails/ICrossAgentGuardrailService.ts:143

Agent IDs this guardrail observes.

  • Empty array [] or undefined: Observe all agents in the agency
  • Specific IDs: Only observe listed agents

Example​

// Observe specific workers
observeAgentIds = ['worker-1', 'worker-2'];

// Observe all agents
observeAgentIds = [];

Methods​

evaluateCrossAgentOutput()?​

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

Defined in: packages/agentos/src/safety/guardrails/ICrossAgentGuardrailService.ts:175

Evaluate output from an observed agent.

Called when an observed agent (per observeAgentIds) emits a chunk. The evaluation timing depends on IGuardrailService.config:

  • evaluateStreamingChunks: true: Called for each TEXT_DELTA
  • evaluateStreamingChunks: false: Called only for FINAL_RESPONSE

Parameters​

payload​

CrossAgentOutputPayload

Cross-agent context and chunk to evaluate

Returns​

Promise<GuardrailEvaluationResult | null>

Evaluation result, or null to allow without action

Remarks​

  • Only effective when canInterruptOthers is true
  • Falls back to this guardrail's own stream for logging/metadata

evaluateInput()?​

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

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

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

Inherited from​

IGuardrailService.evaluateInput

evaluateOutput()?​

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

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

Evaluate agent output before streaming to client.

Called for response chunks based on GuardrailConfig.evaluateStreamingChunks:

  • true: Called for every TEXT_DELTA chunk (real-time filtering)
  • false (default): Called only for FINAL_RESPONSE chunks

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
  • Return SANITIZE with modifiedText to redact/modify content
  • Streaming evaluation adds latency; use only when real-time filtering is required

Inherited from​

IGuardrailService.evaluateOutput