Qwen-Agent
A Qwen-focused framework for tool-using, document-aware, and code-executing LLM applications.
- Source repo
- QwenLM/Qwen-Agent
- Stars
- ★ 17k
- Last updated
- 8mo ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 42/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesOpenAI API (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A Python developer who needs to register an image-generation service as my_image_gen and have a Qwen agent invoke it as part of a task sequence.
- Not a fit if
- Users unwilling to install and run local Docker
- Environments on Python 3.9 or older
- Source review
- 42/100 · Major gaps 3 safety controls not found
What does this agent do, and when should you use it?
Qwen-Agent is an LLM application framework built around Qwen’s instruction following, tool use, planning, and memory capabilities. It exposes LLM classes derived from BaseChatModel, tools derived from BaseTool, and higher-level components derived from Agent. Example applications include Browser Assistant, Code Interpreter, and Custom Assistant, while WebUI provides a Gradio 5-based interface. Applications can use DashScope or connect to OpenAI API-compatible services such as vLLM and Ollama; the README also identifies Qwen-Agent as the backend of Qwen Chat. Its code interpreter runs in local Docker containers, and the documented isolation boundary should still be treated cautiously in production.
Developers can register a BaseTool subclass with @register_tool, parse model-generated parameters in call(params, **kwargs), and return a result to the agent. Assistant(llm=..., system_message=..., function_list=..., files=...) can receive supplied files, select registered or built-in tools such as code_interpreter, and stream responses through bot.run(messages=messages). LLM settings support qwen_dashscope or an OpenAI API-compatible endpoint via model_server, with generate_cfg options including top_p, max_input_tokens, fncall_prompt_type, and use_raw_api. WebUI(bot).run() starts a Gradio interface, while MCP configuration can define servers such as memory, filesystem, and sqlite through command and args fields.
- A Python developer who needs to register an image-generation service as my_image_gen and have a Qwen agent invoke it as part of a task sequence.
- A local application developer who wants an assistant to work with supplied PDF files and use code_interpreter for file-related operations.
- A Qwen application team choosing between DashScope and a self-hosted vLLM or Ollama model service.
- A developer connecting an agent to MCP memory, a filesystem server restricted to an allowed path, or SQLite.
- A team that needs a quick internal agent prototype using WebUI(bot).run().
- An engineer or researcher evaluating the RAG or parallel_doc_qa examples for very long-document question answering.
How do you install or deploy this agent?
Minimal installation:
pip install -U qwen-agentInstall optional GUI, RAG, Code Interpreter, and MCP components:
pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"Source installation:
git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./"[gui,rag,code_interpreter,mcp]"For DashScope, set DASHSCOPE_API_KEY. The GUI requires Python 3.10 or later. Before using the built-in code interpreter, install and run Docker locally.
How do you use this agent?
Configure llm_cfg, for example {'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'}, and provide DASHSCOPE_API_KEY through the environment; alternatively, set model, model_server, and api_key for a compatible service such as vLLM or Ollama. Import Assistant from qwen_agent.agents, supply llm, system_message, function_list, and optional files, then iterate over the streamed output from bot.run(messages=messages). Custom tools should subclass BaseTool, be registered with @register_tool, and be named in function_list. To launch a browser UI, run from qwen_agent.gui import WebUI; WebUI(bot).run(). MCP examples also require their server commands to be runnable; the SQLite example lists Node.js, uv 0.4.18+, Git, and SQLite.
What are this agent's strengths and limitations?
- It offers three concrete extension layers—BaseChatModel, BaseTool, and Agent—so teams can assemble Assistant or implement their own Agent subclass.
- Its default function-calling template natively supports parallel function calls, with documented examples for multi-step and multi-turn tool calling.
- Optional components cover a Gradio WebUI, RAG, MCP, and Docker-based code execution within one framework.
- It supports both DashScope and model_server connections to OpenAI API-compatible services, with vLLM and Ollama named as examples.
- The DashScope path requires DASHSCOPE_API_KEY, while the self-hosted path requires operating and maintaining a model service.
- Code Interpreter depends on local Docker, and the documentation says its isolation is basic and should be used cautiously in production.
- The GUI requires Python 3.10 or later.
- MCP examples depend on external MCP servers and their runtimes; the SQLite example involves Node.js, uv, Git, and SQLite.
How does this agent compare with similar options?
For model serving, the documented choices are DashScope or a self-hosted OpenAI API-compatible service, with vLLM and Ollama given as examples. For Qwen3, the README recommends Qwen-Agent parsing vLLM tool outputs; for Qwen3-Coder, it recommends vLLM’s built-in tool parsing together with use_raw_api.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Qwen-Agent This agent | 42 · Major gaps | Library / SDKFree + model costs | ★ 17k | 8mo ago | Python | — |
| Functionary: Conversational LLM for Controlled Tool Use | 30 · Major gaps | Self-hosted serviceFree | ★ 1.6k | 4mo ago | Python | OpenAI API |
| OrchestKit AI Development Toolkit | 86 · Good | Agent plugin / skillFree + model costs | ★ 299 | today | TypeScript | Claude Code |
| Dive into LangGraph | 69 · Some gaps | Library / SDKFree + model costs | ★ 468 | 1mo ago | Jupyter Notebook | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: The code interpreter tool is based on Docker containers, but the README explicitly warns 'python executor is not sandboxed' and cautions against production use, indicating insufficient privilege control. No user confirmation mechanism is present; tool calls are triggered automatically by the LLM. Data flow transparency is limited; README mentions API key environment variables but does not detail data flow. Sensitive data handling: API keys are passed via environment variables, but no encryption or protection measures are described. Dependency security is not mentioned; no dependency audit or vulnerability scanning. External effects: code interpreter can execute arbitrary code, but with limitations. Rollback mechanism is absent. Source attribution: code has copyright notices, but third-party component origins are not clearly identified.
Evidence: README and example code are consistent, API design is self-consistent. Dependency availability: relies on external services like DashScope, Docker, Node.js, but no version pinning or images. Failure messages: tests have assertions, but no user-friendly error prompts.
Evidence: Targets developers, provides multiple scenario examples (RAG, MCP, code interpreter). Capability boundaries are described, e.g., code interpreter is not sandboxed. Trigger precision: tool calls are determined by LLM, but no precise control mechanism. Environment fit: supports multiple model services (DashScope, vLLM, Ollama), but depends on specific environments.
Evidence: README structure is clear, with installation instructions, FAQ, examples. Naming is stable, but no version history. Known limitations are mentioned (e.g., code interpreter not sandboxed). License is Apache-2.0, complete. Changelog is absent, maintenance responsibility is not clear.
Evidence: Output is streaming text, high usability. Marginal value is high, provides multiple features. Cost-benefit: depends on external APIs and Docker, cost not assessed.
Evidence: Claims in README are partially supported by examples, but no independent verification. Cross-source corroboration is limited, relying only on own documentation. Fact-inference separation is not clear.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Code interpreter is not sandboxed; use with caution in production.
- No user confirmation mechanism; tool calls may execute automatically.
- Relies on external services; ensure API key security.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
- bugfix: support set sse_read_timeout and automatic reconnection for mcpView on GitHub ↗ -
Release notes excerpt
- support streamable-http for mcp - change license to apache 2.0View on GitHub ↗ -
Release notes excerpt
- allow tool response to be empty string - add a fallback for invalid tool call output - support resource in mcp server as tool - support transformers models, audio input, and fix openvinoView on GitHub ↗