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
- Trigger: El usuario envia un mensaje de texto al canal de chat definido (WhatsApp o Google Chat)
- Autenticacion: El sistema valida la identidad del usuario y sus permisos antes de procesar la instruccion
- Interpretacion: El agente (Claude o Gemini) analiza el mensaje y determina el modo de operacion — accion, consulta o reporte
- 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
- Log: Cada operacion se registra automaticamente en el log de auditoria con usuario, accion, empleado afectado y timestamp
- 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