Qwen-Agent es el framework oficial del equipo Qwen para convertir sus modelos en agentes que usan herramientas: llaman a funciones, ejecutan código, consultan documentos y hablan MCP. Al venir de los mismos autores que entrenan Qwen, trae la implementación de referencia del tool calling de estos modelos, así que evitas adivinar el formato correcto de las llamadas. En esta guía verás qué es Qwen-Agent, cómo funciona su function calling, un agente de ejemplo, la ejecución de código con RAG y cómo conectarlo a modelos que ejecutes en tu propia máquina. La misma explicación está disponible en inglés.

Puntos clave

  • Qwen-Agent es un framework de Python de código abierto (licencia Apache-2.0) creado por el propio equipo Qwen; supera las 16.800 estrellas en GitHub y va por la versión 0.0.34, publicada el 16 de febrero de 2026 junto con Qwen3.5.
  • Está pensado para modelos Qwen 3.0 o superior (Qwen3, Qwen3.5, Qwen3-Coder, QwQ-32B) y ofrece cuatro capacidades de serie: function calling, intérprete de código en sandbox, RAG sobre documentos largos y cliente MCP.
  • La documentación lo describe como la implementación canónica del function calling de Qwen3: encapsula por dentro las plantillas y el analizador de las llamadas a herramientas, así que no tienes que parsear la salida a mano.
  • Recomienda el estilo Hermes para las llamadas a herramientas en Qwen3, en lugar de los métodos basados en palabras de parada como ReAct, que pueden cortar antes de tiempo a los modelos con razonamiento.
  • Funciona igual en la nube (a través de DashScope) y en modelos que sirvas de forma local con vLLM, SGLang u Ollama mediante un endpoint compatible con la API de OpenAI.

¿Qué es Qwen-Agent?

Qwen-Agent es, en palabras de su repositorio, «un framework para desarrollar aplicaciones con LLM basadas en la capacidad de seguir instrucciones, usar herramientas, planificar y recordar de Qwen». Traducido: es la caja de herramientas oficial para construir agentes sobre los modelos Qwen, mantenida por el mismo equipo de Alibaba que los entrena.

Esa procedencia es su mayor ventaja. Cuando un modelo abierto llama a una función, el texto que genera sigue un formato concreto (qué tokens marcan el inicio de la llamada, cómo se serializan los argumentos). Si usas un framework genérico, tienes que acertar con ese formato; si lo aciertas mal, el modelo alucina llamadas o el analizador las ignora. Qwen-Agent trae el formato correcto de fábrica, porque lo definen los mismos que entrenaron el modelo.

El proyecto es software libre bajo licencia Apache-2.0, reúne más de 16.800 estrellas en GitHub y va por la versión 0.0.34, publicada el 16 de febrero de 2026 el mismo día que Qwen3.5. Se instala con una sola orden, eligiendo los extras que necesites:

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

#  gui  -> interfaz web con Gradio (necesita Python 3.10+)
#  rag  -> recuperación sobre documentos largos
#  code_interpreter -> ejecución de código en sandbox
#  mcp  -> cliente del Model Context Protocol

¿Cómo funciona el function calling nativo de Qwen?

El function calling (o tool calling) es lo que permite a un modelo pedir que se ejecute una función en lugar de limitarse a responder texto. Tú describes las herramientas disponibles, el modelo decide cuándo y con qué argumentos invocarlas, tú ejecutas la función y le devuelves el resultado para que continúe.

La documentación oficial es tajante: Qwen-Agent contiene «la implementación canónica del function calling de Qwen3». En la práctica significa que la biblioteca encapsula por dentro tanto la plantilla que se envía al modelo como el analizador que convierte su salida en un objeto estructurado con el nombre de la función y sus argumentos en JSON. Tú no ves ese trabajo sucio.

Para Qwen3, el equipo recomienda el formato de llamada de estilo Hermes «para maximizar el rendimiento del function calling», en lugar de los métodos basados en palabras de parada como ReAct. La razón es sutil pero importante: los modelos con razonamiento generan pensamientos intermedios, y un analizador que corta al ver ciertas palabras puede terminar la generación antes de tiempo. El estilo Hermes delimita las llamadas con etiquetas claras y evita ese problema. Si te interesa el tema más allá de Qwen, ese mismo formato Hermes es el que usan otros modelos abiertos preparados para actuar como agentes.

Instalación y un agente de ejemplo

La pieza central es la clase Assistant: le pasas la configuración del modelo y una lista de herramientas, y ella se encarga del bucle de llamadas. Definir una herramienta propia es cuestión de subclasear BaseTool y registrarla con el decorador @register_tool. Este ejemplo, adaptado del repositorio, crea una herramienta ficticia de generación de imágenes y se la ofrece al agente junto al intérprete de código:

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

@register_tool('generar_imagen')
class GenerarImagen(BaseTool):
    description = 'Genera una imagen a partir de una descripción de texto.'
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': 'Descripción detallada de la imagen deseada.',
        '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='Dibuja una imagen y luego procesala.',
    function_list=['generar_imagen', 'code_interpreter'],
)

messages = [{'role': 'user', 'content': 'Dibuja un gato y ponlo en gris'}]
for response in bot.run(messages=messages):
    print(response)

El modelo decide por sí mismo la secuencia: primero llama a generar_imagen con el prompt que ha redactado, recibe la URL y después usa code_interpreter para descargarla y transformarla. Tú no orquestas esos pasos; solo declaras las herramientas y Qwen-Agent gestiona el ida y vuelta.

¿Qué aportan la ejecución de código y el RAG?

Más allá de las funciones que escribas tú, Qwen-Agent trae dos herramientas de serie que resuelven la mayoría de los casos reales. La primera es el intérprete de código (code_interpreter): un sandbox donde el agente escribe y ejecuta Python para calcular, dibujar gráficas o manipular archivos. Se apoya en un entorno aislado para que el código generado no toque tu sistema, y es la base de la aplicación de ejemplo Code Interpreter que incluye el proyecto.

La segunda es la recuperación (RAG). Qwen-Agent puede indexar documentos largos (PDF, Word, páginas web) y dejar que el agente consulte solo los fragmentos relevantes en cada respuesta, en lugar de meter el documento entero en el contexto. Es el mismo patrón que usarías con una base de datos vectorial, pero empaquetado y listo para conectar a un Assistant con una línea. Junto al cliente MCP, que permite al agente hablar con servidores de herramientas externos, estas piezas cubren desde un asistente de datos hasta un agente que navega y actúa sobre servicios reales.

¿Cómo usar Qwen-Agent con modelos locales?

Aquí está el punto que interesa a quien quiere privacidad o coste cero de API. Qwen-Agent no te ata a la nube de Alibaba: acepta cualquier endpoint compatible con la API de OpenAI. Sirves el modelo con vLLM, SGLang u Ollama, y le pasas la dirección al agente. La configuración cambia de qwen_dashscope a un model_server que apunta a tu servidor:

from qwen_agent.agents import Assistant

# Modelo servido de forma local, p. ej. con vLLM en el puerto 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': 'Calcula 12 factorial'}]
for response in bot.run(messages=messages):
    print(response)

El resto del código (herramientas, Assistant, bucle run) es idéntico al de la nube: solo cambia el bloque llm_cfg. Así puedes prototipar contra la API gestionada y luego migrar a Ollama o a vLLM en producción sin reescribir la lógica del agente. Para tareas de function calling exigentes conviene un modelo mediano (Qwen3-8B o superior); los más pequeños aciertan menos con los argumentos.

Preguntas frecuentes

¿En qué se diferencia Qwen-Agent de LangChain o LlamaIndex?

En el origen. LangChain y LlamaIndex son frameworks genéricos que admiten muchos modelos y deben adaptar el formato de las llamadas a cada uno. Qwen-Agent lo mantiene el equipo que entrena Qwen, así que trae la implementación de referencia del tool calling de estos modelos y suele estrenar antes las novedades. Si trabajas exclusivamente con Qwen, esa afinidad reduce errores de formato; si necesitas cambiar de modelo a menudo, un framework genérico te dará más flexibilidad.

¿Necesito una clave de API de Alibaba para usarlo?

No es obligatorio. Puedes usar DashScope con una clave de Alibaba para los modelos en la nube, pero Qwen-Agent funciona igual contra cualquier endpoint compatible con OpenAI. Si sirves Qwen con vLLM u Ollama en tu propia máquina, la api_key es literalmente 'EMPTY' y no pagas por token.

¿Con qué modelos Qwen funciona?

Con la familia Qwen 3.0 y posteriores: Qwen3, Qwen3.5, la variante de código Qwen3-Coder y el modelo de razonamiento QwQ-32B, además de la serie Qwen2.5. Para el function calling, cuanto mayor es el modelo más fiable es la elección de argumentos, así que para agentes en producción conviene evitar las variantes más pequeñas.

Conclusión

Qwen-Agent es la vía más directa para convertir un modelo Qwen en un agente de IA que usa herramientas de verdad. Su gran baza es la procedencia: al venir del propio equipo Qwen, trae la implementación canónica del function calling, el intérprete de código, RAG y MCP listos para conectar, y funciona igual en la nube que con modelos que sirvas en tu propia máquina. El siguiente paso es instalarlo con pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]", escribir tu primera herramienta con @register_tool y apuntarlo a un Qwen3 servido con Ollama para probar el bucle completo sin coste de API.

Fuentes: [1] Qwen-Agent en GitHub[1], [2] Function Calling, documentación oficial de Qwen[2], [3] Blog del equipo Qwen[3], [4] Paquete qwen-agent en PyPI[4].

Visitas: 0

Fuentes

  1. Qwen-Agent en GitHub
  2. Function Calling, documentación oficial de Qwen
  3. Blog del equipo Qwen
  4. Paquete qwen-agent en PyPI

Ruta: Modelos agénticos self-hosted y tool calling