Qwen-Agent

Un marco para desarrollar aplicaciones LLM con capacidades como uso de herramientas, planificación y memoria, basado en el modelo Qwen.

GitHub
17.1k
Prueba este MCPPatrocinado

Documentación

中文 ｜ English


💜 Qwen Chat   |   🤗 Hugging Face   |   🤖 ModelScope   |    📑 Blog    ｜   📖 Documentación
📊 Benchmark   |   💬 WeChat (微信)   |   🫨 Discord  

Qwen-Agent es un framework para desarrollar aplicaciones de LLM basado en las capacidades de seguimiento de instrucciones, uso de herramientas, planificación y memoria de Qwen. También incluye aplicaciones de ejemplo como Browser Assistant, Code Interpreter y Custom Assistant. Ahora Qwen-Agent actúa como el backend de Qwen Chat.

Noticias

  • 🔥🔥🔥16 de febrero de 2026: Publicamos el código de Qwen3.5. Para ejemplos de uso, consulte Qwen3.5 Agent Demo.
  • 27 de enero de 2026: Publicamos el benchmark de evaluación de agentes DeepPlanning y añadimos la documentación de Qwen-Agent.
  • 23 de septiembre de 2025: Añadimos Qwen3-VL Tool-call Demo, que admite herramientas como zoom, búsqueda de imágenes y búsqueda web.
  • 23 de julio de 2025: Añadimos Qwen3-Coder Tool-call Demo; se añadió soporte para la interfaz nativa de llamada a herramientas de la API, como el uso del análisis de llamadas a herramientas integrado de vLLM.
  • 1 de mayo de 2025: Añadimos Qwen3 Tool-call Demo y MCP Cookbooks.
  • 18 de marzo de 2025: Soporte para el campo reasoning_content; ajustamos la plantilla de Function Call predeterminada, que es aplicable a los modelos generales de la serie Qwen2.5 y a QwQ-32B. Si necesita usar la versión anterior de la plantilla, consulte el ejemplo para pasar parámetros.
  • 7 de marzo de 2025: Añadimos QwQ-32B Tool-call Demo. Admite llamadas a herramientas paralelas, de varios pasos y de varios turnos.
  • 3 de diciembre de 2024: Actualizamos la GUI a la versión basada en Gradio 5. Nota: la GUI requiere Python 3.10 o superior.
  • 18 de septiembre de 2024: Añadimos Qwen2.5-Math Demo para mostrar las capacidades de razonamiento integrado con herramientas de Qwen2.5-Math. Nota: el ejecutor de Python no está aislado y está destinado solo para pruebas locales, no para uso en producción.

Primeros pasos

Instalación

  • Instale la versión estable desde PyPI:
pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"
# Or use `pip install -U qwen-agent` for the minimal requirements.
# The optional requirements, specified in double brackets, are:
#   [gui] for Gradio-based GUI support;
#   [rag] for RAG support;
#   [code_interpreter] for Code Interpreter support;
#   [mcp] for MCP support.
  • Alternativamente, puede instalar la última versión de desarrollo desde el código fuente:
git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./"[gui,rag,code_interpreter,mcp]"
# Or `pip install -e ./` for minimal requirements.

Preparación: Servicio de modelos

Puede usar el servicio de modelos proporcionado por DashScope de Alibaba Cloud, o implementar y usar su propio servicio de modelos con los modelos Qwen de código abierto.

  • Si elige usar el servicio de modelos ofrecido por DashScope, asegúrese de establecer la variable de entorno DASHSCOPE_API_KEY con su clave de API única de DashScope.

  • Alternativamente, si prefiere implementar y usar su propio servicio de modelos, siga las instrucciones del README de Qwen2 para implementar un servicio de API compatible con OpenAI. En concreto, consulte la sección vLLM para implementación en GPU de alto rendimiento o la sección Ollama para implementación local en CPU (+GPU). Para los modelos QwQ y Qwen3, se recomienda no añadir los parámetros --enable-auto-tool-choice y --tool-call-parser hermes, ya que Qwen-Agent analizará las salidas de herramientas de vLLM por sí mismo. Para Qwen3-Coder, se recomienda habilitar ambos parámetros, usar el análisis de herramientas integrado de vLLM y combinarlo con el uso del parámetro use_raw_api.

Desarrollando su propio agente

Qwen-Agent ofrece componentes atómicos, como LLMs (que heredan de class BaseChatModel y vienen con llamada a funciones) y Herramientas (que heredan de class BaseTool), junto con componentes de alto nivel como Agentes (derivados de class Agent).

El siguiente ejemplo ilustra el proceso de crear un agente capaz de leer archivos PDF y utilizar herramientas, así como incorporar una herramienta personalizada:

import pprint
import urllib.parse
import json5
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool
from qwen_agent.utils.output_beautify import typewriter_print


# Step 1 (Optional): Add a custom tool named `my_image_gen`.
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
    # The `description` tells the agent the functionality of this tool.
    description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'
    # The `parameters` tell the agent what input parameters the tool has.
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': 'Detailed description of the desired image content, in English',
        'required': True
    }]

    def call(self, params: str, **kwargs) -> str:
        # `params` are the arguments generated by the LLM agent.
        prompt = json5.loads(params)['prompt']
        prompt = urllib.parse.quote(prompt)
        return json5.dumps(
            {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
            ensure_ascii=False)


# Step 2: Configure the LLM you are using.
llm_cfg = {
    # Use the model service provided by DashScope:
    'model': 'qwen-max-latest',
    'model_type': 'qwen_dashscope',
    # 'api_key': 'YOUR_DASHSCOPE_API_KEY',
    # It will use the `DASHSCOPE_API_KEY' environment variable if 'api_key' is not set here.

    # Use a model service compatible with the OpenAI API, such as vLLM or Ollama:
    # 'model': 'Qwen2.5-7B-Instruct',
    # 'model_server': 'http://localhost:8000/v1',  # base_url, also known as api_base
    # 'api_key': 'EMPTY',

    # (Optional) LLM hyperparameters for generation:
    'generate_cfg': {
        'top_p': 0.8
    }
}

# Step 3: Create an agent. Here we use the `Assistant` agent as an example, which is capable of using tools and reading files.
system_instruction = '''After receiving the user's request, you should:
- first draw an image and obtain the image url,
- then run code `request.get(image_url)` to download the image,
- and finally select an image operation from the given document to process the image.
Please show the image using `plt.show()`.'''
tools = ['my_image_gen', 'code_interpreter']  # `code_interpreter` is a built-in tool for executing code. For configuration details, please refer to the FAQ.
files = ['./examples/resource/doc.pdf']  # Give the bot a PDF file to read.
bot = Assistant(llm=llm_cfg,
                system_message=system_instruction,
                function_list=tools,
                files=files)

# Step 4: Run the agent as a chatbot.
messages = []  # This stores the chat history.
while True:
    # For example, enter the query "draw a dog and rotate it 90 degrees".
    query = input('\nuser query: ')
    # Append the user query to the chat history.
    messages.append({'role': 'user', 'content': query})
    response = []
    response_plain_text = ''
    print('bot response:')
    for response in bot.run(messages=messages):
        # Streaming output.
        response_plain_text = typewriter_print(response, response_plain_text)
    # Append the bot responses to the chat history.
    messages.extend(response)

Además de usar implementaciones de agentes integradas como class Assistant, también puede desarrollar su propia implementación de agente heredando de class Agent.

El framework también proporciona una interfaz GUI conveniente, que admite el despliegue rápido de Demos de Gradio para Agentes. Por ejemplo, en el caso anterior, puede lanzar rápidamente una Demo de Gradio con el siguiente código:

from qwen_agent.gui import WebUI
WebUI(bot).run()  # bot is the agent defined in the above code, we do not repeat the definition here for saving space.

Ahora puede chatear con el Agente en la interfaz web. Consulte el directorio de ejemplos para más ejemplos de uso.

Preguntas frecuentes

¿Cómo usar la herramienta Code Interpreter?

Implementamos una herramienta de intérprete de código basada en contenedores Docker locales. Puede habilitar la herramienta integrada code interpreter para su agente, permitiéndole escribir código de forma autónoma según escenarios específicos, ejecutarlo de forma segura en un entorno de sandbox aislado y devolver los resultados de la ejecución.

⚠️ Nota: Antes de usar esta herramienta, asegúrese de que Docker esté instalado y en ejecución en su sistema operativo local. El tiempo necesario para construir la imagen del contenedor por primera vez depende de sus condiciones de red. Para instrucciones de instalación y configuración de Docker, consulte la documentación oficial.

¿Cómo usar MCP?

Puede seleccionar las herramientas necesarias en el sitio web de servidores MCP de código abierto y configurar el entorno correspondiente.

Ejemplo de formato de invocación de MCP:

{
    "mcpServers": {
        "memory": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-memory"]
        },
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
        },
        "sqlite" : {
            "command": "uvx",
            "args": [
                "mcp-server-sqlite",
                "--db-path",
                "test.db"
            ]
        }
    }
}

Para más detalles, puede consultar el ejemplo de uso de MCP

Las dependencias necesarias para ejecutar este ejemplo son las siguientes:

# Node.js (Download and install the latest version from the Node.js official website)
# uv 0.4.18 or higher (Check with uv --version)
# Git (Check with git --version)
# SQLite (Check with sqlite3 --version)

# For macOS users, you can install these components using Homebrew:
brew install uv git sqlite3

# For Windows users, you can install these components using winget:
winget install --id=astral-sh.uv -e
winget install git.git sqlite.sqlite

¿Tiene llamada a funciones (también conocida como llamada a herramientas)?

Sí. Las clases LLM proporcionan llamada a funciones. Además, algunas clases de Agente también se basan en la capacidad de llamada a funciones, por ejemplo, FnCallAgent y ReActChat.

La plantilla de llamada a herramientas predeterminada actual admite de forma nativa llamadas a funciones paralelas.

¿Cómo pasar parámetros de LLM al Agente?

llm_cfg = {
    # The model name being used:
    'model': 'qwen3-32b',
    # The model service being used:
    'model_type': 'qwen_dashscope',
    # If 'api_key' is not set here, it will default to reading the `DASHSCOPE_API_KEY` environment variable:
    'api_key': 'YOUR_DASHSCOPE_API_KEY',

    # Using an OpenAI API compatible model service, such as vLLM or Ollama:
    # 'model': 'qwen3-32b',
    # 'model_server': 'http://localhost:8000/v1',  # base_url, also known as api_base
    # 'api_key': 'EMPTY',

    # (Optional) LLM hyperparameters:
    'generate_cfg': {
        # This parameter will affect the tool-call parsing logic. Default is False:
          # Set to True: when content is `<think>this is the thought</think>this is the answer`
          # Set to False: when response consists of reasoning_content and content
        # 'thought_in_content': True,

        # tool-call template: default is nous (recommended for qwen3):
        # 'fncall_prompt_type': 'nous'

        # Maximum input length, messages will be truncated if they exceed this length, please adjust according to model API:
        # 'max_input_tokens': 58000

        # Parameters that will be passed directly to the model API, such as top_p, enable_thinking, etc., according to the API specifications:
        # 'top_p': 0.8

        # Using the API's native tool call interface
        # 'use_raw_api': True,
    }
}

¿Cómo hacer preguntas y respuestas sobre documentos súper largos que involucran 1M de tokens?

Hemos publicado una solución RAG rápida, así como un agente caro pero competitivo, para hacer preguntas y respuestas sobre documentos súper largos. Han logrado superar a los modelos nativos de contexto largo en dos benchmarks desafiantes mientras son más eficientes, y se desempeñan perfectamente en la prueba de presión de "aguja en el pajar" de una sola aguja que involucra contextos de 1M de tokens. Consulte el blog para detalles técnicos.

Aplicación: BrowserQwen

BrowserQwen es un asistente de navegador construido sobre Qwen-Agent. Consulte su documentación para más detalles.

Aviso legal

El intérprete de código basado en contenedores Docker monta solo el directorio de trabajo especificado e implementa un aislamiento básico de sandbox, pero aún debe usarse con precaución en entornos de producción.