Operadores

Un operador es un nodo que ejecuta una acción determinista: sin LLM, sin aleatoriedad. Para una entrada dada, la salida es predecible.

Por qué usarlos

Cualquier lógica que se pueda escribir explícitamente debería escribirse así. Un LLM que «calcula un total» o «formatea una fecha» es un antipatrón: es más lento, más caro y puede equivocarse.

Regla práctica: si puedes escribir la función en 5 líneas de Python, es un operador — no un agente.

Tipos disponibles

operator HTTP

Realiza una llamada HTTP (REST, GraphQL). Configuración:

• URL (con marcadores de posición del contexto)
• Método, cabeceras, cuerpo
• Autenticación: bearer, basic, api_key_header (cabecera personalizada), u oauth2 (ver más abajo)
• Mapeo de la respuesta a slots

operator DB

Ejecuta una consulta contra una base de datos registrada en Administración → Bases de datos. Admite Postgres, MySQL, MongoDB y la base de datos interna de betool para las tablas definidas por el usuario.

file_transform

Transforma un archivo. Transformadores integrados:

• Lectura (PDF con OCR, DOCX, XLSX, CSV)
• Fragmentación (por página, por fragmento de tokens)
• Conversión (HTML → texto, Markdown ↔ HTML)
• Extracción de estructura (JSON a partir de un esquema)

compute

Cálculos y agregaciones sobre los slots del contexto:

• Filter / map / reduce sobre listas
• Estadísticas columna por columna (count, total, pct)
• Proyecciones de esquema
• Condiciones lógicas compuestas

payload_mapper

Compone una carga útil de salida a partir de los slots del contexto. Útil para preparar el cuerpo de un operador HTTP aguas abajo.

code_step

Cuando la lógica determinista supera lo que compute puede manejar, un code step ejecuta código personalizado en un sandbox — bloqueado por revisión humana. Consulta Code Steps gobernados.

Autenticación y secretos

Los operadores que se comunican con un sistema externo (HTTP, BD) referencian una cuenta registrada dentro de la organización. Las credenciales nunca son visibles dentro del propio pipeline — solo se referencia un nombre de cuenta.

Como resultado, rotar una contraseña no requiere ninguna edición en ningún pipeline.

OAuth2 saliente (client_credentials)

Para las API que requieren un token OAuth2 (cloud empresarial, ERP, proveedores de terceros), el operador HTTP admite el modo oauth2. Registras una credencial OAuth2 en la organización — token_url, client_id, client_secret, scope — y el nodo referencia solo un identificador no sensible.

En el momento de la llamada, betool obtiene un token y lo reutiliza mientras siga siendo válido; lo refresca de forma perezosa al expirar, sin tarea en segundo plano. El client_secret nunca lo devuelve la API de administración (solo se expone un indicador has_secret), y el token obtenido se coloca como Authorization: Bearer … en la petición saliente.

Rotar el secreto tras una rotación del lado del proveedor no requiere ninguna edición del pipeline: la siguiente llamada se refresca automáticamente.

Idempotencia

Todo operador que produzca un efecto secundario (HTTP POST, DB INSERT, envío de email) debe diseñarse para ser idempotente del lado del destino. Práctica recomendada:

• Incluye una idempotency_key en la carga útil (típicamente exchange_id).
• Comprueba del lado del destino si la clave ya ha sido procesada.

betool no reintenta automáticamente un operador fallido: es responsabilidad de tu pipeline orquestar la estrategia de reintento (bucle + condición).