Ir al contenido principal
Español— Elegir un idioma
Menú

Ejemplo práctico: rastreador de pagos

Lección 12 de 14 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Un proyecto completo de extremo a extremo
  2. Los datos
  3. Funciones de negocio
  4. Especificaciones JSON
  5. El diccionario de despacho
  6. El bucle de conversación
  7. Lo que revela la conversación
  8. Conclusiones clave

Un proyecto completo de extremo a extremo

En las lecciones anteriores has aislado cada mecanismo: definiciones de herramientas, el ciclo de llamada, la gestión de errores y la seguridad. Ha llegado el momento de ensamblarlos. Vas a construir un rastreador de pagos conversacional completo donde los usuarios formulan preguntas en lenguaje natural y el sistema consulta un DataFrame de Pandas mediante llamadas a funciones. Este caso de uso se basa directamente en la documentación oficial de Mistral. Cabe en unas cien líneas y expone los cinco bloques constructivos de una aplicación real: datos, funciones de negocio, especificaciones JSON, despacho y el bucle de conversación.

Los datos

Un DataFrame con cinco transacciones cubre los escenarios interesantes: un cliente con varios pagos, un pago pendiente y un pago fallido.

import pandas as pd
import json
import os
from mistralai.client import Mistral
from functools import partial

# Transactions DataFrame
data = {
    "transaction_id": ["T1001", "T1002", "T1003", "T1004", "T1005"],
    "customer_id": ["C001", "C002", "C003", "C002", "C001"],
    "payment_amount": [125.50, 89.99, 350.00, 45.00, 210.75],
    "payment_date": ["2026-03-15", "2026-03-16", "2026-03-17", "2026-03-17", "2026-03-18"],
    "payment_status": ["paid", "paid", "pending", "paid", "failed"]
}
df = pd.DataFrame(data)

Funciones de negocio

Cuatro funciones cubren las necesidades típicas de seguimiento de pagos. Las tres primeras operan sobre una única transacción y difieren por su granularidad: solo el estado, solo la fecha o todos los detalles. Esta aparente redundancia es deliberada: permite que el modelo solicite únicamente lo que necesita, reduciendo datos innecesarios en el contexto. La cuarta cambia de perspectiva y opera por cliente.

Observa el contrato común: todas devuelven una cadena JSON, incluso en caso de error, y todas gestionan identificadores faltantes en lugar de permitir que Pandas lance una excepción ante un índice vacío.

def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
    """Retrieves the status of a payment."""
    if transaction_id in df["transaction_id"].values:
        row = df[df["transaction_id"] == transaction_id].iloc[0]
        return json.dumps({
            "transaction_id": transaction_id,
            "status": row["payment_status"]
        })
    return json.dumps({"error": f"Transaction {transaction_id} not found"})


def retrieve_payment_date(df: pd.DataFrame, transaction_id: str) -> str:
    """Retrieves the date of a payment."""
    if transaction_id in df["transaction_id"].values:
        row = df[df["transaction_id"] == transaction_id].iloc[0]
        return json.dumps({
            "transaction_id": transaction_id,
            "date": row["payment_date"]
        })
    return json.dumps({"error": f"Transaction {transaction_id} not found"})


def retrieve_payment_details(df: pd.DataFrame, transaction_id: str) -> str:
    """Retrieves all details of a payment."""
    if transaction_id in df["transaction_id"].values:
        row = df[df["transaction_id"] == transaction_id].iloc[0]
        return json.dumps({
            "transaction_id": transaction_id,
            "customer_id": row["customer_id"],
            "amount": float(row["payment_amount"]),
            "date": row["payment_date"],
            "status": row["payment_status"]
        })
    return json.dumps({"error": f"Transaction {transaction_id} not found"})


def list_customer_transactions(df: pd.DataFrame, customer_id: str) -> str:
    """Lists all transactions for a given customer."""
    customer_df = df[df["customer_id"] == customer_id]
    if customer_df.empty:
        return json.dumps({"error": f"Customer {customer_id} not found"})

    transactions = []
    for _, row in customer_df.iterrows():
        transactions.append({
            "transaction_id": row["transaction_id"],
            "amount": float(row["payment_amount"]),
            "date": row["payment_date"],
            "status": row["payment_status"]
        })
    return json.dumps({"customer_id": customer_id, "transactions": transactions})

La conversión float(row["payment_amount"]) merece una segunda mirada: sin ella, json.dumps falla con los tipos de NumPy. Este es el tipo de detalle que solo detectas en tiempo de ejecución.

Especificaciones JSON

El modelo no ve nada del código anterior. Solo conoce estas descripciones. Enumerar explícitamente los estados posibles en retrieve_payment_status y recordar al modelo el formato T1001 en la descripción de cada parámetro le permite elegir la función correcta y extraer el identificador adecuadamente.

tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment (paid, pending, failed)",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Transaction identifier (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Retrieves the date of a payment",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Transaction identifier (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_details",
            "description": "Retrieves all details of a payment: amount, date, status, customer",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Transaction identifier (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "list_customer_transactions",
            "description": "Lists all transactions for a given customer",
            "parameters": {
                "type": "object",
                "properties": {
                    "customer_id": {
                        "type": "string",
                        "description": "Customer identifier (e.g., C001)"
                    }
                },
                "required": ["customer_id"]
            }
        }
    }
]

El diccionario de despacho

Aquí está la clave: tus funciones esperan df como primer argumento, pero el modelo nunca lo proporcionará; no sabe que existe, y eso está bien. functools.partial resuelve esto elegantemente vinculando previamente el DataFrame, de modo que cada entrada del diccionario se pueda invocar solo con los argumentos que produce el modelo.

available_functions = {
    "retrieve_payment_status": partial(retrieve_payment_status, df),
    "retrieve_payment_date": partial(retrieve_payment_date, df),
    "retrieve_payment_details": partial(retrieve_payment_details, df),
    "list_customer_transactions": partial(list_customer_transactions, df),
}

El bucle de conversación

El mensaje del sistema establece el rol, el idioma y el formato esperado para los importes. La función chat orquesta el resto, y su estructura merece atención detallada: el bucle while message.tool_calls gestiona una única llamada, varias llamadas paralelas o una cadena donde el modelo solicita otra función tras ver el primer resultado. El bucle interno ejecuta todas las llamadas del turno actual; el bucle externo vuelve a invocar al modelo mientras este siga solicitando herramientas.

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
model = "mistral-large-latest"

messages = [
    {
        "role": "system",
        "content": "You are a payment tracking assistant. "
                   "Respond in English. Use the available tools "
                   "to answer questions about transactions. "
                   "Format amounts in euros with 2 decimal places."
    }
]


def chat(user_input: str) -> str:
    """Complete conversation turn with tool_calls handling."""
    messages.append({"role": "user", "content": user_input})

    response = client.chat.complete(
        model=model, messages=messages, tools=tools
    )
    message = response.choices[0].message

    # Loop while the model wants to call functions
    while message.tool_calls:
        messages.append(message)

        for tool_call in message.tool_calls:
            fn_name = tool_call.function.name
            fn_params = json.loads(tool_call.function.arguments)

            if fn_name in available_functions:
                result = available_functions[fn_name](**fn_params)
            else:
                result = json.dumps({"error": f"Unknown function {fn_name}"})

            messages.append({
                "role": "tool",
                "name": fn_name,
                "content": result,
                "tool_call_id": tool_call.id
            })

        response = client.chat.complete(
            model=model, messages=messages, tools=tools
        )
        message = response.choices[0].message

    messages.append(message)
    return message.content

Lo que revela la conversación

Prueba esto con cuatro turnos consecutivos. El segundo es el más instructivo: «esta transacción» no contiene ningún identificador, pero el modelo llama a retrieve_payment_details con T1001. Ha resuelto la anáfora utilizando el historial conservado en messages, algo que sería imposible si reiniciaras la lista en cada llamada. El cuarto turno muestra la otra cara: ninguna función busca pagos fallidos, pero el modelo consulta al cliente relevante y filtra el resultado por su cuenta.

# Turn 1
print(chat("What is the status of payment T1001?"))
# -> "Payment T1001 has status: paid."

# Turn 2
print(chat("Give me all the details for this transaction."))
# -> "Here are the details for payment T1001:
#     - Customer: C001
#     - Amount: 125.50 euros
#     - Date: March 15, 2026
#     - Status: paid"

# Turn 3
print(chat("What are all the transactions for customer C002?"))
# -> "Customer C002 has 2 transactions:
#     - T1002: 89.99 euros (paid, March 16, 2026)
#     - T1004: 45.00 euros (paid, March 17, 2026)"

# Turn 4
print(chat("Are there any failed payments?"))
# -> "Yes, payment T1005 for customer C001 (210.75 euros) failed."

El formato de los importes con punto decimal y las fechas escritas completas no proviene de ninguna línea de código: es consecuencia del mensaje del sistema. Esta es la conclusión más útil de este capítulo: la mitad de la calidad percibida ocurre en las descripciones y en el mensaje del sistema, no en la mecánica de las llamadas.

Conclusiones clave

  • Un rastreador de pagos completo requiere 4 funciones que cubran los principales casos de uso
  • functools.partial vincula el DataFrame a las funciones para un despacho limpio
  • El bucle while message.tool_calls gestiona automáticamente llamadas secuenciales y paralelas
  • El mensaje del sistema guía al modelo sobre el tono, el idioma y el formato
  • Prueba con conversaciones de varios turnos para verificar que el modelo mantiene el contexto