mgomez/bamboohr-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7501b6567cdb4d8665b06c66a7770502aadb7457
bamboohr-agent/README.md
T
Isaac_Aracena 7501b6567c Actualizar README.md
2026-06-12 16:44:41 +00:00

16 KiB
Raw Blame History

BambooHR Agent

Agente conversacional que permite al equipo de RRHH consultar, modificar y reportar data de empleados en BambooHR mediante lenguaje natural, eliminando errores de nomina y reduciendo tiempo operativo.

Informacion General

Campo Detalle
Proyecto BambooHR Agent
Area RRHH
Estado En Progreso
Developer Principal Isaac Aracena
IT Manager Luis Matos
Fecha de Inicio Junio 8, 2026
Fecha de Cierre Estimada Julio 19, 2026
Ciclo Shape Up Ciclo #1 — Semana 1 de 6
Board de Ejecucion https://pmit.digitalcompass.agency/boards/4inodhfrgx0h
PRD del Proyecto [https://docs.google.com/document/d/1OHn7v3nZeVh94-Gm0COQ1yjkX6HrRTqWhwamH4_gOgc/edit?usp=drive_link

Objetivo

Problema que resuelve

El equipo de RRHH (13-20 personas) gestiona toda la data de empleados entrando manualmente a BambooHR. Editar salarios, agregar empleados, desvincular, subir archivos, consultar informacion y generar reportes toma entre 5-15 minutos por operacion. Cuando hay multiples cambios pendientes, el equipo los pospone. Esos cambios olvidados llegan a nomina con datos incorrectos, generando errores que afectan al empleado, a RRHH y al area administrativa y de nomina.

Solucion implementada

Agente conversacional conectado a BambooHR via API que recibe instrucciones en lenguaje natural por chat y las ejecuta directamente. Opera en tres modos: accion (edita, agrega, desvincula, sube archivos), consulta (responde preguntas sobre data de empleados) y reporte (genera reportes estandar y personalizados). Cada operacion queda registrada en un log de auditoria.

Usuarios / Beneficiarios

  • Operan el agente: Equipo de RRHH (13-20 personas) y equipo IT
  • Acceso admin (settings de BambooHR): Solo Maximo Gomez
  • Se benefician del output: Equipo administrativo, nomina y empleados GLM en 14 paises

Arquitectura

Diagrama de flujo

Usuario envia instruccion por chat
        |
        v
Agente valida identidad y permisos del usuario
        |
        v
Agente interpreta instruccion en lenguaje natural
        |
        +---> Modo accion  --> Ejecuta cambio en BambooHR API
        |
        +---> Modo consulta --> Extrae data de BambooHR API --> Responde en chat
        |
        +---> Modo reporte  --> Genera reporte estandar o personalizado --> Entrega en chat
        |
        v
Registro en log de auditoria (quien, que, cuando)
        |
        v
Confirmacion al usuario

Stack tecnologico

Componente Tecnologia Proposito
Agente IA Claude / Gemini Interpretacion de lenguaje natural y ejecucion
Automatizacion n8n / Python Orquestacion del flujo
Interfaz de chat A definir por Luis Matos (WhatsApp / Google Chat) Canal de comunicacion con el agente
Autenticacion A definir por IT Validar identidad y permisos del usuario
Log de auditoria A definir por IT (Supabase / Google Sheets) Registro de cambios
Infraestructura Google Cloud / Servidor Virtual Hosting y ejecucion

Integraciones externas

Sistema Tipo de integracion Datos que fluyen
BambooHR API REST (full access) Lectura, escritura y reportes de data de empleados
Google Workspace OAuth Autenticacion de usuarios GLM
WhatsApp / Google Chat API Instrucciones entrantes y respuestas salientes
Supabase / Google Sheets API Log de auditoria de cambios

Configuracion y Setup

Prerequisitos

  • API key de BambooHR configurada (plan con full access confirmado)
  • Canal de chat definido y configurado (WhatsApp o Google Chat — pendiente decision de Luis Matos)
  • Sistema de autenticacion configurado (pendiente definicion de IT)
  • Variable de entorno BAMBOOHR_API_KEY configurada
  • Variable de entorno BAMBOOHR_SUBDOMAIN configurada
  • Almacenamiento del log de auditoria configurado (pendiente Supabase o Google Sheets)

Variables de entorno

Variable Descripcion Donde se obtiene
BAMBOOHR_API_KEY API Key de BambooHR BambooHR -> Admin -> API Keys
BAMBOOHR_SUBDOMAIN Subdominio de la cuenta GLM en BambooHR URL de BambooHR (ej. glm.bamboohr.com)
CHAT_CHANNEL Canal de chat activo (whatsapp / google_chat) A definir por Luis Matos
AUTH_SECRET Secret del sistema de autenticacion A definir por IT
LOG_STORAGE_URL URL del almacenamiento del log Supabase o Google Sheets — a definir
ADMIN_USER_ID ID del usuario con acceso a settings (Maximo Gomez) A definir al configurar autenticacion

NUNCA commitear credenciales al repo. Todas las keys van en el vault de credenciales GLM.

Instalacion / Deploy

# Clonar el repo
git clone https://gitea.glm.com/glm-it/bamboohr-agent

# Instalar dependencias
pip install -r requirements.txt

# Configurar variables de entorno
cp .env.example .env
# Editar .env con las credenciales reales

# Correr en local
python main.py

Como funciona

Flujo paso a paso

  1. Trigger: El usuario envia un mensaje de texto al canal de chat definido (WhatsApp o Google Chat)
  2. Autenticacion: El sistema valida la identidad del usuario y sus permisos antes de procesar la instruccion
  3. Interpretacion: El agente (Claude o Gemini) analiza el mensaje y determina el modo de operacion — accion, consulta o reporte
  4. Ejecucion:
    • Modo accion: Llama a los endpoints correspondientes de BambooHR API para ejecutar el cambio. Si la accion es destructiva (ej. desvincular empleado), el agente pide confirmacion antes de ejecutar
    • Modo consulta: Consulta BambooHR API, extrae la data solicitada y la formatea en lenguaje natural
    • Modo reporte: Genera el reporte solicitado (estandar o personalizado) a partir de la data de BambooHR
  5. Log: Cada operacion se registra automaticamente en el log de auditoria con usuario, accion, empleado afectado y timestamp
  6. Confirmacion: El agente responde al usuario en el chat con el resultado de la operacion

Triggers

Trigger Frecuencia Descripcion
Mensaje entrante en canal de chat On demand Usuario envia instruccion o consulta en lenguaje natural

Testing

Como probar el sistema

# Test unitario
python -m pytest tests/

# Test de integracion con BambooHR API
python tests/integration_test.py

# Test manual del agente
# Enviar mensaje de prueba al canal de chat configurado

Casos de prueba minimos

Caso Input Output esperado Estado
Editar salario "Actualiza el salario de [empleado] a $X" Confirmacion + cambio ejecutado en BambooHR Pendiente
Agregar empleado "Agrega nuevo empleado [datos]" Confirmacion + empleado creado en BambooHR Pendiente
Desvincular empleado "Desvincula a [empleado] desde hoy" Solicitud de confirmacion + ejecucion tras confirmar Pendiente
Subir archivo "Sube este contrato al perfil de [empleado]" Archivo subido al perfil en BambooHR Pendiente
Consulta de data "Cuantos dias de vacaciones tiene [empleado]?" Respuesta con dato correcto extraido de BambooHR Pendiente
Reporte estandar "Dame el headcount por pais" Reporte generado y entregado en el chat Pendiente
Reporte personalizado "Lista empleados con salario no actualizado en 6 meses" Reporte personalizado generado Pendiente
Acceso a settings sin permiso Usuario no-admin intenta modificar configuracion Acceso denegado, sin ejecucion Pendiente
Acceso a settings con permiso Maximo Gomez modifica configuracion Cambio ejecutado correctamente Pendiente
Log de auditoria Cualquier accion ejecutada Entrada registrada en log con todos los campos Pendiente

Errores conocidos y troubleshooting

Error Causa probable Solucion
401 Unauthorized en BambooHR API Key vencida o incorrecta Renovar key en BambooHR -> Admin -> API Keys y actualizar .env
Acceso denegado a settings Usuario no tiene permisos de admin Verificar ADMIN_USER_ID en variables de entorno
Agente no interpreta la instruccion Instruccion muy ambigua o incompleta El agente debe solicitar aclaracion al usuario antes de ejecutar
Log no registra la accion Conexion con almacenamiento del log fallida Verificar LOG_STORAGE_URL y credenciales de acceso
Canal de chat no recibe mensajes Webhook no configurado correctamente Revisar configuracion del canal en la plataforma correspondiente

Monitoreo

Como saber si el sistema esta funcionando

  • Log de auditoria: Revisar que las acciones ejecutadas esten siendo registradas correctamente
  • Canal de chat: Enviar un mensaje de prueba y verificar que el agente responda
  • BambooHR: Verificar aleatoriamente que los cambios ejecutados por el agente se reflejen correctamente
  • Alertas: A definir por IT — el sistema debe enviar alerta a Luis Matos si falla una ejecucion critica

Estructura del repositorio

/bamboohr-agent
├── README.md                  <- Este archivo
├── .env.example               <- Variables de entorno de ejemplo (sin valores reales)
├── main.py                    <- Punto de entrada principal
├── /src
│   ├── agent.py               <- Logica del agente — interpretacion de instrucciones
│   ├── bamboohr_client.py     <- Integracion con BambooHR API
│   ├── auth.py                <- Sistema de autenticacion y permisos
│   ├── audit_log.py           <- Registro de auditoria
│   └── chat_interface.py      <- Integracion con canal de chat
├── /tests
│   ├── test_agent.py          <- Tests del agente
│   ├── test_bamboohr.py       <- Tests de integracion con BambooHR API
│   └── integration_test.py    <- Tests de integracion completos
├── /docs
│   └── architecture.png       <- Diagrama de arquitectura (pendiente)
├── CHANGELOG.md               <- Historial de cambios
└── DECISIONS.md               <- Log de decisiones tecnicas

CHANGELOG

[Junio 8, 2026] v0.1 — Inicio del ciclo. Repo creado.

DECISIONS LOG

DEC-001 — Canal de chat

  • Fecha: Junio 2026
  • Contexto: El agente necesita un canal de comunicación para recibir instrucciones y responder al equipo de RRHH. GLM opera dentro de Google Workspace y el proyecto manejará acciones sensibles sobre información de empleados en BambooHR.
  • Opciones consideradas: WhatsApp API vs Google Chat API
  • Decisión: Usar Google Chat como canal principal para la primera versión del BambooHR Agent.
  • Razón: Google Chat permite trabajar con identidad corporativa de Google Workspace, usuarios internos, mejor trazabilidad y menor riesgo de suplantación que WhatsApp para acciones sensibles de RRHH.
  • Impacto: WhatsApp queda como posible canal futuro para notificaciones, recordatorios, alertas o consultas simples de bajo riesgo, pero no como canal principal para ejecutar acciones críticas en BambooHR.

DEC-002 — Sistema de autenticación

  • Fecha: Junio 2026
  • Contexto: Se necesita validar la identidad de cada usuario antes de permitir consultas, modificaciones, reportes o acciones sobre BambooHR.
  • Opciones consideradas: Google Workspace / OAuth vs sistema propio de usuarios vs autenticación por número de WhatsApp
  • Decisión: Usar Google Workspace como proveedor de identidad.
  • Razón: Evita crear usuarios y contraseñas propias, aprovecha las cuentas corporativas existentes y permite auditar cada solicitud por correo corporativo.
  • Impacto: Solo usuarios corporativos autorizados podrán interactuar con el agente. Antes de procesar cualquier instrucción, el sistema deberá validar identidad, rol y permisos del usuario.

DEC-003 — Modelo de autorización y permisos

  • Fecha: Junio 2026
  • Contexto: No basta con saber que el usuario pertenece a GLM. El agente debe validar que el usuario tenga permiso para ejecutar una acción específica según rol, país/área permitida, sensibilidad del dato y nivel de riesgo de la operación.
  • Opciones consideradas: Google Sheets vs Supabase/Postgres vs Neo4j
  • Decisión: Usar Neo4j como grafo de autorización y relaciones.
  • Razón: Neo4j permite modelar relaciones complejas entre usuarios, roles, países, áreas, acciones, campos sensibles, confirmaciones y aprobaciones.
  • Impacto: Neo4j guardará metadata de permisos y relaciones. No almacenará salarios reales, documentos, datos personales sensibles completos ni historial completo de BambooHR.

DEC-004 — Almacenamiento del log de auditoría

  • Fecha: Junio 2026
  • Contexto: Cada acción relevante debe quedar registrada con usuario, acción, empleado afectado si aplica, timestamp, resultado de autorización y resultado de ejecución.
  • Opciones consideradas: Supabase/Postgres vs Google Sheets
  • Decisión: Usar Supabase/Postgres como almacenamiento principal del log de auditoría.
  • Razón: Supabase/Postgres ofrece mayor control, estructura, trazabilidad, seguridad y escalabilidad que Google Sheets para un proyecto con datos sensibles de RRHH.
  • Impacto: Google Sheets podrá usarse solo como herramienta auxiliar de visualización o exporte, pero no como log principal de auditoría.

DEC-005 — Separación de responsabilidades entre n8n y Python Service

  • Fecha: Junio 2026
  • Contexto: n8n es ideal para orquestar flujos, recibir mensajes, llamar servicios externos y responder al usuario. Sin embargo, las reglas críticas de permisos, autorización, ejecución contra BambooHR y auditoría deben mantenerse centralizadas, versionadas y auditables.
  • Opciones consideradas: Hacer toda la lógica en n8n vs separar la lógica crítica en un Python Service
  • Decisión: Usar n8n como orquestador del flujo y un Python Service como capa de lógica crítica.
  • Razón: Separar la lógica crítica evita que reglas sensibles de RRHH queden dispersas en múltiples nodos visuales. El Python Service permite validar permisos, consultar Neo4j, ejecutar BambooHR API y registrar auditoría de forma más controlada y fácil de probar.
  • Impacto: n8n recibirá el mensaje, coordinará el flujo y responderá al usuario. El Python Service validará permisos, consultará Neo4j, ejecutará acciones autorizadas en BambooHR API y registrará auditoría en Supabase/Postgres.

DEC-006 — Política de seguridad para acciones sensibles

  • Fecha: Junio 2026
  • Contexto: El agente podrá ejecutar acciones que impactan datos sensibles de empleados, nómina y procesos de RRHH. Una instrucción mal interpretada no debe ejecutarse automáticamente si representa riesgo alto.
  • Opciones consideradas: Ejecutar acciones directamente vs solicitar confirmación/aprobación según riesgo
  • Decisión: Requerir confirmación explícita para acciones sensibles y aprobación cuando aplique según política interna.
  • Razón: Cambios de salario, desvinculaciones, creación de empleados, cambios de manager, cambios de fechas críticas y acciones que impacten nómina requieren control adicional antes de ejecutarse.
  • Impacto: Las acciones sensibles no se ejecutarán directamente después de ser interpretadas. El agente deberá pedir confirmación y registrar la operación en auditoría. Los settings de BambooHR quedan bloqueados para todos excepto Máximo Gómez.

Contactos del proyecto

Rol Nombre Contacto
Product Owner Maximo Gomez [completar]
IT Manager Luis Matos [completar]
Developer Isaac Aracena [completar]

Definition of Done

  • Agente ejecuta los 3 modos: accion, consulta y reporte
  • 95% de acciones ejecutadas correctamente en pruebas reales
  • Tiempo por operacion menor a 30 segundos
  • Sistema de permisos funcionando — settings bloqueados para no-admins
  • Log de auditoria registrando todas las operaciones
  • Todos los casos de prueba en estado OK
  • Codigo commiteado y pusheado a Gitea
  • README completo y actualizado
  • Variables de entorno documentadas en .env.example
  • Probado en ambiente real con equipo de RRHH
  • Luis Matos valido el output
  • Maximo aprobo el resultado final

Documento mantenido por el equipo GLM IT - Ultima actualizacion: Junio 8, 2026

Reference in New Issue View Git Blame Copy Permalink