# Qwen-Agent: A Python Framework for Tool-Calling Qwen Applications

> Qwen-Agent is the Python framework behind Qwen Chat, packaging function calling, RAG, a code interpreter and MCP support into atomic LLM and Tool classes. The install is one pip command, but the framework assumes you already have a Qwen model endpoint.

**QwenLM/Qwen-Agent** — Agent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.

- Repository: https://github.com/QwenLM/Qwen-Agent
- Website: https://pypi.org/project/qwen-agent/
- Stars: 17,136 · Forks: 1,737
- Language: Python
- License: Apache-2.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/qwenlm-qwen-agent

## What Qwen-Agent solves, and who it is actually for

Qwen-Agent is a framework for building LLM applications on top of Qwen's instruction following, tool usage, planning and memory behaviour. That sentence from the README is a fair summary of the scope: it is not a chatbot product, and it is not a model. It is the layer between a Qwen endpoint and an application that needs to call tools, read documents, or run code.

The audience is Python developers who have already picked Qwen as their model. The repository ships atomic components (LLMs inheriting from BaseChatModel, Tools inheriting from BaseTool) plus higher-level Agents derived from class Agent, and it also ships example applications: Browser Assistant, Code Interpreter, Custom Assistant. The README states that Qwen-Agent now plays the backend role for Qwen Chat, which tells you the framework is exercised by a production surface, though that says nothing about whether your particular deployment will behave the same way.

The strongest signal about intended use is the extras list in the install command. gui, rag, code_interpreter and mcp are separate dependency groups, so a minimal install pulls only what a plain function-calling agent needs. If you want a Gradio interface, you take [gui]. If you want retrieval, you take [rag]. That packaging choice is a reasonable proxy for how the maintainers think about the project: a core loop plus optional capabilities, rather than one monolithic stack.

## How the agent loop is assembled from BaseChatModel and BaseTool

The architecture visible in the repository is compositional. You register a tool, describe it, and let the LLM produce the arguments. The README's custom tool example makes the contract explicit: a BaseTool subclass declares a description string and a parameters list, and the call method receives params as a string that the agent generated. The example parses those params with json5 and reads the prompt field out of the resulting object.

That string-in, string-out signature is worth pausing on. The tool does not receive a typed Python object. It receives whatever the model emitted, which is why the example uses json5 rather than the standard library json parser: models produce slightly malformed JSON often enough that lenient parsing is the pragmatic default. Your call method is responsible for validating anything it depends on.

Above the tools sits the Agent. The README describes Agents as derived from class Agent and shows qwen_agent.agents.Assistant as the concrete entry point for a PDF-reading, tool-using assistant. LLM parameters are passed through the agent rather than configured on the model object directly, and the README references a use_raw_api parameter for the case where you want vLLM's built-in tool-call parsing instead of Qwen-Agent's own parsing. That switch matters: the README recommends not enabling --enable-auto-tool-choice and --tool-call-parser hermes for QwQ and Qwen3, because Qwen-Agent parses tool outputs from vLLM itself, while for Qwen3-Coder it recommends enabling both and combining them with use_raw_api. Getting this wrong is a silent failure mode, not a loud one.

## Installing Qwen-Agent and running a first tool-calling agent

The README gives two install paths. The stable release comes from PyPI with the extras you need selected in brackets:

```bash
pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"
# Or use `pip install -U qwen-agent` for the minimal requirements.
```

A minimal install is `pip install -U qwen-agent`. The extras are documented in the README as [gui] for Gradio-based GUI support, [rag] for RAG support, [code_interpreter] for Code Interpreter support, and [mcp] for MCP support. If you prefer the development version, the README clones the repository, changes into it, and installs editable with the same extras:

```bash
git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./"[gui,rag,code_interpreter,mcp]"
```

Before any agent runs, you need a model service. The README offers two options. The first is DashScope, Alibaba Cloud's model service, which requires the environment variable DASHSCOPE_API_KEY to be set to your key. The second is deploying Qwen yourself behind an OpenAI-compatible API, with vLLM recommended for high-throughput GPU deployment and Ollama for local CPU (plus GPU) deployment. Setting that variable is described in the README as setting DASHSCOPE_API_KEY to your unique DashScope API key.

With the key in place, the first real use is the custom tool pattern from the README. You subclass BaseTool, decorate it with register_tool, and give the agent a description and a parameters list. The README's MyImageGen example does exactly this: the description tells the agent what the tool does, parameters declares a single required prompt string, and call parses the model's arguments. The surrounding example builds an Assistant that can read PDF files and use that tool, and prints output through typewriter_print from qwen_agent.utils.output_beautify. What you should see when it works is the agent selecting the tool, emitting a JSON argument string, and your call method returning a URL that gets folded back into the response.

## The code interpreter is not sandboxed, and the README says so

The most consequential limitation is stated plainly in the news entry dated Sep 18, 2024, alongside the Qwen2.5-Math demo: the python executor is not sandboxed and is intended for local testing only, not for production use. That is not a caveat buried in a footnote. It is the project telling you that the code_interpreter extra, which is the feature most likely to attract a team, does not come with isolation.

If your use case involves executing model-generated code against real data, on a machine that can reach anything you care about, Qwen-Agent is the wrong tool as shipped. You would need to supply your own execution boundary, and the README does not document one. The same news entry frames the demo as a showcase of Tool-Integrated Reasoning for Qwen2.5-Math, so the intended context is evaluation, not deployment.

A second constraint is model coupling. The default Function Call template was adjusted on 2025-03-18 to suit the Qwen2.5 series general models and QwQ-32B, and the README notes that using the old template requires passing parameters as shown in examples/function_calling.py. Anyone upgrading across that date and running an older Qwen model should expect to change code. The framework is built for Qwen first; pointing it at a non-Qwen model is not covered by the README's preparation section, which names only DashScope and self-hosted Qwen.

## Qwen-Agent compared with LangGraph

LangGraph and Qwen-Agent both let you build agents that call tools, but they disagree about where the structure lives. LangGraph models an application as an explicit graph of nodes and edges, so control flow is something you write down and can inspect. Qwen-Agent instead gives you an Agent class that owns the loop, with BaseTool subclasses plugged in through a registry decorator. The README's example never describes a graph; it describes a tool, its parameters, and the call method that services it.

That difference decides which one fits. If your workflow has branches, retries, human checkpoints and a topology you want to reason about independently of the model, an explicit graph is the more honest representation. If your workflow is "give the model tools and let it decide," Qwen-Agent's registry approach is less ceremony, and the function-call template is tuned for Qwen specifically. The trade-off is visibility: with Qwen-Agent, the sequencing lives inside the model's decisions and the framework's prompt templates, and the README does not document a way to render that plan before execution.

The comparison also runs through the model layer. Qwen-Agent's preparation section assumes DashScope or a self-hosted Qwen served through vLLM or Ollama, and its parser recommendations are written per Qwen model family. A framework that is model-agnostic by design will not have that guidance, nor that coupling.

## Maintenance, releases and what the Apache-2.0 licence means here

The repository is not archived, and the last push was on 2026-03-04. The most recent tagged release listed is v0.0.26 on 2025-05-29, with v0.0.25 and v0.0.24 in the two weeks before it. That gap between the latest tag and the latest push is worth noting: commits continue, but the version numbers in the 0.0.x line suggest the project does not treat releases as a stability contract. Pin a version in your requirements file rather than tracking the tip of main.

The upgrade cost concentrates in two places. Function-call templates have changed before, as the 2025-03-18 entry shows, and the README keeps an example for the old behaviour. Model-family support is added continuously, with news entries for Qwen3, Qwen3-Coder, Qwen3-VL, QwQ-32B and Qwen3.5 appearing across 2025 and 2026. Each addition can shift what the recommended vLLM flags are, so a deployment that hardcodes --tool-call-parser hermes for every model will eventually be wrong for one of them.

The licence is Apache-2.0, and the README carries the standard copyright notice for the Qwen team at Alibaba Group. Apache-2.0 is permissive, but the README's notice explicitly disclaims warranties and limits liability, and the bundled qwen.tiktoken and tool resource files are shipped as package data under the same terms. If you redistribute Qwen-Agent inside a product, read the LICENSE file in the repository and the notices for any model weights you serve alongside it. That is a question for your own counsel, not something this article can settle.

## Conclusion

Adopt Qwen-Agent if you are building Python agents on Qwen models and want function calling, RAG and MCP behind one Agent class, and if you already have a DashScope key or a self-hosted OpenAI-compatible Qwen endpoint. Do not adopt it if you need a sandboxed code executor in production: the README says the python executor is not sandboxed and is for local testing only. Before writing code, verify which extras you need (gui, rag, code_interpreter, mcp) and check whether your target model requires the old function-call template, because the default changed on 2025-03-18.

## FAQ

### Does Qwen have an agent?

Yes. Qwen-Agent is a framework for developing LLM applications based on the instruction following, tool usage, planning and memory capabilities of Qwen, and the README states it now plays the backend role for Qwen Chat.

### How do I install Qwen-Agent?

Install the stable version from PyPI with pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]", or use pip install -U qwen-agent for the minimal requirements. The bracketed extras select Gradio GUI, RAG, Code Interpreter and MCP support respectively.

### How do I use Qwen-Agent in my own application?

The README's example registers a custom tool by subclassing BaseTool with a description and parameters list, then builds a qwen_agent.agents.Assistant that can read PDF files and call that tool. The tool's call method receives the model-generated arguments as a string, which the example parses with json5.

### Is Qwen-Agent free?

The framework itself is released under the Apache-2.0 licence, so the code is free to use under those terms. Running it still requires a model service: either DashScope with a DASHSCOPE_API_KEY, or your own self-hosted Qwen deployment.

### Who develops Qwen-Agent?

The repository is QwenLM/Qwen-Agent, the licence header names the Qwen team at Alibaba Group, and setup.py lists the author as Qwen Team with an alibaba-inc.com contact address.

## Sources

- [License: Apache-2.0](https://github.com/QwenLM/Qwen-Agent/blob/main/LICENSE)
- [Project website](https://pypi.org/project/qwen-agent/)
- [QwenLM/Qwen-Agent on GitHub](https://github.com/QwenLM/Qwen-Agent)
- [README](https://github.com/QwenLM/Qwen-Agent/blob/main/README.md)
- [Releases](https://github.com/QwenLM/Qwen-Agent/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/qwenlm-qwen-agent