Conectar sistemas desconectados con un agente que lee y escribe por API

Cuando el ERP, el CRM y las hojas de cálculo no se hablan, alguien copia datos a mano. Esta guía muestra cómo poner un agente en medio con herramientas acotadas, permisos claros y una fuente de verdad por dato.

Mateo Pizaialabs.app · publicado 15 oct 2026

Empieza por el mapa de datos

Antes de escribir código, dibuja qué dato vive dónde.

Cada dato tiene una fuente de verdad. Los demás sistemas leen de ella o reciben copias sincronizadas. Si dos sistemas modifican el mismo dato sin reglas, ningún agente lo arregla.

Cuándo un agente aporta y cuándo basta una integración

Una integración clásica copia datos de A a B con reglas fijas. Resuelve bien la sincronización estructurada.

El agente aporta cuando hay interpretación:

• Una solicitud en lenguaje natural que hay que convertir en consultas a varios sistemas.
• Datos semiestructurados, como correos o notas, que hay que mapear a campos.
• Casos donde la acción depende del contexto de varios sistemas a la vez.

Ejemplo: "¿Qué clientes con pedidos retrasados tienen facturas vencidas?". Requiere cruzar logística, ERP y CRM. Un agente con herramientas lo resuelve sin construir un reporte nuevo.

Arquitectura

La pieza clave es la capa de herramientas. El agente no llama directo a las APIs. Llama funciones que tú defines.

Paso 1: diseña herramientas acotadas

Una herramienta buena hace una cosa y valida sus entradas.

@herramienta(permiso="lectura")
def pedidos_retrasados(dias_minimos: int = 1) -> list[dict]:
    return logistica.pedidos(estado="en_transito", retraso_min=dias_minimos,
                             campos=["pedido", "cliente_id", "retraso_dias"])

@herramienta(permiso="escritura", requiere_aprobacion=True)
def actualizar_contacto_crm(cliente_id: str, correo: str) -> dict:
    validar_correo(correo)
    return crm.actualizar(cliente_id, {"correo": correo})

Reglas:

• Nombres y descripciones claras. El modelo elige herramientas por su descripción.
• Parámetros tipados y validados.
• Respuestas con solo los campos necesarios.
• Nada de herramientas genéricas como "ejecutar consulta SQL" o "llamar cualquier endpoint".

Paso 2: separa lectura y escritura

Empieza solo con lectura. El agente responde preguntas y arma reportes. El riesgo es bajo y aprendes cómo lo usa tu equipo.

Luego agrega escritura en este orden:

1. Escrituras reversibles en sistemas internos: notas, etiquetas.
2. Actualizaciones de datos con aprobación.
3. Acciones con efecto externo, como enviar mensajes, siempre con política de aprobación.

Paso 3: credenciales y permisos

• Cada sistema tiene una cuenta de servicio para el agente, con el mínimo permiso necesario.
• Las credenciales viven en un gestor de secretos. Nunca en el prompt ni en el código.
• Si el agente actúa por un usuario, aplica los permisos de ese usuario. Un vendedor no ve, a través del agente, lo que no ve en el CRM.

Paso 4: manejo de errores de las APIs

Las APIs fallan. Tu capa de herramientas debe manejar:

• Límites de tasa: respeta los encabezados de la API y aplica backoff.
• Paginación: trae todos los resultados o informa al agente que hay más.
• Timeouts: reintenta lecturas. Para escrituras, usa idempotencia.
• Errores de validación: devuelve un mensaje claro al agente para que corrija o escale.

Ninguna herramienta devuelve un error crudo con datos internos o credenciales.

Paso 5: sistemas sin API

Muchos sistemas viejos no tienen API. Opciones, de más a menos recomendable:

1. Exportaciones programadas a un formato estándar, que se cargan en una base intermedia.
2. Acceso de solo lectura a la base de datos, con vistas acotadas.
3. Automatización de interfaz, solo como último recurso y con monitoreo, porque se rompe cuando cambia la pantalla.

Para las hojas de cálculo compartidas, define un formato fijo de columnas. Una hoja editada a mano por varias personas es una fuente frágil.

Paso 6: auditoría

Cada llamada a una herramienta queda registrada: quién la pidió, qué herramienta, parámetros, resultado y hora. Para escrituras, guarda el valor anterior y el nuevo.

Con eso puedes responder qué cambió el agente y revertir si hace falta.

Métricas

Errores comunes

• No definir fuente de verdad por dato.
• Herramientas genéricas con acceso total.
• Credenciales con permisos de administrador.
• Empezar por escritura.
• Ignorar paginación y límites de tasa.

Checklist

• Mapa de datos con fuente de verdad
• Herramientas acotadas y tipadas
• Lectura primero, escritura después
• Cuentas de servicio con mínimo permiso
• Gestor de secretos
• Manejo de límites, paginación y timeouts
• Auditoría de cada llamada
• Plan para sistemas sin API

Preguntas frecuentes