Skip to main content

​
Voice-specific guardrails

VoiceGateway provides project-scoped, LLM-side guardrails for voice agents. Guardrails are injected through the existing voicegateway.inference.LLM(...) drop-in path, so agent code keeps the same LiveKit construction pattern. Guardrails do not create a proxy session service, do not inspect raw audio, and do not intercept arbitrary tool calls. They append a versioned system prompt block to the LiveKit chat context and register one reserved LiveKit function tool named report_guardrail_action.

​
Policy model

Guardrail policies live per project. The default is disabled, with every category set to off. 
projects:
  support:
    name: Support Bot
    guardrails:
      enabled: true
      categories:
        pii: redact
        financial: block
        medical: alert
        prompt_injection: block
        off_topic: off
Categories:
  • pii
  • financial
  • medical
  • prompt_injection
  • off_topic
Actions:
  • redact: answer without repeating the sensitive detail.
  • block: decline the current turn with a brief, neutral response.
  • alert: continue normally and write an audit event.
  • off: disable that category.

​
Runtime behavior

On the first guarded LLM chat in a session, VoiceGateway freezes the active project policy. Later dashboard or API edits affect new sessions only. When guardrails are active:
  • VoiceGateway appends a <voicegateway_guardrails version="v0.6.0"> block after existing system/developer instructions.
  • VoiceGateway registers report_guardrail_action(category, action, context_excerpt).
  • A user-defined tool with the same name is rejected for that session.
  • Audit rows are written to guardrail_events with event_type = fired.
Session detail responses include:
  • guardrails_active
  • guardrails_bypassed
  • guardrail_policy_snapshot
  • guardrail_events
This lets the dashboard distinguish “active policy, zero events” from “no guardrail audit”.

​
Bypass

Use bypass only for trusted internal sessions where the operator intentionally wants no injection. VoiceGateway records a bypass audit event when the frozen policy would otherwise be active. 
from voicegateway import inference

session_id = inference.start_session(bypass_guardrails=True)

# Or, when binding a custom LiveKit AgentSession:
inference.attach_session(agent_session, bypass_guardrails=True)
Bypass skips prompt/tool injection for the session. The bypass row has event_type = bypassed; category and action are NULL.

​
CLI

voicegw guardrails talks to the dashboard API: 
voicegw guardrails show --project support
voicegw guardrails set --project support --category pii --action redact
voicegw guardrails clear --project support
voicegw guardrails dry-run --project support
Use VOICEGW_API_KEY when your dashboard API requires auth.

​
API

Server API:
  • GET /v1/projects/{id}/guardrails
  • POST /v1/projects/{id}/guardrails
  • GET /v1/guardrails/events
  • GET /v1/guardrails/aggregate
Dashboard API mirrors these under /api/.... Aggregates count only fired rows. Event listings can include both fired and bypassed.

​
Caveats

These guardrails are prompt-side controls, not a deterministic safety classifier. They depend on the selected LLM following instructions and calling the reserved tool. Use provider-native moderation, contractual compliance review, and invoice/log reconciliation for higher-assurance workflows.