API de Agentes Mistral: Una guía con proyecto de demostración

Mistral ha publicado la API de Agentes, un marco que facilita el desarrollo de agentes de IA inteligentes y autónomos capaces de realizar tareas complejas de varios pasos. Va más allá de los modelos lingüísticos tradicionales al integrar el uso de herramientas, la memoria persistente y las capacidades de orquestación.

En este tutorial, te explicaré cómo utilizar la API de Agentes Mistral para crear asistentes inteligentes capaces de:

• Utilizando herramientas como la búsqueda web, la ejecución de código y la generación de imágenes
• Retener la memoria en conversaciones largas para preservar el contexto
• Delegar tareas entre varios agentes

Aprenderás los conceptos básicos del marco agencial de Mistral, explorarás los conectores incorporados y las funciones de orquestación, y construirás un asistente multiagente que funcione.

Mantenemos a nuestros lectores al día de lo último en IA enviándoles The Median, nuestro boletín gratuito de los viernes que desglosa las noticias clave de la semana. Suscríbete y mantente alerta en sólo unos minutos a la semana:

¿Qué es la API de Agentes de Mistral?

La API de Agentes Mistral es un marco que permite a los grandes modelos lingüísticos realizar acciones de varios pasos, utilizar herramientas externas y mantener la memoria a través de las interacciones. A diferencia de las simples API de chat, capacita a los agentes de IA para:

• Acceder a la web, ejecutar código, generar imágenes o recuperar documentos
• Coordinarse con otros agentes mediante orquestación
• Mantener conversaciones persistentes con la memoria a largo plazo

Actualmente, sólo se admiten mistral-medium-latest (también conocido como mistral-medium-2505) y mistral-large-latest, pero es posible que pronto se admitan nuevos modelos.

Explicación de los conceptos básicos

Antes de pasar a la parte práctica, creo que es útil aclarar los conceptos básicos de la API de Agentes.

Fuente: Mistral AI

Agentes

Los agentes de Mistral son personas potenciadas por modelos y mejoradas con instrucciones predefinidas, acceso a herramientas y estado de la conversación:

• Las instrucciones guían el comportamiento del agente (por ejemplo, "Eres un entrenador nutricional que registra comidas").
• Herramientas como web_search o image_generation permiten a los agentes realizar acciones en el mundo real.
• La memoria permite a los agentes realizar un seguimiento de los mensajes anteriores y de los resultados de las herramientas a lo largo de los turnos, apoyando el razonamiento contextual.

Esta abstracción convierte un modelo básico de chat en un asistente multifuncional que puede participar en flujos de trabajo complejos.

Conversaciones 

Cada interacción entre un usuario y un agente forma parte de una conversación, que almacena:

• Mensajes anteriores y respuestas del asistente
• Llamadas a la herramienta y resultados
• Streaming de metadatos para visibilidad a nivel de token (opcional)

Estas conversaciones persistentes permiten a los agentes realizar tareas de varios turnos, como planificar, revisar o aprender de entradas anteriores.

Conectores y soporte de herramientas personalizadas

Mistral permite una fácil integración de herramientas mediante:

• Conectores: Se trata de herramientas preintegradas como web_search, code_execution, image_generation, document_library que funcionan "out-of-the-box".
• Herramientas MCP: Permiten API personalizadas alojadas por programadores que pueden invocarse como herramientas dentro del flujo de trabajo del agente.

Piensa en los conectores como aplicaciones integradas, y en las Herramientas MCP como complementos que tú escribes. Juntos, permiten a los agentes acceder tanto a las capacidades integradas como a los puntos finales definidos por los programadores para una lógica personalizada.

Fuente: Mistral AI

Entradas y entregas

Mistral rastrea todas las acciones de una conversación como "Entradas" estructuradas, lo que permite la trazabilidad y el control de los intercambios de mensajes y las ejecuciones de herramientas.

Los traspasos de agentes son aquellos en los que un agente delega el control en otro para modular los flujos de trabajo.

Fuente: Mistral AI

Esta arquitectura de orquestación facilita la composición y gestión de sistemas multiagente complejos sin perder transparencia ni control.

Configurar la API de Mistral

Empecemos a configurar Mistral. Empezaremos creando una clave API para el proyecto. Estos son los pasos que debes seguir:

1. Para empezar, crea una cuenta Mistral o inicia sesión en console.mistral.ai.

2. A continuación, ve a Configuración del espacio de trabajo (flecha desplegable junto a tu nombre, en la esquina superior izquierda) y haz clic en Facturación para añadir tu información de pago y activar los pagos en tu cuenta.

3. Haz clic en Añadir créditos y rellena tus datos de facturación en el formulario. A continuación, rellena el número de créditos que desees. Nota: Necesitas añadir al menos 10 créditos.

4. A continuación, en la pestaña de la izquierda, haz clic en Claves API y crea una nueva clave API haciendo clic en Crear nueva clave. Asegúrate de copiar la clave API, guárdala de forma segura y no la compartas con nadie.

Ahora tienes una clave API válida para interactuar con los modelos Mistral y construir agentes inteligentes.

Resumen del proyecto: Coach Nutricional con Agentes Mistral

En este proyecto, construiremos un Entrenador Nutricional potenciado por IA utilizando la API de Agentes de Mistral. Éste es el flujo de usuarios:

1. El usuario envía una comida que acaba de comer (por ejemplo, "ensalada de pollo con aliño de aceite de oliva").
2. Un agente de búsqueda web utiliza el conector incorporado para calcular las calorías de la comida.
3. Un agente registrador graba esta entrada con el nombre del usuario y la marca de tiempo.
4. Por último, un agente de generación de imágenes sugiere una comida de seguimiento saludable, devolviendo tanto una imagen como una descripción y una receta.

Para proporcionar una interfaz web en la que los usuarios puedan interactuar con el nutricionista, utilizaremos Gradio.

Paso 1: Requisitos previos

Antes de empezar, asegúrate de que tienes instalado lo siguiente:

• Python 3.8+
• Todos los paquetes necesarios enumerados en requirements.txt

python-dotenv==1.1.0
mistralai==0.0.7
typing-extensions==4.12.2
requests==2.31.0
gradio==4.34.0

Además, crea un archivo .env que contenga tu clave API de Mistral. Este enfoque mantiene seguras tus claves API y permite que distintos miembros del equipo o entornos de despliegue utilicen credenciales diferentes sin modificar el código fuente.

MISTRAL_API_KEY=YOUR_API_KEY

Nota: Se recomienda instalar estas dependencias dentro de un entorno aislado como conda, venv o uv para evitar conflictos de versiones con otros proyectos Python.

Aquí tienes los comandos para configurar diferentes entornos:

Utilizar venv

python -m venv mistral_env
source mistral_env/bin/activate   # On Windows: mistral_env\Scripts\activate

Utilizar Conda

conda create -n mistral_env python=3.10
conda activate mistral_env

Utilizar uv

Si aún no tienes uv:

pip install uv

Entonces:

uv venv mistral_env
source mistral_env/bin/activate

Para instalar todas las dependencias mencionadas, ejecuta el siguiente código en tu terminal:

pip install -r requirements.txt

Nota: Si encuentras algún error relacionado con mistralai al utilizar cualquier agente o conector, ejecuta el siguiente código:

pip install –upgrade mistralai

Esto actualizará la biblioteca mistralai a su última versión.

Paso 2: Configurar las herramientas Mistral

En esta sección, prepararemos nuestras herramientas y la configuración del cliente para interactuar con la API de los Agentes Mistral.  Definiremos los esquemas de la herramienta, inicializaremos el cliente y verificaremos la autenticación. Más adelante se hará referencia a estas herramientas cuando se configuren agentes específicos, como estimadores de calorías o generadores de imágenes.

Paso 2.1: Registro e inicialización de la herramienta

En primer lugar, definimos los esquemas de nuestra herramienta, la selección del modelo y la instanciación del cliente. A continuación, construimos métodos de ayuda como create_chat_completion() y check_client(). El siguiente código va en el archivo configs.py dentro de la carpeta de herramientas:

#Configuration file
from mistralai import Mistral, UserMessage, SystemMessage
from dotenv import load_dotenv
import os
load_dotenv()
# Mistral model 
mistral_model = "mistral-large-latest"
client = Mistral(api_key=os.environ.get("MISTRAL_API_KEY"))
# Agent IDs
web_search_id = "web_search_agent"
food_logger_id = "food_logger_agent"
user_assistant_id = "user_assistant_agent"
image_generator_id = "image_generator_agent"
# Tool definitions
tools = {
    "log_meal": {
        "name": "log_meal",
        "description": "Log a user's meal with calorie count",
        "input_schema": {
            "type": "object",
            "properties": {
                "username": {"type": "string"},
                "meal": {"type": "string"},
                "calories": {"type": "number"},
                "timestamp": {"type": "string", "format": "date-time"}
            },
            "required": ["username", "meal", "calories", "timestamp"]
        }
    },
    "web_search": {
        "name": "web_search",
        "description": "Search the web for information about a meal",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string"}
            },
            "required": ["query"]
        }
    }
}

Empezamos importando dotenv para cargar variables sensibles como la clave de la API de Mistral desde un archivo local .env al entorno de Python. Esto mantiene las credenciales seguras y fuera del código fuente. A continuación, seleccionamos el modelo por defecto mistral-large-latest e instanciamos un cliente Mistral utilizando la clave API.

A continuación, definimos las especificaciones internas de la herramienta (esquemas) utilizando el formato de esquema JSON. Ayudan en lo siguiente

• Simular el comportamiento de las herramientas MCP (aunque no estén registradas mediante la biblioteca McpTool)
• Describe las entradas esperadas como "nombre de usuario", "comida" y "calorías"
• Ayuda a garantizar un formato de entrada coherente en todos los módulos

Ahora, vamos a añadir nuestros métodos ayudantes que crean finalizaciones de chat, registran herramientas, agentes e inicializan el cliente.

def create_chat_completion(messages, model=mistral_model):  
    # Convert messages to new format
    formatted_messages = []
    for msg in messages:
        if msg["role"] == "system":
            formatted_messages.append(SystemMessage(content=msg["content"]))
        else:
            formatted_messages.append(UserMessage(content=msg["content"]))
    return client.chat.complete(
        model=model,
        messages=formatted_messages
    )
# Register tools
def register_tools():
    for tool_name, tool in tools.items():
        print(f"Registered tool: {tool_name}")
# Register agents
def register_agents():
    print("Registered User Assistant Agent")
    print("Registered Web Search Agent")
    print("Registered Food Logger Agent")
# Initialize everything
def initialize():
    register_tools()
    register_agents()
    check_client()
# Check if the client is initialized
def is_client_initialized():
    return client is not None and os.environ.get("MISTRAL_API_KEY") is not None
def check_client():
    if not is_client_initialized():
        print("Mistral client is not initialized. Please check your API key.")
        return False
    print("Mistral client is initialized.")
    return True
initialize()

La función create_chat_completion() envuelve una llamada al método client.chat.complete(), que forma parte del SDK del cliente Mistral, para enviar mensajes al modelo.

• Reformatea los mensajes en bruto de tipo dict en los objetos UserMessage y SystemMessage requeridos por el SDK de Mistral.
• También es útil para completar de forma estandarizada toda la app.

Las funciones register_tools() y register_agents() ayudan durante el desarrollo local registrando qué herramientas y agentes están activos en el sistema. Mientras tanto, las funciones check_client() y is_client_initialized() garantizan que el cliente Mistral se ha instanciado correctamente y que la clave API está disponible, lo que ayuda a evitar errores de ejecución durante la ejecución del agente.

Paso 2.2: Estimación de calorías con el agente de búsqueda web

Ahora que hemos inicializado las herramientas base y el cliente, vamos a construir un Agente de Búsqueda en la Web dedicado a la Nutrición. Este agente utiliza el conector web_search de Mistral para buscar estimaciones calóricas de las comidas en tiempo real. Este código se encuentra en el archivo web_search.py dentro de la carpeta de herramientas.

# Web search tool
import re
from mistralai import Mistral, UserMessage, SystemMessage
from tools.configs import client
def search_calories(meal_desc):
    try:
        # Web search agent
        websearch_agent = client.beta.agents.create(
            model="mistral-medium-latest",
            description="Agent able to search for nutritional information and calorie content of meals",
            name="Nutrition Search Agent",
            instructions="You have the ability to perform web searches with web_search to find accurate calorie information. Return ONLY a single number representing total calories.",
            tools=[{"type": "web_search"}],
            completion_args={
                "temperature": 0.3,
                "top_p": 0.95,
            }
        )
        response = client.beta.conversations.start(
            agent_id=websearch_agent.id,
            inputs=f"What are the total calories in {meal_desc}?"
        )
        print("Raw response:", response)
        # Extract the number from the response
        if hasattr(response, 'outputs'):
            for output in response.outputs:
                if hasattr(output, 'content'):
                    if isinstance(output.content, str):
                        numbers = re.findall(r'\d+', output.content)
                        if numbers:
                            return int(numbers[0])
                    elif isinstance(output.content, list):
                        for chunk in output.content:
                            if hasattr(chunk, 'text'):
                                numbers = re.findall(r'\d+', chunk.text)
                                if numbers:
                                    return int(numbers[0])
        print("No calorie information found in web search response")
        return 0     
    except Exception as e:
        print(f"Error during web search: {str(e)}")
        return 0

En el código anterior, la función search_calories() utiliza la herramienta incorporada de conector para la búsqueda web de la API de Agentes Mistral, que permite a los agentes realizar consultas web en directo como la estimación de calorías, superando las limitaciones del entrenamiento estático del modelo. Así es como funciona:

1. Creación de agentes: Primero crea un "Agente de Búsqueda Nutricional" utilizando el modelo mistral-medium-latest, que está equipado con la herramienta web_search y al que se le ordena que devuelva sólo calorías.
2. Ejecución de la consulta: A continuación, se utiliza al agente para iniciar una conversación en la que se le pregunta por el total de calorías de la descripción de la comida proporcionada.
3. Análisis de la respuesta: La respuesta del agente se analiza utilizando expresiones regulares para extraer el primer valor numérico (que debe ser el recuento de calorías).
4. Fallbacks: Si no se encuentra un número válido o se produce un error, la función registra el problema y devuelve cero como respuesta alternativa.

Sin web_search, la mayoría de los modelos no pueden responder a preguntas sobre acontecimientos recientes o comidas específicas del dominio que no se ven en sus datos de entrenamiento. Con él, podemos consultar información nutricional, menús de restaurantes o artículos de noticias en tiempo real.

Hay dos variantes de búsqueda web:

• web_search: Un conector de motor de búsqueda ligero y de uso general (utilizado en nuestro proyecto).
• web_search_premium: Una versión mejorada que incluye la verificación del proveedor de noticias y una recopilación de contexto más amplia.

A continuación, exploraremos la estimación alternativa de calorías utilizando la lógica de sólo indicación.

Paso 2.3: Estimación, registro y sugerencia de comidas

En esta sección, implementamos tres funciones esenciales que actúan como fallbacks o mejoras. El siguiente código se encuentra dentro del archivo next.py en la carpeta de herramientas.

#Meal suggestions
from datetime import datetime
from tools.configs import client, create_chat_completion
from mistralai import SystemMessage, UserMessage
import re
def estimate_calories(meal_desc):   
    try:
        # Messages for calorie estimation
        messages = [
            SystemMessage(content="You are a nutrition expert. Estimate calories in meals. Return ONLY a single number representing total calories."),
            UserMessage(content=f"Estimate calories in: {meal_desc}")
        ]
        response = client.chat.complete(
            model="mistral-small-latest",  # Using smaller model to avoid rate limits
            messages=messages,
            temperature=0.1,
            max_tokens=50
        )
        content = response.choices[0].message.content
        numbers = re.findall(r'\d+', content)    
        if numbers:
            return int(numbers[0])
        return 0     
    except Exception as e:
        print(f"Error during calorie estimation: {str(e)}")
        return 0
def log_meal(username, meal, calories):  
    try:
        # Messages for meal logging
        messages = [
            SystemMessage(content="You are a meal logging assistant. Log the user's meal with calories."),
            UserMessage(content=f"Log this meal: {meal} with {calories} calories for user {username} at {datetime.utcnow().isoformat()}")
        ]
        response = client.chat.complete(
            model="mistral-small-latest",  # Using smaller model to avoid rate limits
            messages=messages,
            temperature=0.1,
            max_tokens=100
        )
        return response.choices[0].message.content.strip()
    except Exception as e:
        print(f"Error during meal logging: {str(e)}")
        return f"Logged {meal} ({calories} calories) for {username}"
def suggest_next_meal(calories, dietary_preference):   
    try:
        # Messages for meal suggestion
        messages = [
            SystemMessage(content="You are a nutrition expert. Suggest healthy meals based on calorie intake and dietary preferences."),
            UserMessage(content=f"Suggest a {dietary_preference} meal that would be a good next meal after consuming {calories} calories. Make it specific and appetizing.")
        ]
        response = client.chat.complete(
            model="mistral-small-latest",  
            messages=messages,
            temperature=0.7
        )
        return response.choices[0].message.content.strip()        
    except Exception as e:
        print(f"Error during meal suggestion: {str(e)}")
        return "Unable to suggest next meal at this time."

Este script define las funciones básicas de backend que impulsan nuestro flujo de trabajo de nutrición (desde la estimación de calorías hasta la planificación de comidas de seguimiento). Estas funciones utilizan modelos ligeros de Mistral y la finalización estándar del chat, sin necesidad de crear agentes ni conectores que se utilicen cuando la búsqueda web no esté disponible, o para evitar errores de límite de velocidad. Esto es lo que hace cada función:

1. estimate_calories(): Esta función se utiliza como alternativa si el conector web_search falla o no está disponible.
1. Envía un mensaje de sistema que contiene la función del asistente como experto en nutrición junto con la indicación al usuario que incluye la comida que quiere registrar.
2. El modelo se utiliza con temperature=0.1 bajo para obtener resultados deterministas. Esto significa que el modelo producirá respuestas coherentes y repetibles para las mismas tareas de entrada, como la estimación y el registro de calorías, en las que se prefieren los resultados estables y factuales a la variación creativa.
3. Analiza el primer número (mediante regex) de la respuesta del modelo.
2. log_meal(): Esta función registra la comida de un usuario, incluyendo una marca de tiempo.
1. Utiliza una finalización de chat con la instrucción y devuelve el mensaje de confirmación formateado del asistente.
2. Esto permite un registro interno ligero sin necesidad de una base de datos dedicada.
3. suggest_next_meal(): Esta función recomienda al usuario su próxima comida basándose en la ingesta calórica previa y en su perfil dietético.
1. El modelo se invoca con temperature=0.7 para fomentar sugerencias más creativas.
2. A continuación, la respuesta se despoja y se devuelve como la siguiente idea de comida.

Juntas, estas funciones permiten la estimación de calorías, la confirmación de registros y las recomendaciones saludables sin necesidad de API externas. En el siguiente paso, visualizaremos las sugerencias de comida con el conector de generación de imágenes de Mistral.

Paso 2.4: Generar visuales con el conector de generación de imágenes

Añadamos ahora una capa visual a nuestro asistente. En este paso, utilizaremos el conector image_generation integrado en Mistral para generar una imagen apetitosa de la próxima comida sugerida.

#Image generation tool
import os
import re
from mistralai import Mistral, UserMessage, SystemMessage
from mistralai.models import ToolFileChunk
from tools.configs import client
from datetime import datetime
def generate_food_image(meal_description):  
    try:
        print(f"Starting image generation for: {meal_description}")        
        # Image generation agent
        image_agent = client.beta.agents.create(
            model="mistral-medium-latest",
            name="Food Image Generation Agent",
            description="Agent used to generate food images.",
            instructions="Use the image generation tool to create appetizing food images. Generate realistic and appetizing images of meals.",
            tools=[{"type": "image_generation"}],
            completion_args={
                "temperature": 0.3,
                "top_p": 0.95,
            }
        )
        print("Created image generation agent")
        response = client.beta.conversations.start(
            agent_id=image_agent.id,
            inputs=f"Generate an appetizing image of: {meal_description}",
            stream=False  
        )
        print("Got response from image generation")
        os.makedirs("generated_images", exist_ok=True)
        # Process the response and save images
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
        image_paths = []
        if hasattr(response, 'outputs'):
            print(f"Processing {len(response.outputs)} outputs")
            for output in response.outputs:
                if hasattr(output, 'content'):
                    print(f"Processing content of type: {type(output.content)}")
                    if isinstance(output.content, list):
                        for i, chunk in enumerate(output.content):
                            print(f"Processing chunk {i} of type: {type(chunk)}")
                            if isinstance(chunk, ToolFileChunk):
                                print(f"Found ToolFileChunk with file_id: {chunk.file_id}")
                                try:
                                    # Download the image
                                    file_bytes = client.files.download(file_id=chunk.file_id).read()       
                                    # Save the image
                                    image_path = f"generated_images/meal_{timestamp}_{i}.png"
                                    with open(image_path, "wb") as file:
                                        file.write(file_bytes)
                                    image_paths.append(image_path)
                                    print(f"Successfully saved image to: {image_path}")
                                except Exception as e:
                                    print(f"Error processing image chunk: {str(e)}")
                    else:
                        print(f"Content is not a list: {output.content}")
        if image_paths:
            print(f"Successfully generated {len(image_paths)} images")
            return image_paths[0]  # Return the first image path
        else:
            print("No images were generated")
            return "No image was generated”
    except Exception as e:
        print(f"Error during image generation: {str(e)}")
        if hasattr(e, '__dict__'):
            print(f"Error details: {e.__dict__}")
        return f"Error generating image: {str(e)}" 

La función generate_food_image() genera una representación visual de una comida utilizando la herramienta image_generation integrada en Mistral. He aquí lo que hace cada parte:

• Creación de agentes: Un nuevo agente recibe instrucciones para crear imágenes de comida realistas y apetitosas.
• Inicio de la conversación: Se envía un aviso pidiendo al agente que genere una imagen del meal_description dado que es generado por el agente de la comida siguiente.
• Gestión de respuestas: La función comprueba si la respuesta contiene trozos de imagen. En caso afirmativo, descarga cada imagen mediante el método files.download() del cliente Mistral. Las imágenes se guardan localmente en una carpeta generated_images/ con nombres de archivo con fecha y hora.
• Salida: Devuelve la ruta a la primera imagen guardada correctamente, o un mensaje de error si falla la generación.

Esta herramienta añade una capa visual a nuestro entrenador nutricional, haciendo que las sugerencias de comidas sean más atractivas y realistas.

Paso 3: Nutricionista a tiempo completo

Ahora que hemos creado las herramientas individuales y las capacidades de los agentes, es hora de ponerlas en una única canalización. Este paso pega todo junto en un ayudante de trabajo que se maneja:

• Búsqueda de calorías (vía web o estimación)
• Registro (usuario, comida, calorías, marca de tiempo)
• Sugerir una comida de seguimiento
• Visualizar la comida con una imagen

Todos estos pasos se realizan llamando a cada función de nuestros archivos anteriores en el orden correcto. El código de esta canalización se encuentra fuera de la carpeta de herramientas, en el archivo agent.py.

# Pipeline logic file
from tools import estimate_calories, log_meal, suggest_next_meal, search_calories
from tools.image_gen import generate_food_image
from datetime import datetime
import time
def run_nutritionist_pipeline(username, meal_desc, dietary_preference):
    tools_used = set()    
    print(f"Searching for calories for: {meal_desc}")
    calories_text = search_calories(meal_desc)
    tools_used.add("Web Search")    
    # If web search fails, fall back to estimation
    if calories_text == 0:
        print("Web search failed, falling back to estimation...")
        time.sleep(1)  # Add delay to avoid rate limits
        calories_text = estimate_calories(meal_desc)
        tools_used.add("Calorie Estimation")   
    estimated_calories = calories_text
    print(f"Estimated calories: {estimated_calories}")   
    print(f"Logging meal for {username}...")
    time.sleep(1)  # Add delay to avoid rate limits
    log_response = log_meal(username, meal_desc, estimated_calories)
    tools_used.add("Meal Logging")    
    print("Generating next meal suggestion...")
    time.sleep(1)  
    suggestion = suggest_next_meal(estimated_calories, dietary_preference)
    tools_used.add("Next Meal Suggestion")    
    print("Generating image description for suggested meal...")
    time.sleep(1)  
    meal_image = generate_food_image(suggestion)
    tools_used.add("Image Description Generation")
    return {
        "logged": log_response,
        "next_meal_suggestion": suggestion,
        "meal_image": meal_image,
        "tools_used": sorted(list(tools_used))
    }

El código anterior coordina todo el flujo de trabajo del asistente de nutrición encadenando varias herramientas de agente en una única canalización. Vamos a desglosar el código anterior con más detalle:

• La función run_nutritionist_pipeline() acepta como entradas username, meal_desc, y dietary_preference para impulsar el proceso de recomendación.
• En primer lugar, intenta determinar el contenido calórico de la comida utilizando la función search_calories() del conector de búsqueda web de Mistral. Si esto falla, recurre a una estimación mediante un modelo ligero a través de estimate_calories().
• A continuación, el valor calórico obtenido se registra mediante la función log_meal(), que etiqueta la entrada con una marca de tiempo y la asocia al usuario.
• Basándose en las calorías consumidas y la preferencia dietética, la función suggest_next_meal() sugiere una comida de seguimiento utilizando un razonamiento basado en indicaciones.
• Por último, la función generate_food_image() utiliza el conector de generación de imágenes de Mistral para producir una representación visual del plato recomendado.
• A lo largo del proceso, time.sleep(1) se utiliza para introducir breves pausas entre las solicitudes para evitar que se activen los límites de velocidad durante las llamadas a la API.
• La función devuelve un diccionario que contiene la confirmación del registro de la comida, el texto de sugerencia de la siguiente comida, la ruta de la imagen generada y una lista de las herramientas que se utilizaron en esta interacción.

Esta canalización combina múltiples capacidades, como la búsqueda, la estimación, el registro, la sugerencia y la visualización, en una experiencia de nutrición potenciada por la IA.

Paso 4: Crear una interfaz fácil de usar con Gradio

Ahora que la lógica del backend está completa, vamos a envolverla en un frontend limpio y fácil de usar utilizando Gradio.

# Main files
import gradio as gr
from agent import run_nutritionist_pipeline
import os
import re
def process_meal(username, meal_desc, dietary_preference):
    # Run the pipeline
    result = run_nutritionist_pipeline(username, meal_desc, dietary_preference)    
    # Extract calories from the logged meal response
    calories = "Not available"
    if result['logged']:
        calorie_match = re.search(r'(\d+)\s*calories', result['logged'], re.IGNORECASE)
        if calorie_match:
            calories = calorie_match.group(1)
        else:
            paren_match = re.search(r'\((\d+)\)', result['logged'])
            if paren_match:
                calories = paren_match.group(1)
            else:
                number_match = re.search(r'\b(\d+)\b', result['logged'])
                if number_match:
                    calories = number_match.group(1)    
    # Map tool names to Mistral connectors
    connector_map = {
        "Web Search": "Web Search",
        "Image Description Generation": "Image Generation",
        "Meal Logging": "Chat Completion",
        "Next Meal Suggestion": "Chat Completion"
    }   
    connectors_used = set()
    for tool in result['tools_used']:
        if tool in connector_map:
            connectors_used.add(connector_map[tool])    
    output = f"""
# Meal Analysis Results
## Meal Details
- **Meal Description:** {meal_desc}
- **Estimated Calories:** {calories}
## Next Meal Suggestion
{result['next_meal_suggestion']}

## Tools Used
{', '.join(result['tools_used'])}
## Mistral Connectors Used
{', '.join(sorted(connectors_used))}
""
    # Get the image path and check if it is valid
    image_path = result['meal_image']    
    if os.path.exists(image_path) and image_path.endswith('.png'):
        return output, image_path
    else:
        return output, None
# Create the Gradio interface
with gr.Blocks(theme=gr.themes.Soft()) as demo:
    gr.Markdown("# 🍽️ Nutritionist Assistant")    
    with gr.Row():
        with gr.Column():
            username = gr.Textbox(label="Username", placeholder="Enter your name")
            meal_desc = gr.Textbox(label="Meal Description", placeholder="Describe your meal (e.g., 'Chicken salad with olive oil dressing')")
            dietary_preference = gr.Dropdown(
                choices=["vegetarian", "vegan", "Non-vegetarian", "gluten-free"],
                label="Dietary Preference",
                value="omnivore"
            )
            submit_btn = gr.Button("Process Meal", variant="primary")        
        with gr.Column():
            output = gr.Markdown(label="Results")
            image_output = gr.Image(label="Generated Meal Image", type="filepath")    
    submit_btn.click(
        fn=process_meal,
        inputs=[username, meal_desc, dietary_preference],
        outputs=[output, image_output]
    )
# Launch the app
if __name__ == "__main__":
    demo.launch() 

En el fragmento de código anterior, configuramos una interfaz de usuario completa de Gradio para interactuar con la canalización del Agente Nutricionista. Así es como funciona:

• Empezamos importando la función run_nutritionist_pipeline() de agent.py, que dirige la lógica central del agente.
• A continuación, la función process_meal() actúa como una envoltura alrededor del canal de agentes, que acepta username, meal_desc, y dietary_preference como entradas del usuario y activa la lógica multiagente definida anteriormente.
• Dentro de la función process_meal(), se analiza el diccionario de resultados para extraer el resumen de la comida, las calorías, la próxima comida sugerida y los conectores utilizados.
• La función también comprueba si la ruta de la imagen generada es válida antes de devolverla para su visualización. Si no se encuentra la imagen, sólo se devuelve el resultado textual.
• La app Gradio está construida utilizando gr.Blocks() y el diseño incluye dos caras, una con campos de entrada y un botón de Procesar Comida. Mientras que el otro lado contiene un área de salida para los resultados del análisis de la comida y una vista previa de la imagen de la siguiente comida.
• La llamada de retorno de submit_btn.click() conecta el botón del frontend para activar la función process_meal(), pasando las entradas y recibiendo markdown formateado e imagen como salidas.
• Por último, la aplicación se lanza a través de demo.launch() si el script se ejecuta como módulo principal. Puedes configurar debug = True para activar el modo de depuración de la aplicación.

Para ejecutar esta demostración, abre un terminal en tu directorio raíz y escribe el siguiente comando:

python app.py

La estructura general de este proyecto sería la siguiente:

Mistral_Agent_API/
├── generated_images/ # Stores generated meal images
├── tools/
│   ├── configs.py              # API setup, tool schema, environment config
│   ├── image_gen.py            # Generates meal image  
│   ├── next.py                 # Calorie estimator, logger, and next meal 
│   └── web_search.py           # Mistral web_search connector to find calorie 
├── agent.py                    # Main pipeline connecting all tools
├── app.py                      # Gradio UI 
├── requirements.txt            # Project dependencies
├── .env                        # Environment variables 

Puedes encontrar el código completo de este proyecto en este repositorio de GitHub.

Conclusión

En este tutorial, construimos un Entrenador de Nutrición AI totalmente funcional utilizando la API de Agentes Mistral. Por el camino, exploramos:

• En qué se diferencian los agentes Mistral de los modelos LLM brutos
• El papel de los conectores como web_search y image_generation
• Orquestación a través de múltiples agentes en una única canalización
• Construir un frontend fácil de usar con Gradio

Este proyecto muestra el poder de los flujos de trabajo agénticos, en los que los LLM no son meros respondedores pasivos, sino entidades interactivas que razonan, actúan y coordinan tareas. Desde registrar comidas hasta sugerir alternativas saludables e incluso generar imágenes, mostramos cómo combinar herramientas sencillas en potentes experiencias de IA.

Para saber más sobre el uso de agentes de IA, te recomiendo estos tutoriales prácticos:

• Códice de OpenAI: Una guía con 3 ejemplos prácticos
• Google Jules: Una guía con 3 ejemplos prácticos
• Laboratorios Perplexity: Una guía con 5 ejemplos prácticos
• n8n: Una guía con ejemplos prácticos
• Dificar la IA: Una guía con proyecto de demostración