mgomez/bamboohr-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7e796b9dd590c5e0610b9a22f24f8a74a53f8c84
bamboohr-agent/README.md
T
mgomez 7e796b9dd5 Actualizar README.md
2026-06-04 19:45:34 +00:00

12 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 [Link a Kan.bn — completar al crear el board]
PRD del Proyecto [Link al PRD — completar al subir a Google Drive]

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 (WhatsApp vs Google Chat)

  • Fecha: Pendiente — Semana 1
  • Contexto: El agente necesita un canal de comunicacion. GLM opera en Google Workspace pero Maximo usa WhatsApp para operaciones similares
  • Opciones consideradas: WhatsApp API vs Google Chat API
  • Decision: A definir por Luis Matos en Semana 1
  • Razon: Pendiente

DEC-002 — Sistema de autenticacion

  • Fecha: Pendiente — Semana 1
  • Contexto: Se necesita validar la identidad de cada usuario para aplicar permisos correctamente
  • Opciones consideradas: Google OAuth vs sistema propio vs otro
  • Decision: A definir por IT en Semana 1
  • Razon: Pendiente

DEC-003 — Almacenamiento del log de auditoria

  • Fecha: Pendiente — Semana 1
  • Contexto: Cada accion ejecutada debe quedar registrada con usuario, accion, timestamp y resultado
  • Opciones consideradas: Supabase / Postgres vs Google Sheets
  • Decision: A definir por IT en Semana 1
  • Razon: Pendiente

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