La llegada de agentes que utilizan herramientas ha cambiado la forma de pensar algunas interfaces, pero no ha eliminado los fundamentos de ingeniería de software. Dos principios clásicos siguen siendo especialmente útiles: alta cohesión y bajo acoplamiento.
Un agente necesita decidir qué herramienta utilizar, construir entradas válidas e interpretar el resultado. Cuando los servicios mezclan responsabilidades o dependen de demasiados detalles internos, esa operación se vuelve frágil.
Alta cohesión: una herramienta, una intención clara
Un módulo tiene alta cohesión cuando sus elementos colaboran alrededor de una responsabilidad definida.
Compara estas herramientas:
manage_everything(data)create_project(input)
assign_project(project_id, collaborator_id)
close_project(project_id, closing_note)La primera herramienta requiere interpretar una entrada genérica y descubrir qué comportamiento ejecutar. Las siguientes expresan intenciones específicas.
Para un agente, la segunda opción reduce decisiones ambiguas. Para el equipo de desarrollo, facilita pruebas, permisos y mantenimiento.
Una herramienta cohesiva debería tener:
- Un nombre orientado a una acción.
- Una descripción precisa.
- Entradas mínimas y validadas.
- Un conjunto pequeño de resultados posibles.
- Errores distinguibles.
- Efectos secundarios conocidos.
Bajo acoplamiento: depender de contratos, no de detalles
El bajo acoplamiento reduce cuánto necesita saber un componente sobre otro.
Un agente no debería conocer tablas, nombres de columnas ni reglas distribuidas en la interfaz. Debería invocar un contrato estable:
{
"projectId": "prj_402",
"collaboratorId": "usr_18"
}La lógica de negocio valida si el proyecto existe, si el usuario puede asignarlo y si el colaborador está disponible. El contrato oculta detalles internos y protege invariantes.
Este desacoplamiento permite cambiar la base de datos o la interfaz sin modificar todas las integraciones.
No expongas CRUD como si fuera negocio
Las operaciones create, read, update y delete son útiles para construir software, pero no siempre representan la intención del usuario.
“Actualizar proyecto” puede significar:
- Cambiar el nombre.
- Asignar un colaborador.
- Aprobar una estimación.
- Cerrar el proyecto.
- Cancelarlo.
Cada acción puede tener reglas y permisos diferentes. Una API puramente genérica obliga al agente a conocer demasiados detalles y aumenta el riesgo de modificar campos incorrectos.
Conviene exponer acciones de dominio cuando existe una transición relevante:
approve_estimate
request_changes
assign_collaborator
complete_service
archive_projectUtiliza eventos para informar sin crear dependencias directas
Cuando una acción debe producir varias consecuencias, una arquitectura orientada a eventos puede reducir acoplamiento.
Después de crear un proyecto podrían ocurrir estas acciones:
- Enviar una notificación.
- Crear una carpeta.
- Registrar una actividad.
- Actualizar un indicador.
- Programar una tarea.
El servicio de proyectos puede publicar project.created. Otros componentes reaccionan según sus responsabilidades.
Esto evita que el servicio central conozca todos los detalles, pero introduce nuevas necesidades:
- Identificadores de evento.
- Reintentos.
- Idempotencia.
- Registro de fallos.
- Consistencia eventual.
- Observabilidad.
Los eventos no deben usarse solo porque parecen modernos. Son útiles cuando varios consumidores necesitan reaccionar de forma independiente.
Diseña errores que ayuden a decidir
Un mensaje como “operación fallida” no ayuda a un agente a seleccionar el siguiente paso.
Es mejor distinguir:
{
"code": "COLLABORATOR_UNAVAILABLE",
"message": "El colaborador no está disponible en el periodo del proyecto.",
"recoverable": true,
"suggestedAction": "select_another_collaborator"
}La respuesta no tiene que ordenar al agente qué hacer, pero sí debe aportar contexto suficiente para una decisión controlada.
Agrega idempotencia a las operaciones importantes
Los agentes y las integraciones pueden repetir una solicitud por un error de red o una respuesta tardía. Una acción idempotente evita crear resultados duplicados.
Un cliente puede enviar una clave única:
Idempotency-Key: req_2026_08_03_001Si la misma operación se recibe otra vez, el servicio devuelve el resultado previo en lugar de crear otro proyecto, cobro o mensaje.
Separa lectura, propuesta y ejecución
Para operaciones sensibles resulta útil dividir el flujo:
- Consultar información.
- Proponer una acción.
- Validar reglas.
- Solicitar confirmación.
- Ejecutar.
- Registrar el resultado.
Por ejemplo, un agente puede preparar una asignación y mostrar su impacto antes de confirmarla. Esta separación es especialmente importante en acciones financieras, eliminación de datos o comunicación externa.
Un criterio para evaluar herramientas
Antes de exponer una capacidad a un agente, revisa:
- ¿La acción tiene una intención única?
- ¿Las entradas pueden validarse completamente?
- ¿Los permisos están definidos en el servidor?
- ¿La respuesta permite verificar el resultado?
- ¿La operación tolera reintentos?
- ¿Existe un registro auditable?
- ¿Los errores indican si se puede recuperar?
- ¿La acción puede ejecutarse sin conocer detalles internos?
Si varias respuestas son negativas, el problema no se resuelve mejorando el prompt. Es necesario mejorar el servicio.
La arquitectura preparada para agentes no es una arquitectura exclusiva para IA. Es una arquitectura modular, observable y operable que también beneficia a aplicaciones web, integraciones y equipos humanos.