Qwen-Agent is the Qwen team’s official framework for turning their models into tool-using agents: they call functions, run code, query documents and speak MCP. Because it comes from the same authors who train Qwen, it ships the reference implementation of tool calling for these models, so you avoid guessing the right call format. In this guide you will see what Qwen-Agent is, how its function calling works, a worked agent example, code execution with RAG and how to point it at models you run on your own machine. The same explanation is available in Spanish.

Key takeaways

  • Qwen-Agent is an open-source Python framework (Apache-2.0 licence) built by the Qwen team itself; it has over 16,800 stars on GitHub and is on version 0.0.34, released on 16 February 2026 alongside Qwen3.5.
  • It targets models from Qwen 3.0 upward (Qwen3, Qwen3.5, Qwen3-Coder, QwQ-32B) and offers four capabilities out of the box: function calling, a sandboxed code interpreter, RAG over long documents and an MCP client.
  • The documentation describes it as the canonical implementation of Qwen3 function calling: it wraps the tool-call templates and parser internally, so you never parse the raw output by hand.
  • It recommends the Hermes style for tool calls on Qwen3, rather than stopword-based methods like ReAct, which can cut reasoning models off too early.
  • It works the same in the cloud (via DashScope) and against models you serve locally with vLLM, SGLang or Ollama through an OpenAI-compatible endpoint.

What is Qwen-Agent?

Qwen-Agent is, in its repository’s words, "a framework for developing LLM applications based on the instruction following, tool usage, planning, and memory capabilities of Qwen." In plain terms: it is the official toolbox for building agents on top of the Qwen models, maintained by the same Alibaba team that trains them.

That provenance is its biggest advantage. When an open model calls a function, the text it generates follows a specific format (which tokens mark the start of the call, how the arguments are serialised). With a generic framework you have to get that format right; get it wrong and the model hallucinates calls or the parser ignores them. Qwen-Agent brings the correct format out of the box, because it is defined by the very people who trained the model.

The project is free software under the Apache-2.0 licence, holds more than 16,800 stars on GitHub and is on version 0.0.34, released on 16 February 2026, the same day as Qwen3.5. It installs with a single command, picking the extras you need:

pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"

#  gui  -> Gradio web interface (needs Python 3.10+)
#  rag  -> retrieval over long documents
#  code_interpreter -> sandboxed code execution
#  mcp  -> Model Context Protocol client

How does Qwen’s native function calling work?

Function calling (or tool calling) is what lets a model ask for a function to run instead of just answering with text. You describe the available tools, the model decides when and with which arguments to invoke them, you run the function and return the result so it can continue.

The official documentation is blunt: Qwen-Agent holds "the canonical implementation of function calling for Qwen3." In practice that means the library wraps both the template sent to the model and the parser that turns its output into a structured object with the function name and its arguments in JSON. You never see that grunt work.

For Qwen3, the team recommends the Hermes-style call format "to maximise function calling performance," rather than stopword-based methods like ReAct. The reason is subtle but important: reasoning models generate intermediate thoughts, and a parser that stops at certain words can end the generation too early. The Hermes style delimits calls with clear tags and avoids that problem. If the topic interests you beyond Qwen, that same Hermes format is what other open, agent-ready models use.

Installation and a worked agent example

The central piece is the Assistant class: you pass it the model config and a list of tools, and it handles the call loop. Defining your own tool is a matter of subclassing BaseTool and registering it with the @register_tool decorator. This example, adapted from the repository, creates a mock image-generation tool and offers it to the agent alongside the code interpreter:

import json5
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool

@register_tool('generate_image')
class GenerateImage(BaseTool):
    description = 'Generate an image from a text description.'
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': 'Detailed description of the desired image.',
        'required': True,
    }]

    def call(self, params: str, **kwargs) -> str:
        prompt = json5.loads(params)['prompt']
        return json5.dumps({'image_url': f'https://.../{prompt}'})

llm_cfg = {'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'}

bot = Assistant(
    llm=llm_cfg,
    system_message='Draw an image and then process it.',
    function_list=['generate_image', 'code_interpreter'],
)

messages = [{'role': 'user', 'content': 'Draw a cat and make it grey'}]
for response in bot.run(messages=messages):
    print(response)

The model works out the sequence itself: first it calls generate_image with the prompt it drafted, receives the URL and then uses code_interpreter to download and transform it. You do not orchestrate those steps; you just declare the tools and Qwen-Agent manages the back and forth.

What do the code interpreter and RAG add?

Beyond the functions you write yourself, Qwen-Agent ships two built-in tools that cover most real cases. The first is the code interpreter (code_interpreter): a sandbox where the agent writes and runs Python to compute, draw charts or manipulate files. It relies on an isolated environment so the generated code never touches your system, and it is the basis of the Code Interpreter sample application the project includes.

The second is retrieval (RAG). Qwen-Agent can index long documents (PDF, Word, web pages) and let the agent query only the relevant fragments in each answer, instead of stuffing the whole document into the context. It is the same pattern you would use with a vector database, but packaged and ready to attach to an Assistant in one line. Together with the MCP client, which lets the agent talk to external tool servers, these pieces cover everything from a data assistant to an agent that browses and acts on real services.

How do you use Qwen-Agent with local models?

Here is the part that matters to anyone who wants privacy or zero API cost. Qwen-Agent does not tie you to Alibaba’s cloud: it accepts any OpenAI-compatible endpoint. You serve the model with vLLM, SGLang or Ollama and pass the address to the agent. The config changes from qwen_dashscope to a model_server pointing at your server:

from qwen_agent.agents import Assistant

# Model served locally, e.g. with vLLM on port 8000
llm_cfg = {
    'model': 'Qwen/Qwen3-8B',
    'model_server': 'http://localhost:8000/v1',
    'api_key': 'EMPTY',
}

bot = Assistant(llm=llm_cfg, function_list=['code_interpreter'])

messages = [{'role': 'user', 'content': 'Compute 12 factorial'}]
for response in bot.run(messages=messages):
    print(response)

The rest of the code (tools, Assistant, the run loop) is identical to the cloud version: only the llm_cfg block changes. So you can prototype against the managed API and then migrate to Ollama or vLLM in production without rewriting the agent logic. For demanding function-calling tasks a mid-sized model (Qwen3-8B or above) is advisable; the smaller ones get the arguments wrong more often.

Frequently asked questions

How is Qwen-Agent different from LangChain or LlamaIndex?

In its origin. LangChain and LlamaIndex are generic frameworks that support many models and must adapt the call format to each one. Qwen-Agent is maintained by the team that trains Qwen, so it ships the reference implementation of tool calling for these models and usually gets new features first. If you work exclusively with Qwen, that affinity reduces format errors; if you need to swap models often, a generic framework gives you more flexibility.

Do I need an Alibaba API key to use it?

No, it is not mandatory. You can use DashScope with an Alibaba key for the cloud models, but Qwen-Agent works just as well against any OpenAI-compatible endpoint. If you serve Qwen with vLLM or Ollama on your own machine, the api_key is literally 'EMPTY' and you pay nothing per token.

Which Qwen models does it work with?

With the Qwen 3.0 family and later: Qwen3, Qwen3.5, the code variant Qwen3-Coder and the QwQ-32B reasoning model, plus the Qwen2.5 series. For function calling, the larger the model the more reliable its choice of arguments, so for production agents it is best to avoid the smallest variants.

Conclusion

Qwen-Agent is the most direct way to turn a Qwen model into an AI agent that uses real tools. Its trump card is provenance: coming from the Qwen team itself, it ships the canonical function-calling implementation, the code interpreter, RAG and MCP ready to plug in, and it works the same in the cloud as with models you serve on your own machine. The next step is to install it with pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]", write your first tool with @register_tool and point it at a Qwen3 served with Ollama to test the full loop at no API cost.

Sources: [1] Qwen-Agent on GitHub[1], [2] Function Calling, official Qwen documentation[2], [3] Qwen team blog[3], [4] qwen-agent package on PyPI[4].

Visitas: 0

Sources

  1. Qwen-Agent on GitHub
  2. Function Calling, official Qwen documentation
  3. Qwen team blog
  4. qwen-agent package on PyPI

Route: Self-hosted Agentic Models and Tool Calling