Arquitecturas de herramientas múltiples en producción
En esta página
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 comoinput_text, y la búsqueda web utiliza la herramientaweb_search(web_search_previewes ahora una herramienta heredada sin filtros de dominio). Los archivos generados se recuperan mediante las funcionesfichiers_generesytelechargerde 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.