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

Arquitecturas de herramientas múltiples en producción

Lección 20 de 20 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Arquitecturas de herramientas múltiples en producción
  2. Arquitectura por capas
  3. Orquestador de producción
  4. Configuración declarativa
  5. Observabilidad y monitorización
  6. Gestión de costes
  7. Patrón: enrutador inteligente
  8. Lista de comprobación para producción
  9. Puntos clave
  10. Pon a prueba tus conocimientos

Actualizado el 2 de noviembre de 2026 según la documentación de OpenAI: la herramienta Code Interpreter ahora requiere un parámetro container (añadido a todos los ejemplos), las partes de entrada de texto se tipan como input_text, y la búsqueda web utiliza la herramienta web_search (web_search_preview es ahora una herramienta heredada sin filtros de dominio). Los archivos generados se recuperan mediante las funciones fichiers_generes y telecharger de la Lección 10. Fuentes: Code Interpreter · Búsqueda web.

Arquitecturas de herramientas múltiples en producción

Un prototipo de herramientas múltiples funciona porque una sola persona lo utiliza, conoce sus límites y lo reinicia cuando falla. La producción elimina las tres condiciones a la vez. Lo que se vuelve crítico no es la calidad de la respuesta —eso ya estaba ahí—, sino tres propiedades de las que carecía el prototipo: saber qué ocurrió cuando falla una llamada, evitar que un bucle descontrolado agote tu presupuesto y poder modificar el comportamiento sin necesidad de volver a desplegar.

Los patrones que siguen abordan cada uno de estos requisitos. No los adoptes todos de golpe: empieza por la observabilidad, porque sin ella ni siquiera sabrás cuál de los otros te falta.

Arquitectura por capas

Separar las responsabilidades en capas no es una cuestión de elegancia arquitectónica: hace que cada parte sea sustituible. El beneficio concreto es que puedes cambiar la orquestación sin tocar la interfaz, o añadir una herramienta sin reescribir la lógica de negocio. Las cuatro capas siguientes son el desglose mínimo que se mantiene en la práctica.

# Capa 1: Interfaz - recepción de solicitudes
# Capa 2: Orquestación - gestión de bucles y enrutamiento
# Capa 3: Ejecución - llamadas a herramientas y funciones
# Capa 4: Observabilidad - registros, métricas, trazas

from openai import OpenAI
from dataclasses import dataclass, field
from datetime import datetime
import json
import time
import logging

logger = logging.getLogger("multi-outils")

@dataclass
class TraceExecution:
    """Traza de ejecución para monitorización."""
    requete_id: str
    debut: float = field(default_factory=time.time)
    tours: list = field(default_factory=list)
    outils_utilises: list = field(default_factory=list)
    tokens_total: int = 0
    erreurs: list = field(default_factory=list)
    duree_totale: float = 0.0

Orquestador de producción

class OrchestreurProduction:
    def __init__(self, config: dict):
        self.client = OpenAI()
        self.config = config
        self.tools = self._construire_tools(config)
        self.dispatcher = self._construire_dispatcher(config)

    def _construire_tools(self, config: dict) -> list:
        """Construye el array de herramientas desde la configuración."""
        tools = []

        if config.get("file_search"):
            tools.append({
                "type": "file_search",
                "vector_store_ids": config["file_search"]["vector_stores"],
                "max_num_results": config["file_search"].get("max_results", 10)
            })

        if config.get("web_search"):
            tools.append({
                "type": "web_search",
                "search_context_size": config["web_search"].get("context_size", "medium")
            })

        if config.get("code_interpreter"):
            tools.append({"type": "code_interpreter", "container": {"type": "auto"}})

        for func in config.get("fonctions", []):
            tools.append(func)

        return tools

    def _construire_dispatcher(self, config: dict) -> dict:
        """Mapea los nombres de función con sus implementaciones."""
        return config.get("implementations", {})

    def executer(self, requete: str, fichiers: list = None,
                 max_tours: int = 10) -> dict:
        """Ejecuta una solicitud con trazado completo."""
        trace = TraceExecution(
            requete_id=f"req_{int(time.time()*1000)}"
        )

        content = [{"type": "input_text", "text": requete}]
        if fichiers:
            for fid in fichiers:
                content.append({"type": "input_file", "file_id": fid})

        messages = [{"role": "user", "content": content}]

        try:
            for tour in range(max_tours):
                debut_tour = time.time()

                response = self.client.responses.create(
                    model=self.config.get("model", "gpt-5.6-terra"),
                    input=messages,
                    tools=self.tools,
                    instructions=self.config.get("instructions", "")
                )

                trace.tokens_total += response.usage.total_tokens

                # Identificar llamadas a funciones
                appels = [
                    item for item in response.output
                    if item.type == "function_call"
                ]

                # Registrar herramientas utilizadas
                for item in response.output:
                    if hasattr(item, "type"):
                        trace.outils_utilises.append(item.type)

                trace.tours.append({
                    "numero": tour + 1,
                    "appels_fonction": len(appels),
                    "duree": time.time() - debut_tour
                })

                if not appels:
                    trace.duree_totale = time.time() - trace.debut
                    return {
                        "reponse": response.output_text,
                        "trace": trace
                    }

                # Ejecutar funciones personalizadas
                resultats = self._executer_fonctions(appels, trace)
                messages = response.output + resultats

        except Exception as e:
            trace.erreurs.append(str(e))
            trace.duree_totale = time.time() - trace.debut
            logger.error(f"Erreur requête {trace.requete_id}: {e}")
            return {"reponse": None, "erreur": str(e), "trace": trace}

        trace.duree_totale = time.time() - trace.debut
        return {"reponse": "Limite de tours", "trace": trace}

    def _executer_fonctions(self, appels: list, trace: TraceExecution) -> list:
        """Ejecuta funciones con manejo de errores."""
        resultats = []
        for appel in appels:
            try:
                func = self.dispatcher.get(appel.name)
                if not func:
                    raise ValueError(f"Fonction inconnue : {appel.name}")

                args = json.loads(appel.arguments)
                resultat = func(**args)
                resultats.append({
                    "type": "function_call_output",
                    "call_id": appel.call_id,
                    "output": json.dumps(resultat)
                })
            except Exception as e:
                trace.erreurs.append(f"{appel.name}: {str(e)}")
                resultats.append({
                    "type": "function_call_output",
                    "call_id": appel.call_id,
                    "output": json.dumps({"error": str(e)})
                })
        return resultats

Configuración declarativa

Sacar las definiciones del sistema del código y llevarlas a la configuración cambia quién puede intervenir. Ajustar un prompt de sistema, eliminar una herramienta o modificar un techo de costes se convierte en un cambio de archivo —revisable y reversible— en lugar de un despliegue. En un sistema que evoluciona semanalmente, esa es la diferencia entre iterar y reaccionar.

config_assistant_commercial = {
    "model": "gpt-5.6-terra",
    "instructions": (
        "Eres un asistente de ventas. Tienes acceso a datos del CRM, "
        "documentación de productos, la web y análisis de datos. "
        "Prioriza los datos internos, enriquécete con datos web."
    ),
    "file_search": {
        "vector_stores": ["vs_fiches_produit", "vs_propositions"],
        "max_results": 10
    },
    "web_search": {
        "context_size": "medium"
    },
    "code_interpreter": True,
    "fonctions": [
        {
            "type": "function",
            "name": "creer_opportunite",
            "description": "Crear una oportunidad en el CRM",
            "parameters": {
                "type": "object",
                "properties": {
                    "client": {"type": "string"},
                    "montant": {"type": "number"},
                    "probabilite": {"type": "integer"}
                },
                "required": ["client", "montant", "probabilite"],
                "additionalProperties": False
            },
            "strict": True
        }
    ],
    "implementations": {
        "creer_opportunite": lambda client, montant, probabilite:
            crm_service.creer_opportunite(client, montant, probabilite)
    }
}

orchestreur = OrchestreurProduction(config_assistant_commercial)
resultat = orchestreur.executer("Prepara una propuesta para Acme Corp")

Observabilidad y monitorización

Panel de métricas

Tres métricas son suficientes para empezar, y cada una responde a una pregunta diferente: la latencia por herramienta te dice cuál está ralentizando el sistema, la tasa de fallos por herramienta te indica cuál es frágil, y el coste por solicitud te muestra cuál se está disparando. Una media global de las tres no responde a ninguna de estas preguntas.

class MetriquesMultiOutils:
    def __init__(self):
        self.requetes = []

    def enregistrer(self, trace: TraceExecution):
        self.requetes.append({
            "id": trace.requete_id,
            "timestamp": datetime.now().isoformat(),
            "duree": trace.duree_totale,
            "tours": len(trace.tours),
            "tokens": trace.tokens_total,
            "outils": list(set(trace.outils_utilises)),
            "erreurs": len(trace.erreurs),
            "cout_estime": self._estimer_cout(trace)
        })

    def _estimer_cout(self, trace: TraceExecution) -> float:
        """Estima el coste en dólares de la ejecución."""
        # Tarifas aproximadas para gpt-5.6-terra: 2 $ / 12 $ por millón
        cout_input = trace.tokens_total * 0.6 * 0.000002
        cout_output = trace.tokens_total * 0.4 * 0.000012
        return round(cout_input + cout_output, 4)

    def rapport(self) -> dict:
        if not self.requetes:
            return {}
        durees = [r["duree"] for r in self.requetes]
        tokens = [r["tokens"] for r in self.requetes]
        couts = [r["cout_estime"] for r in self.requetes]

        return {
            "total_requetes": len(self.requetes),
            "duree_moyenne": sum(durees) / len(durees),
            "tokens_moyen": sum(tokens) / len(tokens),
            "cout_total": sum(couts),
            "taux_erreur": sum(1 for r in self.requetes if r["erreurs"] > 0) / len(self.requetes),
            "outils_les_plus_utilises": self._outils_frequents()
        }

    def _outils_frequents(self) -> dict:
        compteur = {}
        for r in self.requetes:
            for outil in r["outils"]:
                compteur[outil] = compteur.get(outil, 0) + 1
        return dict(sorted(compteur.items(), key=lambda x: -x[1]))

Gestión de costes

class GestionnaireCouts:
    def __init__(self, budget_quotidien: float = 50.0):
        self.budget = budget_quotidien
        self.depenses_jour = 0.0
        self.date_reset = datetime.now().date()

    def peut_executer(self, cout_estime: float) -> bool:
        """Comprueba si el presupuesto permite la ejecución."""
        aujourdhui = datetime.now().date()
        if aujourdhui > self.date_reset:
            self.depenses_jour = 0.0
            self.date_reset = aujourdhui

        return (self.depenses_jour + cout_estime) <= self.budget

    def enregistrer_depense(self, cout: float):
        self.depenses_jour += cout

    def budget_restant(self) -> float:
        return self.budget - self.depenses_jour

# Integración en el orquestador
gestionnaire_couts = GestionnaireCouts(budget_quotidien=100.0)

def executer_avec_budget(orchestreur, requete, **kwargs):
    cout_estime = 0.05  # Estimación conservadora
    if not gestionnaire_couts.peut_executer(cout_estime):
        return {"erreur": "Presupuesto diario alcanzado", "restant": 0}

    resultat = orchestreur.executer(requete, **kwargs)
    cout_reel = resultat["trace"].tokens_total * 0.000002
    gestionnaire_couts.enregistrer_depense(cout_reel)

    return resultat

Patrón: enrutador inteligente

A medida que los casos de uso se multiplican, la tentación es entregarlo todo a un único sistema equipado con todas las herramientas. Esa es la opción más costosa: cada solicitud, incluso las triviales, carga con el conjunto completo de definiciones de herramientas. Un enrutador que clasifique primero la solicitud y luego llame a un orquestador especializado mantiene los contextos cortos y hace que cada flujo sea medible por separado.

class RouteurIntelligent:
    def __init__(self):
        self.client = OpenAI()
        self.orchestreurs = {}

    def enregistrer(self, domaine: str, orchestreur: OrchestreurProduction):
        self.orchestreurs[domaine] = orchestreur

    def router(self, requete: str) -> dict:
        """Determina el dominio y enruta al orquestador correcto."""
        # Clasificación rápida con un modelo ligero
        response = self.client.responses.create(
            model="gpt-5.6-terra",
            input=f"Clasifica esta solicitud en un dominio: {requete}\n"
                  f"Dominios disponibles: {list(self.orchestreurs.keys())}\n"
                  f"Responde solo con el nombre del dominio.",
        )

        domaine = response.output_text.strip().lower()

        if domaine not in self.orchestreurs:
            domaine = "general"  # Respaldo

        logger.info(f"Requête routee vers : {domaine}")
        return self.orchestreurs[domaine].executer(requete)

# Configuración
routeur = RouteurIntelligent()
routeur.enregistrer("commercial", OrchestreurProduction(config_assistant_commercial))
routeur.enregistrer("support", OrchestreurProduction(config_support))
routeur.enregistrer("rh", OrchestreurProduction(config_rh))

# Uso
resultat = routeur.router("¿Cuántos días de vacaciones me quedan?")
# -> Enruta automáticamente al orquestador de RR. HH.

Lista de comprobación para producción

Esta lista de comprobación es intencionadamente breve. No pretende ser exhaustiva, pero cubre los puntos cuya ausencia te cuesta incidentes en lugar de molestias, y que no puedes añadir con prisas el día que el sistema ya está en manos de los usuarios.

checklist = {
    "securite": [
        "Validar argumentos para cada función",
        "Limitación de tasa por usuario",
        "Sanitizar entradas y salidas",
        "Sin datos sensibles en los registros"
    ],
    "fiabilite": [
        "Reintentos con retroceso en errores transitorios",
        "Interruptor de circuito por servicio externo",
        "Tiempo de espera por herramienta y por solicitud global",
        "Respaldo cuando una herramienta no está disponible"
    ],
    "performance": [
        "Ejecución paralela de llamadas independientes",
        "Caché de resultados de búsqueda frecuentes",
        "Limitar el número de iteraciones del bucle",
        "Elegir el modelo adaptado a la complejidad (gpt-5.6-terra vs gpt-5.6-terra)"
    ],
    "observabilite": [
        "Registro estructurado para cada llamada",
        "Métricas de latencia y coste",
        "Alertas sobre la tasa de error",
        "Traza completa de cada solicitud"
    ],
    "couts": [
        "Presupuesto diario con interruptor de circuito",
        "Estimación de costes antes de la ejecución",
        "Informe de gastos semanal",
        "Optimización de la elección del modelo por complejidad"
    ]
}

Puntos clave

  • Descomponer en capas: interfaz, orquestación, ejecución, observabilidad
  • Usar configuración declarativa para definir sistemas
  • Trazar cada ejecución para monitorización y depuración
  • Implementar un gestor de costes con presupuesto diario
  • Un enrutador inteligente distribuye las solicitudes a los orquestadores adecuados

Pon a prueba tus conocimientos

Llamadas a funciones, búsqueda, ejecución: todo el arsenal en cinco preguntas.

1. ¿Qué debe contener un buen esquema de función?

Respuesta: Tipos estrictos y descripciones operativas por parámetro; este es el contrato que el modelo usa para decidir cuándo llamar y cómo rellenar; la validación rechaza el resto.

2. Búsqueda web o búsqueda de archivos: ¿cómo elegir?

Respuesta: Búsqueda web para información pública y reciente; búsqueda de archivos para tus documentos indexados (fragmentación + clasificación integrada); y la búsqueda híbrida combina ambas cuando la respuesta abarca ambos mundos.

3. ¿Qué permite Code Interpreter en la API?

Respuesta: Ejecutar código en un entorno aislado: procesar CSV/Excel/imágenes, calcular con precisión, producir gráficos; el modelo razona, el código calcula, el entorno aislado protege.

4. ¿Para qué sirve Tool Search?

Respuesta: Para exponer dinámicamente un catálogo amplio de herramientas: el modelo busca la herramienta relevante en lugar de recibir cien esquemas a la vez; el contexto se mantiene ligero, las capacidades siguen siendo vastas.

5. ¿Qué reglas se aplican a una arquitectura de herramientas múltiples en producción?

Respuesta: Herramientas con alcance claro, manejo de errores y respaldos por herramienta, llamadas paralelas cuando son independientes, y observabilidad para cada llamada; la robustez se diseña herramienta por herramienta.

Cada herramienta tiene su terreno; la producción las combina; la arquitectura final anterior es tu plan de referencia.