# 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 ``` ## TASK 3 — Integración base con BambooHR API **Estado:** Validada técnicamente en n8n. Se construyó un workflow de validación base para probar la integración real con BambooHR API usando HTTP Request en n8n. La prueba se realizó con API Key real de GLM, autenticación Basic Auth y subdominio `glm.bamboohr.com`. ### Validaciones realizadas * Conexión correcta con BambooHR API. * API Key real configurada en credencial segura de n8n. * Subdominio real confirmado: `glm.bamboohr.com`. * Lectura de metadata: `company_information`, `meta/fields`, `meta/tables` y `meta/lists`. * Lectura de directorio de empleados. * Identificación de empleado de prueba existente: * ID: `40557` * Nombre API: `Bruce Wayne` * Nombre preferido: `Batman` * Correo: `psmaxg1@gmail.com` * Lectura de empleado por ID. * Escritura básica sobre empleado de prueba mediante `POST /api/v1/employees/{id}`. * Confirmación de escritura básica actualizando `workPhoneExtension`. * Escritura en tabla histórica `jobInfo` mediante `POST /api/v1/employees/{id}/tables/jobInfo`. * Confirmación por `GET /api/v1/employees/{id}/tables/jobInfo`. ### Decisiones de prueba No se creó un empleado nuevo con `POST /api/v1/employees`, porque RRHH ya contaba con un empleado de prueba existente. Esto evita generar una licencia adicional innecesaria. Las escrituras en `compensation` y `employmentStatus` no se ejecutaron en esta tarea por tratarse de datos sensibles relacionados con nómina y estatus laboral. Quedan pendientes para una prueba controlada posterior con autorización explícita de RRHH/IT. ### Resultado La integración base conecta correctamente con BambooHR, lee información real y escribe datos sobre un empleado de prueba sin errores. La TASK 3 queda validada a nivel técnico para continuar con la siguiente capa del producto. ## 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