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 implementacion de referencia del tool calling de estos modelos, asi que evitas adivinar el formato correcto de las llamadas. En esta guia veras que es Qwen-Agent, como funciona su function calling, un agente de ejemplo, la ejecucion de código con RAG y como conectarlo a modelos que ejecutes en tu propia maquina. La misma explicacion esta disponible en ingles.

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 version 0.0.34, publicada el 16 de febrero de 2026 junto con Qwen3.5.
  • Esta pensado para modelos Qwen 3.0 o superior (Qwen3, Qwen3.5, Qwen3-Coder, QwQ-32B) y ofrece cuatro capacidades de serie: function calling, interprete de código en sandbox, RAG sobre documentos largos y cliente MCP.
  • La documentacion lo describe como la implementacion canonica del function calling de Qwen3: encapsula por dentro las plantillas y el analizador de las llamadas a herramientas, asi que no tienes que parsear la salida a mano.
  • Recomienda el estilo Hermes para las llamadas a herramientas en Qwen3, en lugar de los metodos basados en palabras de parada como ReAct, que pueden cortar antes de tiempo a los modelos con razonamiento.
  • Funciona igual en la nube (a traves de DashScope) y en modelos que sirvas de forma local con vLLM, SGLang u Ollama mediante un endpoint compatible con la API de OpenAI.

¿Que 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 funcion, el texto que genera sigue un formato concreto (que tokens marcan el inicio de la llamada, como se serializan los argumentos). Si usas un framework generico, 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 fabrica, porque lo definen los mismos que entrenaron el modelo.

El proyecto es software libre bajo licencia Apache-2.0, reune mas de 16.800 estrellas en GitHub y va por la version 0.0.34, publicada el 16 de febrero de 2026 el mismo dia 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  -> recuperacion sobre documentos largos
#  code_interpreter -> ejecucion de código en sandbox
#  mcp  -> cliente del Model Context Protocol

¿Como 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 funcion en lugar de limitarse a responder texto. Tu describes las herramientas disponibles, el modelo decide cuando y con que argumentos invocarlas, tu ejecutas la funcion y le devuelves el resultado para que continue.

La documentacion oficial es tajante: Qwen-Agent contiene «la implementacion canonica del function calling de Qwen3». En la practica significa que la biblioteca encapsula por dentro tanto la plantilla que se envia al modelo como el analizador que convierte su salida en un objeto estructurado con el nombre de la funcion y sus argumentos en JSON. Tu 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 metodos basados en palabras de parada como ReAct. La razon es sutil pero importante: los modelos con razonamiento generan pensamientos intermedios, y un analizador que corta al ver ciertas palabras puede terminar la generacion antes de tiempo. El estilo Hermes delimita las llamadas con etiquetas claras y evita ese problema. Si te interesa el tema mas alla de Qwen, ese mismo formato Hermes es el que usan otros modelos abiertos preparados para actuar como agentes.

Instalacion 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 cuestion de subclasear BaseTool y registrarla con el decorador @register_tool. Este ejemplo, adaptado del repositorio, crea una herramienta ficticia de generacion de imagenes y se la ofrece al agente junto al interprete 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 descripcion de texto.'
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': 'Descripcion 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 si 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. Tu no orquestas esos pasos; solo declaras las herramientas y Qwen-Agent gestiona el ida y vuelta.

¿Que aportan la ejecucion de código y el RAG?

Mas alla de las funciones que escribas tu, Qwen-Agent trae dos herramientas de serie que resuelven la mayoria de los casos reales. La primera es el interprete de código (code_interpreter): un sandbox donde el agente escribe y ejecuta Python para calcular, dibujar graficas 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 aplicacion de ejemplo Code Interpreter que incluye el proyecto.

La segunda es la recuperacion (RAG). Qwen-Agent puede indexar documentos largos (PDF, Word, paginas 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 patron que usarias con una base de datos vectorial, pero empaquetado y listo para conectar a un Assistant con una linea. 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 actua sobre servicios reales.

¿Como usar Qwen-Agent con modelos locales?

Aqui esta 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 direccion 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 identico al de la nube: solo cambia el bloque llm_cfg. Asi puedes prototipar contra la API gestionada y luego migrar a Ollama o a vLLM en produccion sin reescribir la logica del agente. Para tareas de function calling exigentes conviene un modelo mediano (Qwen3-8B o superior); los mas pequeños aciertan menos con los argumentos.

Preguntas frecuentes

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

En el origen. LangChain y LlamaIndex son frameworks genericos que admiten muchos modelos y deben adaptar el formato de las llamadas a cada uno. Qwen-Agent lo mantiene el equipo que entrena Qwen, asi que trae la implementacion 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 generico te dara mas 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 maquina, la api_key es literalmente 'EMPTY' y no pagas por token.

¿Con que 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, ademas de la serie Qwen2.5. Para el function calling, cuanto mayor es el modelo mas fiable es la eleccion de argumentos, asi que para agentes en produccion conviene evitar las variantes mas pequeñas.

Conclusion

Qwen-Agent es la via mas 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 implementacion canonica del function calling, el interprete de código, RAG y MCP listos para conectar, y funciona igual en la nube que con modelos que sirvas en tu propia maquina. 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, documentacion 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, documentacion oficial de Qwen
  3. Blog del equipo Qwen
  4. Paquete qwen-agent en PyPI

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