Proyecto Multi-Agente LMPE1245-20260725

Este repositorio implementa una arquitectura de Multi-Agente Autónoma para estandarización y distribución de archivos basada en CrewAI.

Framework CrewAI

CrewAI es un marco de trabajo de código abierto en Python que permite orquestar equipos de agentes de inteligencia artificial autónomos para que collaboren. Los agentes se organizan mediante roles específicos, metas y herramientas para resolver tareas complejas de varios pasos, capacidad de ejecución a multiagente.

Componentes Principales

• Agentes: Unidades de IA con un rol, objetivo y contexto definidos.
• Tareas: Acciones específicas que los agentes deben completar.
• Herramientas (Tools): Utilidades que permiten a los agentes buscar información o ejecutar funciones.
• Crew (Equipo): La tripulación o grupo de agentes coordinados para cumplir un objetivo en común.

Funcionamiento

• Asignación por roles: Cada agente actúa como un experto (analista, redactor o investigador) en lugar de una IA genérica.
• Proceso de trabajo: Los flujos pueden ser secuenciales (un paso tras otro) o jerárquicos, donde un agente líder delega el trabajo.
• Razonamiento: Los modelos de lenguaje grande (LLM) sirven como motor para que los agentes decidan acciones y compartan resultados entre ellos.

Caso de uso

Actualmente se cuenta con el proceso de generación y almacenamiento de archivos de diferentes sistemas (canales), los canales almacenan en diferentes repositorios los archivos generados, además, son generados en varios formatos y con distintos nombres.

Por necesidad del negocio los archivos son renombrados, transformados a otras formatos (extensiones), finalmente son copiados a otros repositorios manualmente según la necesidad y unidad de negocio.

Problema Identificado:

Se necesita resolver el problema identificado en base a 2 agentes con CrewAI que automaticen los procesos manuales que realizan los usuarios. Para la solución de la estandarización y distribución de archivos provenientes de múltiples canales aplicando CrewAI se consdiera los siguientes puntos:

• Ventajas Principales: Modularidad en roles, gestión determinista de flujos de trabajo (Processes), integración robusta de funciones Python mediante decoradores (@tool) y compatibilidad con diversos LLMs.
• Características Clave: Configuración declarativa en YAML, memoria compartida y alta observabilidad en la traza de ejecución.
• Entorno: Ejecución local mediante script de Python en Visual Studio Code e interacción con PostgreSQL gestionado desde pgAdmin 4.

Planteamiento de Solución con CrewAI (2 Agentes)

Para que los agentes operen sobre archivos reales, se necesitará registrar herramientas personalizadas (Custom Tools) en Python (usando librerías como os, shutil, pandas o pathlib) para que la IA ejecute las acciones en el disco o repositorio.

Perfil de los 2 Agentes

1. Agente Analista de Formatos y Estandarización (File Standardizer Agent)

• Rol: Especialista en Transformación de Archivos.
  • Objetivo: Leer archivos de los repositorios origen, identificar su estructura actual, renombrarlos bajo el estándar de la empresa y convertirlos al formato requerido (ej. de CSV a Excel, o TXT a JSON).
  • Herramientas asignadas: Herramientas de lectura de directorios, detección de extensiones y scripts de conversión de formatos.

1. Agente de Clasificación y Distribución Logística (Data Logistics Agent)

• Rol: Gestor de Enrutamiento y Distribución de Datos.
  • Objetivo: Analizar el contenido o nombre del archivo estandarizado, determinar a qué unidad de negocio pertenece (Finanzas, Operaciones, etc.) y moverlo al repositorio destino correspondiente.
  • Herramientas asignadas: Herramientas de copiado/movimiento de archivos (locales, carpetas compartidas o buckets en la nube) y reglas de negocio.

1. Flujo de Ejecución

A continuación, se detalla el paso a paso correspondiente al diagrama de secuencia que contempla exclusivamente la ejecución directa de los dos agentes y sus respectivas tareas:

sequenceDiagram
    autonumber
    participant Crew as CrewAI Pipeline
    participant Agente1 as Agente Estandarizador
    participant Tool1 as Tool: transformar_formato_archivo
    participant Agente2 as Agente Distribuidor
    participant Tool2 as Tool: distribuir_archivo_final

    Note over Crew, Agente1: Tarea 1: Estandarización de Archivo[cite: 1, 2]
    Crew->>Agente1: Ejecutar tarea_transformacion[cite: 1, 2, 6]
    Agente1->>Tool1: Invoca transformar_formato_archivo(id_registro, ruta_archivo, tipo_conversion)[cite: 5]
    Tool1->>Tool1: Procesa conversión y actualiza DB (ESTANDARIZADO)[cite: 3, 5]
    Tool1-->>Agente1: Retorna mensaje de éxito de transformación[cite: 2, 5]
    Agente1-->>Crew: Finaliza Tarea 1[cite: 2]

    Note over Crew, Agente2: Tarea 2: Distribución y Logística[cite: 2]
    Crew->>Agente2: Ejecutar tarea_distribucion[cite: 2, 6]
    Agente2->>Tool2: Invoca distribuir_archivo_final(id_registro, ruta_local_archivo, destino, unidad_negocio)[cite: 4]
    Tool2->>Tool2: Mueve archivo a destino y actualiza DB (PROCESADO)[cite: 3, 4]
    Tool2-->>Agente2: Retorna confirmación de ruta final[cite: 2, 4]
    Agente2-->>Crew: Finaliza Tarea 2 y pipeline[cite: 2, 6]

2. Detalle del flujo paso a paso

• 1. Inicio de la Tarea 1: El pipeline de CrewAI activa al Agente Estandarizador para ejecutar la primera tarea de transformación.
• 2. Invocación de Herramienta de Estandarización: El agente invoca de forma directa la herramienta transformar_formato_archivo enviando los parámetros requeridos (id_registro, ruta_archivo, tipo_conversion).
• 3. Procesamiento y Actualización Transaccional: La herramienta ejecuta la conversión del archivo (utilizando librerías como pandas, Pillow, xmltodict o comtypes), actualiza el estado del registro en la base de datos a 'ESTANDARIZADO' y registra los logs correspondientes.
• 4. Retorno de Resultados de la Tarea 1: La herramienta devuelve el mensaje de éxito al agente estandarizador, el cual finaliza formalmente su subtarea y cede el control al pipeline.
• 5. Inicio de la Tarea 2: El pipeline de CrewAI activa al Agente Distribuidor para continuar con el flujo operativo.
• 6. Invocación de Herramienta de Logística: El segundo agente invoca la herramienta distribuir_archivo_final pasando el ID de registro, la ruta local del archivo transformado, el destino y la unidad de negocio correspondiente.
• 7. Enrutamiento y Cierre del Proceso: La herramienta traslada físicamente el archivo hacia su repositorio final (Local, SFTP o SharePoint), actualiza el estado del registro en la base de datos a 'PROCESADO' y consolida la auditoría.
• 8. Finalización del Pipeline: Se retorna la confirmación de la ruta final al agente distribuidor, concluyendo de manera exitosa la ejecución del flujo secuencial entre ambos agentes.

3. Justificación del Programa Desarrollado

1. Problema que resuelve: Automatiza la estandarización y distribución de archivos provenientes de múltiples canales corporativos (CSV, Word, XML, Imágenes) hacia repositorios finales (Local, SFTP, SharePoint), eliminando la intervención manual repetitiva.
2. Abstracciones principales: Agent (roles especializados), Task (unidades de trabajo), Tools (@tool para lógica determinista) y Runner (kickoff para la ejecución del pipeline).
3. Adecuación al caso de uso: Permite separar claramente la labor técnica de transformación de datos de la gestión logística operativa mediante dos agentes coordinados.
4. Diferencia frente a LangChain / LangGraph: CrewAI ofrece un nivel de abstracción superior basado en roles y metas con configuración declarativa en YAML, evitando la programación manual compleja de grafos de estado.
5. Limitaciones y curvas de aprendizaje: Dependencia estricta del entorno operativo Windows (comtypes) para la conversión nativa de MS Word a PDF, y la necesidad de refinar los prompts de comportamiento (backstory) para evitar llamadas erróneas a las herramientas.

4. Análisis del Problema de Negocio

• Problema del usuario: Operación fragmentada con múltiples canales y formatos de archivos no normalizados que requieren transformaciones y traslados manuales.
• Tarea mejorada: Renombrado, conversión de formatos y enrutamiento hacia repositorios corporativos finales.
• Información recibida por el agente: ID de registro, ruta física del archivo, tipo de conversión y repositorio de origen.
• Decisiones previas: Validación de formatos soportados, selección de la herramienta adecuada y verificación transaccional en base de datos.
• Resultado esperado: Archivos transformados, distribuidos en su destino final y trazabilidad completa en PostgreSQL.
• Valor del agente frente a llamada directa: Un LLM por sí solo no puede manipular archivos locales, conectarse a servidores SFTP ni actualizar bases de datos relacionales; el agente combina razonamiento con ejecución real de software.

5. Requisitos Técnicos y Arquitectura en Capas

5.1. Componentes de la Solución (Tablas y Agentes)

| Componente / Recurso | Nombre Técnico | Descripción Funcional | | --- | --- | --- | | Tabla | control_archivos | Almacena el inventario de archivos, estados y metadatos. | | Tabla | logs_agentes | Registra la traza de auditoría y eventos de ejecución. | | Agente 1 | agente_estandarizador | Modelo gpt-4o-mini. Especialista en lectura y conversión. | | Agente 2 | agente_distribuidor | Modelo gpt-4o-mini. Gestor logístico y de distribución. | | Seguridad | Archivo .env | Credenciales protegidas (DATABASE_URL, SFTP, SharePoint). | | Herramientas | transformar_formato_archivo | Conversiones mediante pandas, Pillow, xmltodict, comtypes. | | Herramientas | distribuir_archivo_final | Envíos locales, paramiko (SFTP) y Office365-REST (SharePoint). |

5.2. Arquitectura en Capas

El sistema procesa de manera multi-agente archivos provenientes de diversas fuentes para su normalización y envío controlado.

1. Capa de Orquestación y Control

• Pipeline CrewAI: Actúa como el núcleo de procesamiento secuencial apalancado en modelos de lenguaje (gpt-4o-mini), interpretando y coordinando las reglas de ejecución.
• Gestión de Reglas y Entorno Virtual: Administra la configuración estática mediante esquemas definidos en agents.yaml y tasks.yaml, operando de manera aislada bajo entornos de Python y variables seguras .env.

2. Capa Inteligente y Roles (Agentes)

• Agente Estandarizador: Recibe la asignación inicial de la tarea de transformación para normalizar la estructura de los datos de entrada.
• Agente Distribuidor: Toma el contexto heredado del agente anterior para gestionar el flujo logístico de salida.

3. Capa de Ejecución y Herramientas (@tool)

• transformar_formato_archivo: Herramienta invocada por el primer agente para extraer y convertir el contenido heterogéneo (PDFs, XMLs, Words, CSVs) hacia un formato estándar unificado.
• distribuir_archivo_final: Herramienta invocada por el segundo agente para direccionar los archivos procesados hacia sus destinos finales.

4. Capa de Persistencia

• PostgreSQL Metadata: Almacena la tabla transaccional control_archivos para el control de estados y la bitácora de trazabilidad en logs_agentes.

5. Distribución de Archivos y Entorno de Desarrollo

• Canales de Salida: Gestiona el almacenamiento y envío final hacia repositorios de tipo Local, SFTP o SharePoint.
• Entorno de Ejecución: Respaldado por herramientas operativas como Visual Studio Code, Anaconda, Git Bash y pgAdmin 4.

5.3. Controles y Pruebas Mínimas

1. Validación de entradas: Comprobación de existencia de registros pendientes (PENDIENTE) y validación de tipos de conversión admitidos.
2. Manejo de excepciones: Bloques try-except integrados en cada herramienta y registro automático de fallos críticos en logs.
3. Respuesta ante falta de información: Validación previa en el script principal para notificar lotes vacíos.
4. Control fuera de dominio: Restricción estricta de los tipos de conversión permitidos.
5. Confirmación de acciones sensibles: Operaciones acopladas al control transaccional de la base de datos relacional.
6. Timeouts / Fallback: Uso de un LLM estable y optimizado (openai/gpt-4o-mini).
7. Protección de credenciales: Uso de python-dotenv y exclusión de claves en código fuente.

Instructivo de Ejecución

1. Abrir el proyecto en Visual Studio Code.
2. Configurar la base de datos en pgAdmin 4 ejecutando el script inicial (database/init.sql).
3. Crear el archivo .env con las credenciales requeridas.
4. Instalar las dependencias del entorno:

pip install -r requirements.txt

1. Ejecutar el orquestador principal:

python main.py

---

Documentación elaborado por Hadson Paredes - 2026

• Repositorio: File-Standardizer-Agent-CrewAI
• Disponible como recurso públicos en Hadson.Tech

<hr> <h4 align="center"> Publicaciones en mis redes sociales y repositorio GitHub</h4> <div align="center"> <h3>Sígueme en mis redes sociales</h3> <a href="https://github.com/devhadson"> <img src="https://img.shields.io/badge/GitHub-devhadson-black?logo=GitHub&style=flat-square" target="_blank" alt="GitHub"> </a> <a href="https://www.linkedin.com/in/hadson-paredes/"> <img src="https://img.shields.io/badge/LinkedIn-Hadson%20Paredes-blue?logo=linkedin&style=flat-square" target="_blank" alt="LinkedIn"> </a> <a href="https://www.facebook.com/hadson.paredescordova/"> <img src="https://img.shields.io/badge/Facebook-Hadson%20Paredes%20Cordova-Gree?logo=facebook&style=flat-square" target="_blank" alt="Facebook"> </a> <a href="https://x.com/hadson_paredes"> <img src="https://img.shields.io/badge/Hadson%20Paredes-black?logo=x&style=flat-square" target="_blank" alt="X"> </a> </div>