OpenAI Realtime engine: expose the WebSocket close code and reason to subclasses
维护者通常 1 天内回复
评估
调研方向
Start with livekit/agents/llm/_realtime/openai.py, especially the receive loop at lines 1176–1190, and inspect how _is_fatal_error classifies error events. Trace how the WebSocket close code and reason are discarded and how errors are retried; done means subclasses can use close details to classify fatal versus retryable closures. An open linked pull request (#8078) is already addressing this issue.
由索引模型根据 Issue 内容生成。
描述
Feature Type
Would make my life easier
Feature Description
The shared OpenAI Realtime engine (livekit.agents.llm._realtime.openai) discards the WebSocket close code and reason. When the server closes the socket, _recv_task raises a generic, retryable APIConnectionError("… connection closed unexpectedly"), whatever the close frame said (openai.py#L1176-L1190).
OpenAI-compatible providers built on this engine often use close codes to signal that the session is over for good. For example, a provider closes with 4001 for bad credentials or 1008 for a policy violation, where reconnecting can't help. Since the code and reason are lost, the engine retries these until max_retry is used up, and a plugin can't tell a fatal close from a transient one.
It would help if the close code and reason were available to subclasses, for example:
- carried on the raised error (e.g.
APIConnectionError.body = {"code": ..., "reason": ...}), or - passed to an overridable hook such as
_on_ws_closed(code, reason) -> APIError, which decides whether the error is retryable.
Workarounds / Alternatives
The ElevenLabs realtime plugin in #8075 wraps the aiohttp WebSocket returned by _create_ws_conn to record the close frame's code and reason. Its _run_ws override then catches the APIConnectionError and raises a mapped APIError with the right retryable flag. It works, but it depends on internals of the receive loop, and every OpenAI-compatible provider would need to repeat it.
Additional Context
The same engine already lets subclasses classify errors that arrive as error events (_is_fatal_error). This would give close frames the same treatment.
🤖 Generated with Claude Code
- 主要语言
- Python
- 星标
- 14.6k
- 派生
- 3.9k
- 平均合并
- 3 天 19 小时
- 30 天内合并 PR
- 204
环境准备
这个项目没有提供开发容器、Dockerfile 或贡献指南，环境需要你自己搭建：先看它的 README，通用步骤见我们的新手贡献指南。
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
livekit/agents 的其他 Issue
-
Assistant markup is stripped from chat history when expressive mode is off可能已有人在做 @ShivamSharma43 于 16 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 72/100
维护者通常 1 天内回复
-
docs: openai.LLM vs openai.responses.LLM for HTTP OpenAI-compat hosts可能重新可做 @AbarnaaSree 于 55 天前认领，目前没有进行中的 PR。 未关闭
难度 2/5 1-3 小时 新手友好度 72/100
维护者通常 1 天内回复
-
Python AgentServer health check (GET /) returns 200 before the worker has registered with LiveKit可能已有人在做 @ninglinLiu 今天认领。 未关闭
难度 3/5 1-2 天 新手友好度 35/100
维护者通常 1 天内回复
-
enhancement
难度 4/5 3-5 天 新手友好度 38/100
维护者通常 1 天内回复
-
Soniox and simplismart STT detect a dead websocket and reconnect into it forever instead of failing over可能已有人在做 @ninglinLiu 于 1 天前认领。 未关闭
难度 4/5 3-5 天 新手友好度 35/100
维护者通常 1 天内回复
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 84/100
-
bug
难度 2/5 1-3 小时 新手友好度 77/100
AstrBotDevs/AstrBot#10720 ·
维护者通常 1 天内回复
-
cause/upstream comp/cli P2 provider/other tool/file type/bug
难度 2/5 1-3 小时 新手友好度 78/100
NousResearch/hermes-agent#143900 ·
维护者通常 1 天内回复
-
难度 1/5 1-3 小时 新手友好度 85/100
WLAN-Pi/wlanpi-profiler#341 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 77/100
维护者通常 1 天内回复