Imagina que llegan 50 mensajes de clientes en un día. Uno habla de un cobro duplicado, otro describe un error y otro solo pregunta por una función. Si una IA responde con texto libre, tu automatización terminará interpretando frases como “parece urgente” y adivinando dónde guardar cada caso. Para una función de producto real, primero define la estructura que tu software necesita.

Este ejemplo construye un clasificador de tickets con tres campos: categoria, prioridad y resumen. La API Responses de OpenAI permite pedir Structured Outputs mediante un JSON Schema estricto. Eso restringe la forma de la salida; no verifica por sí solo que la categoría sea correcta. Por eso añadiremos una comprobación de negocio y una cola de revisión.

1. Define un contrato pequeño

Usa categorías que realmente existan en tu operación. Aquí son facturacion, error y otro; la prioridad puede ser alta o normal. Evita pedir veinte campos “por si acaso”: cada campo adicional exige datos y decisiones que tal vez no estén en el mensaje.

Instala el SDK con python -m pip install openai y configura OPENAI_API_KEY en el entorno. Después guarda este script como clasificar.py:

import json
import os
from openai import OpenAI

SCHEMA = {
    "type": "object",
    "properties": {
        "categoria": {
            "type": "string",
            "enum": ["facturacion", "error", "otro"],
        },
        "prioridad": {
            "type": "string",
            "enum": ["alta", "normal"],
        },
        "resumen": {"type": "string"},
    },
    "required": ["categoria", "prioridad", "resumen"],
    "additionalProperties": False,
}

def clasificar(mensaje: str) -> dict:
    if not mensaje.strip():
        raise ValueError("El mensaje está vacío")
    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
    response = client.responses.create(
        model="gpt-6-luna",
        input=[
            {
                "role": "system",
                "content": (
                    "Clasifica tickets de soporte. No inventes datos. "
                    "Si falta contexto, usa categoria 'otro'. "
                    "Resume en una frase breve."
                ),
            },
            {"role": "user", "content": mensaje},
        ],
        text={
            "format": {
                "type": "json_schema",
                "name": "ticket",
                "strict": True,
                "schema": SCHEMA,
            }
        },
    )
    if response.status != "completed" or not response.output_text:
        raise RuntimeError("Sin salida completa; revisar respuesta")
    ticket = json.loads(response.output_text)
    if ticket["prioridad"] == "alta":
        ticket["revision_humana"] = True
    else:
        ticket["revision_humana"] = False
    return ticket

if __name__ == "__main__":
    caso = "Me cobraron dos veces la suscripción de octubre."
    print(json.dumps(clasificar(caso), ensure_ascii=False, indent=2))

En un caso así podrías recibir {"categoria":"facturacion","prioridad":"alta","resumen":"Cliente reporta un cobro duplicado"}, más la marca local revision_humana. Es un ejemplo de salida posible, no una respuesta garantizada ni una llamada que hayamos ejecutado con tu cuenta.

2. Separa formato, verdad y acción

El esquema hace que categoria sea una de las opciones permitidas, que prioridad esté presente y que no aparezcan claves extra. Sin embargo, un mensaje ambiguo todavía puede recibir una clasificación errónea. No envíes automáticamente un reembolso porque el JSON diga facturacion. Haz que el modelo proponga la etiqueta; tu sistema decide qué acciones requieren revisión.

En producción, guarda el mensaje original, la versión del esquema, la salida, el modelo y la corrección humana. Revisa semanalmente una muestra de casos normales y todos los de prioridad alta. Si ves que los tickets de facturación acaban en otro, mejora las instrucciones o añade ejemplos reales antes de multiplicar la automatización. Una métrica útil es precisión por categoría, no solo el porcentaje de JSON válido.

Primer uso: exporta OPENAI_API_KEY en tu terminal y ejecuta python clasificar.py. En Windows PowerShell, define la variable de entorno con $env:OPENAI_API_KEY. Antes de conectar una bandeja de entrada, prueba un único mensaje no sensible para comprobar que tu cuenta tiene acceso al modelo elegido. Si cambias el modelo, conserva el mismo esquema y compara resultados sobre los mismos tickets; no atribuyas una mejora a un modelo sin ese control.

3. Prueba con casos que rompan la ilusión

Crea una batería pequeña: cobro duplicado, error técnico con captura, consulta comercial, mensaje vacío y un caso que mezcle cobro y fallo. El script rechaza el vacío antes de pagar una llamada. El caso mixto debe ir a revisión si la categoría decide un flujo costoso. También prueba respuestas incompletas y negativas: el cliente no debe tratar una ausencia de salida como clasificación normal.

Para tickets con datos personales, envía solo el texto necesario y aplica tus reglas de privacidad. Si cambiar una categoría tiene consecuencias económicas, valida contra registros de negocio antes de ejecutar. La IA sirve para reducir lectura manual; el contrato y la revisión hacen que el resultado sea confiable.

Fuente: guía oficial de Structured Outputs y Responses de OpenAI. El patrón del SDK sigue el ejemplo oficial; la llamada real requiere tu clave y no fue ejecutada aquí.