Definir funciones en Python
En esta página
De la teoría al código
Ya conoces el proceso de cinco pasos y la estructura del esquema JSON. Es hora de escribir código Python real. En esta lección, crearás funciones, redactarás sus especificaciones y prepararás todo para la API de Mistral: todo lo que debe existir antes de realizar la primera llamada de red.
Instalar el SDK de Mistral
Comienza instalando el paquete oficial:
pip install mistralai
A continuación, configura tu clave de API. Las buenas prácticas dictan que nunca la hardcodees en tus archivos de código fuente. En su lugar, léela desde una variable de entorno para que puedas subir tu código al control de versiones de forma segura.
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Crear funciones en Python
Veamos un ejemplo práctico: un sistema de seguimiento de pagos respaldado por un DataFrame de Pandas. Este es un ejemplo clásico de la documentación de Mistral que ilustra perfectamente el concepto; aquí, el DataFrame hace el papel que tendría una base de datos en producción.
import pandas as pd
import json
# Datos de pagos
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)
A continuación llega el código que accede realmente a estos datos. Son funciones Python estándar; nada en su implementación sugiere que un LLM las vaya a dirigir.
def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
"""Recupera el estado de un pago mediante su ID."""
if transaction_id in df["transaction_id"].values:
status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
return json.dumps({"status": status})
return json.dumps({"error": f"Transacción {transaction_id} no encontrada"})
def retrieve_payment_date(df: pd.DataFrame, transaction_id: str) -> str:
"""Recupera la fecha de un pago mediante su ID."""
if transaction_id in df["transaction_id"].values:
date = df[df["transaction_id"] == transaction_id]["payment_date"].values[0]
return json.dumps({"date": date})
return json.dumps({"error": f"Transacción {transaction_id} no encontrada"})
Dos detalles de implementación merecen tu atención. Primero, estas funciones devuelven siempre una cadena JSON, nunca un objeto Python crudo. Este es el formato que el modelo espera como resultado de una herramienta, por lo que json.dumps() es innegociable. Segundo, gestionan explícitamente el caso en que no se encuentra una transacción en lugar de lanzar una excepción. Este error, formateado como JSON, vuelve al modelo igual que cualquier otro resultado, permitiéndole informar cortésmente al usuario de que la transacción T9999 no existe. Más adelante en el curso verás por qué este reflejo es esencial.
Escribir especificaciones JSON
Cada función necesita una especificación para que el modelo pueda entenderla. Aquí aplicas la estructura de la lección anterior a las dos funciones anteriores; observa la correspondencia estricta entre los campos name y los nombres reales de las funciones Python.
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Recupera el estado de un pago (paid, pending, failed) "
"basándose en el ID de la transacción.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Identificador único de la transacción (p. ej., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_date",
"description": "Recupera la fecha en que se realizó un pago "
"basándose en el ID de la transacción.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Identificador único de la transacción (p. ej., T1001)"
}
},
"required": ["transaction_id"]
}
}
}
]
Organizar funciones en un diccionario
El modelo devuelve un nombre de función como cadena. Necesitas una forma de mapear esa cadena al objeto callable correspondiente sin recurrir a eval ni a una cascada de sentencias if. Un diccionario de despacho resuelve este problema en tres líneas.
from functools import partial
# Vincular el DataFrame a cada función
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
}
functools.partial aborda una dificultad específica y real. Tus funciones esperan dos argumentos —el DataFrame y el ID—, pero el modelo solo proporciona uno. El modelo no sabe nada de df, ni debería saberlo. partial rellena previamente ese primer parámetro de una vez por todas. Este mismo mecanismo se aplica a conexiones de bases de datos, clientes HTTP o tokens de autenticación. La invocación dinámica se vuelve entonces trivial.
function_name = "retrieve_payment_status"
function_params = {"transaction_id": "T1001"}
result = available_functions[function_name](**function_params)
# → '{"status": "paid"}'
La opción tool_choice
Al enviar estas herramientas a la API, el parámetro tool_choice decide cuánta libertad le das al modelo. Son posibles tres valores.
# El modelo decide si usar una herramienta o responder directamente (predeterminado)
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="auto"
)
# Forzar al modelo a usar una herramienta
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="any"
)
# Impedir que el modelo use herramientas
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="none"
)
El modo "auto" es el más común en producción por una buena razón: un asistente de seguimiento de pagos debe poder decir «hola» sin desencadenar una consulta a la base de datos. El modelo responde directamente a preguntas generales y usa funciones solo cuando es relevante. Una lección completa más adelante en el curso cubre casos de uso específicos para any y none.
Puntos clave
- Las funciones deben devolver cadenas JSON, nunca objetos Python crudos
- Usa un diccionario de despacho para mapear nombres de funciones a sus implementaciones
functools.partiales ideal para prellenar parámetros como conexiones a bases de datos o DataFramestool_choicecontrola si el modelo puede o debe usar funciones (auto,any,none)- Gestiona siempre los casos de error en tus funciones (parámetros no válidos, datos faltantes)