Bug: Output guardrail on supervisor agent causes SSE stream to never terminate
Description
When an agent with sub-agents (supervisor pattern) has outputGuardrails configured, the SSE stream never terminates — the stream reaches the finish step but does not emit the finish event, and the controller never closes. The client hangs indefinitely waiting for the stream to end.
Reproduction
- Create a supervisor agent with sub-agents and output guardrails:
import { Agent } from "@voltagent/core";
const mainAgent = new Agent({
name: "main",
model: /* any model */,
subAgents: [/* ... */],
inputGuardrails: [/* works fine */],
outputGuardrails: [
{
name: "output-sanitizer",
execute: async ({ output }) => {
// Simple pass-through or sanitization logic
return { action: "modify", output };
},
},
],
});Call
agent.streamText()or trigger via the built-in SSE server endpoint.Observe: the stream emits content chunks but never emits the
finishevent. The SSE connection stays open indefinitely. The client hangs.
Expected Behavior
When the model finishes generating and the output guardrail's execute returns, the stream should emit the finish event and close the SSE connection normally.
Actual Behavior
- Stream reaches the finish step internally
- No
finishevent is emitted to the client - SSE controller never closes
- Client hangs indefinitely
Workaround
Remove outputGuardrails from supervisor agents. Input guardrails work correctly and do not cause this issue.
const mainAgent = new Agent({
name: "main",
model: /* any model */,
subAgents: [/* ... */],
inputGuardrails: [/* works fine */],
// outputGuardrails: [/* REMOVED — causes SSE hang */],
});Environment
@voltagent/core: 2.9.2 (also confirmed not fixed in 2.10.0)- Node.js: v22.18.0
- OS: Windows 10 / Linux (Docker)
Additional Context
- This only affects agents with sub-agents (supervisor pattern). Standalone agents with output guardrails appear to work fine.
inputGuardrailson the same supervisor agent work correctly.- This was tested with both
streamText()and the built-in SSE server endpoint. - The closest related fix is PR #1135 (v2.6.5) which fixes a double
writer.close()exception for agents with sub-agents, but it does not resolve this output guardrail issue. createOutputGuardrailis still a documented feature with no caveat about supervisor incompatibility, so this appears to be an untracked defect rather than a known limitation.
Impact
Output content filtering (sensitive word sanitization, compliance checks, PII redaction) cannot be applied to supervisor agents, forcing users to implement workarounds (post-processing in onEnd hooks or SSE middleware) which are less clean and miss streaming-time interception.
Source: VoltAgent/voltagent