389 lines
19 KiB
Markdown
389 lines
19 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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 |
|
|
|
|
---
|
|
## TASK 2 — Mapeo de endpoints BambooHR API
|
|
|
|
**Estado:** Completada
|
|
**Documento de entrega:** TASK 2 — Mapeo de endpoints BambooHR API
|
|
|
|
Se revisó la documentación de BambooHR API y se mapearon los endpoints relevantes para construir el BambooHR Agent como producto final. El mapeo cubre los tres modos principales del agente: **acción, consulta y reporte**.
|
|
|
|
### Categorías de endpoints identificadas
|
|
|
|
| Categoría | Uso dentro del agente |
|
|
| ------------------ | --------------------------------------------------------------------------------------- |
|
|
| Metadata | Validar conexión, campos, tablas y listas disponibles |
|
|
| Empleados | Buscar, listar y consultar empleados |
|
|
| Tablas históricas | Consultar o modificar `jobInfo`, `compensation`, `employmentStatus`, bonos y comisiones |
|
|
| Acciones | Crear empleados, actualizar datos básicos y agregar filas históricas |
|
|
| Archivos | Listar, subir, descargar o eliminar documentos de empleados |
|
|
| Reportes | Ejecutar reportes guardados y reportes personalizados |
|
|
| Datasets | Consultas avanzadas para reportería dinámica |
|
|
| Webhooks / cambios | Monitorear cambios en empleados y tablas |
|
|
| Time Off | Consultar tipos y balances de vacaciones/licencias |
|
|
|
|
### Endpoints principales documentados
|
|
|
|
```text
|
|
GET /api/v1/company_information
|
|
GET /api/v1/meta/fields
|
|
GET /api/v1/meta/tables
|
|
GET /api/v1/meta/lists
|
|
|
|
GET /api/v1/employees
|
|
GET /api/v1/employees/directory
|
|
GET /api/v1/employees/{id}
|
|
GET /api/v1/employees/{id}/tables/{table}
|
|
|
|
POST /api/v1/employees
|
|
POST /api/v1/employees/{id}
|
|
POST /api/v1/employees/{id}/tables/{table}
|
|
POST /api/v1/employees/{id}/tables/{table}/{rowId}
|
|
|
|
GET /api/v1/employees/{id}/files/view
|
|
POST /api/v1/employees/{id}/files
|
|
GET /api/v1/employees/{id}/files/{fileId}
|
|
DELETE /api/v1/employees/{id}/files/{fileId}
|
|
|
|
GET /api/v1/reports/{reportId}
|
|
POST /api/v1/reports/custom
|
|
|
|
GET /api/v1_2/datasets
|
|
GET /api/v1_2/datasets/{datasetName}/fields
|
|
POST /api/v1_2/datasets/{datasetName}/field-options
|
|
POST /api/v1_2/datasets/{datasetName}/data
|
|
|
|
GET /api/v1/employees/changed
|
|
GET /api/v1/employees/changed/tables/{table}
|
|
GET /api/v1/webhooks
|
|
GET /api/v1/meta/time_off/types
|
|
```
|
|
|
|
### Validaciones pendientes para TASK 3
|
|
|
|
La TASK 2 deja listo el mapa técnico. La TASK 3 debe validar estos endpoints con la API Key real de GLM, confirmar permisos reales del plan contratado y probar lectura/escritura sobre un empleado dummy autorizado por RRHH/IT.
|
|
|
|
No se deben ejecutar acciones de escritura sobre empleados reales.
|
|
|
|
## Testing
|
|
|
|
### Como probar el sistema
|
|
|
|
```bash
|
|
# 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.
|
|
[Junio 15, 2026] TASK 2 — Endpoints BambooHR API mapeados y documentados para acciones, consultas y reportes del producto final.
|
|
```
|
|
|
|
---
|
|
|
|
## 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 |