qwen-audio-agent: a voice runtime that keeps a coding agent talking while it works
A realtime voice runtime that keeps Agents talking, working, and present. Real-time Voice Runtime for AI Agents
At a glance
- What is it?
- QwenAudio's qwen-audio-agent is a Node.js realtime voice runtime that sits in front of an ACP-compatible coding agent, answers simple questions itself, and delegates longer work to the backend. It is a good fit if your agent already speaks ACP; it is the wrong tool if you want a self-contained voice assistant with no external agent.
- Who is it for?
- Adopt qwen-audio-agent if you already run an ACP-speaking agent such as Qwen Code, OpenCode, or Kimi Code and want a voice layer that keeps the conversation alive during tool calls. Do not adopt it if you need a fully offline assistant or cannot supply a DashScope API key for the hosted realtime model.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap qwen-audio-agent fills between speech and a coding agent
Most voice assistants stop being useful the moment the answer requires a tool call. The README states the problem directly: conversation should not "grind to a halt just because the Agent is looking something up, calling a tool, or working on a task." qwen-audio-agent is built around that specific failure. The project describes itself as a realtime voice runtime that keeps agents "talking, working, and present."
The intended user is someone who already has a coding agent and wants to talk to it instead of typing. The Agent Support table lists Qwen Code, OpenCode, OpenClaw, Qoder, MiniMax Code, Kimi Code, Hermes, CodeBuddy, Codex, Claude Code, DeepSeek, and Pi, with integration paths marked as native ACP, built-in ACP bridge, or external ACP adapter. There is also a "None" row for frontend-only mode, which needs no configuration.
That row matters. It tells you the runtime is usable as a standalone voice frontend without any backend agent attached. If you have no agent and no intention of wiring one up, the project still runs, but the task delegation features described in the README have nothing to delegate to.
How the runtime splits frontend answers from backend tasks
The architecture section gives one sentence of routing logic: "Questions that can be answered directly are answered immediately; when tools or sustained processing are needed, the task is delegated to the backend Agent." The README adds that "the user always faces the same assistant" across both paths.
Two diagrams are referenced, docs/architecture-overview-en.png and docs/qwen-audio-agent-three-layer-architecture-en.png, with a deep dive at docs/architecture/deep-dive.md. The README does not reproduce the layer breakdown in text, so the exact boundary between the frontend model and the delegated task is not something I can confirm from the material. What is documented is the outcome: frontend conversation and background tasks "run in parallel," you can ask about progress or cancel at any time, and task results "automatically return to the current conversation, supporting follow-up questions and modifications."
The release notes add detail on how the runtime state surfaces to the user. v1.11.0 links pet animations to runtime states. v1.9.0 adds desktop task cards showing live agent progress. v1.5.0 adds scheduled reminders and progress reporting. Taken together, the design assumes long-running work and treats visible state as part of the product rather than an afterthought.
Install and configure: the commands the README actually gives
The install path is a global npm package. The README lists the requirement as Node.js 22.22.2+ or 24.15.0+ and npm 10+, then gives one command:
npm install -g qwen-audio-agent
Configuration is generated rather than hand-written. Running qwenaudio config produces a dotenv-style file where you fill in the key and model:
DASHSCOPE_API_KEY=your-key QWEN_AUDIO_REALTIME_MODEL=qwen-audio-3.0-realtime-plus
The README notes that the voice frontend model can be Audio Flash/Plus or Omni Flash/Plus, with Audio Plus as the default. The configuration snippet in the README is truncated at the point where backend settings begin, so I cannot list the backend keys from the supplied material. The configuration guide at docs/configuration.md is the place the README points to for those.
Two other paths exist. Building from source and installing from GitHub are covered in docs/getting-started/install.md, along with how to obtain a DashScope API key. The quickstart lives at qwenaudio.github.io/qwen-audio-agent/getting-started/quickstart. Frontends listed in the README are WebUI, terminal TUI, and a desktop floating orb for macOS, Windows, and Linux.
Backend support is a table of gradations, not a yes/no list
The Agent Support table is the most informative part of the README because it refuses to flatten everything into "supported." Qwen Code, OpenCode, OpenClaw, Qoder, and Kimi Code get five stars. MiniMax Code, Hermes, CodeBuddy, Codex, Claude Code, DeepSeek, and Pi get four. The README explains the scale: five stars means "a thoroughly tested recommended integration," four means "active development or not yet fully verified."
The integration mechanism differs by backend. Native ACP covers most entries. OpenClaw uses a built-in ACP bridge. Codex, Claude Code, and Pi require an external ACP adapter, and the setup column says "One-click install (base + adapter), user config required." That extra adapter step is worth reading as a signal: the further a backend sits from native ACP, the more moving parts you own.
Setup requirements also diverge. OpenCode and OpenClaw want a Bailian config. DeepSeek wants a DeepSeek API key. The rest say "user config required," which is vague enough that you should open docs/backends/overview.md before assuming your agent is a drop-in. The README itself points there for "detailed configuration and capability boundaries."
Where the design constrains you: keys, Node versions, and unverified backends
The most concrete limitation is the API key. The default realtime model is a hosted Qwen audio model reached through DashScope, and the config template requires DASHSCOPE_API_KEY. If your constraint is that audio must never leave the machine, the default path does not satisfy it. The README does document a partial answer: v1.3.0 added integration with Hugging Face speech-to-speech, described as "supporting fully local VAD, STT, LLM, and TTS." That is a frontend integration, and the README does not state whether it removes the DashScope requirement for the realtime model or coexists with it. Treat it as something to verify in the docs rather than a settled offline mode.
The version floor is unusually specific: Node.js 22.22.2+ or 24.15.0+. A patch-level minimum suggests the project depends on behaviour that changed inside a minor line. On a managed CI image pinned to an earlier 22.x build, npm install -g will succeed and the runtime may still fail. Check node --version before anything else.
The four-star backends are the other soft spot. A four-star rating means "active development or not yet fully verified," which is the project's own wording. If your workflow depends on Codex or Claude Code, you are on the adapter path, and the adapter is the component most likely to break when the upstream agent changes its protocol surface. The release cadence supports that reading: v1.10.0 on 2026-08-13, v1.10.1 on 2026-08-15, v1.11.0 on 2026-08-20. Three releases in a week is normal for a project still finding its edges.
What it does not replace: a plain speech-to-speech pipeline
The obvious alternative is the Hugging Face speech-to-speech project, which the README itself cites as a frontend integration rather than a competitor. The difference in approach is architectural. A speech-to-speech pipeline chains VAD, STT, an LLM, and TTS into one loop and produces one conversational stream. qwen-audio-agent keeps that loop for direct answers but adds a second path: a delegated task handed to an external agent over ACP, running asynchronously, reporting progress, and returning its result into the same conversation.
If your goal is a voice chat that answers questions, the pipeline is simpler and, in its fully local configuration, avoids sending audio to a hosted model. If your goal is to talk to an agent that edits files, runs commands, and takes minutes to finish, the pipeline gives you no place to put that work. The README's framing is explicit about which case it targets: multiple independent tasks "executed asynchronously by the backend Agent, with continuous status tracking."
A second alternative is not a tool at all: skip voice and use your agent's terminal interface. qwen-audio-agent's value depends on interruption and presence being worth the setup cost. For short, deterministic commands, typing is faster and has no model dependency.
Licence, maintenance, and what a v2.0.0 in development means for upgrades
The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. It also requires that you preserve notices and state significant changes. That is the standard reading of the licence text and not legal advice; if you redistribute the package inside a product, have counsel look at the NOTICE handling.
Maintenance cost has two components. The first is the pinned Node floor, which forces you to track Node releases more closely than a project requiring only "18+" would. The second is the ACP surface. Every backend agent you connect is a dependency you do not control, and the external adapters for Codex, Claude Code, and Pi are the ones most exposed to upstream protocol changes.
The upgrade picture is unsettled by the project's own announcement. The README's news section says v2.0.0 is "in development," with "ongoing work on the Agent architecture, task lifecycle, multimodal input, memory, and extensibility." Agent architecture and task lifecycle are two of the pillars the current version is built on. A major version that reworks them means the configuration you write today may not carry forward. Pin your installed version, read the v2.0.0 release notes when they land, and treat the current docs/configuration.md as valid only for the 1.x line.
Editorial conclusion
Adopt qwen-audio-agent if you already run an ACP-speaking agent such as Qwen Code, OpenCode, or Kimi Code and want a voice layer that keeps the conversation alive during tool calls. Do not adopt it if you need a fully offline assistant or cannot supply a DashScope API key for the hosted realtime model. Before installing, verify that your Node version satisfies the 22.22.2+ or 24.15.0+ requirement, that your chosen backend appears in the Agent Support table, and that the speech-to-speech frontend path actually covers the languages you need.
Community notes