🕐 HR Agent MCP

🕐 HR Agent MCP

Agente conversacional de RH que substitui telas estáticas de sistema de pontopor uma interface de conversa — com MCP, LangGraph, RAG e BigQuery.

🔗 Demo online: (senha: solicitar) ·

O que ele faz

O agente atende quatro tipos de pedido em linguagem natural, todos via chat:

• Consulta de batidas — "como foram as batidas da Ana nas últimas duassemanas?" retorna o histórico, com atrasos e batidas incompletasdestacados.
• Dúvidas de política, com fonte — "qual a tolerância de atraso?" érespondido com RAG sobre as políticas de RH da empresa, citando odocumento de origem, não apenas um resumo genérico.
• Aprovação de ajuste com confirmação humana — pedidos de escrita (porexemplo, aprovar um ajuste de ponto) passam por um card de confirmaçãoexplícito antes de qualquer alteração no banco, e ficam registrados emtrilha de auditoria.
• Analytics no BigQuery — perguntas analíticas ("qual equipe acumuloumais horas extras por mês?") geram SQL via LLM, que passa por uma camadade governança antes de tocar o warehouse.

GIF da demo aqui.

Arquitetura

flowchart TD
    UI[Streamlit — chat + painel MCP] --> AG[LangGraph — agente ReAct\nmemória + human-in-the-loop]
    AG -->|MCP stdio| SRV[Servidor MCP — FastMCP]
    SRV --> T1[consultar_batidas] --> DB[(SQLite\noperacional)]
    SRV --> T2[listar/aprovar ajustes] --> DB
    T2 --> AUD[(audit_log)]
    SRV --> T3[consultar_politica] --> RAG[FAISS — políticas de RH]
    SRV --> T4[analytics_rh] --> BQ[(BigQuery\nrh_analytics)]
    ETL[ETL Python\nextract→transform→load] --> DB
    ETL --> BQ

O sistema separa deliberadamente dois mundos: o operacional (SQLite,leitura e escrita, latência baixa, dados do dia a dia como batidas eajustes) e o analítico (BigQuery, somente leitura, dados agregados paraperguntas de gestão). Essa separação evita que consultas analíticas pesadasconcorram com o caminho transacional e mantém o warehouse como uma cópiaderivada e auditável, nunca como fonte de verdade para escrita. Por issotoda operação de escrita — hoje, aprovar um ajuste de ponto — passa porinterrupt (o grafo pausa e devolve o controle à interface, que exigeconfirmação humana explícita) e é registrada em audit_log antes de serconsiderada concluída: o agente nunca escreve silenciosamente.

Capacidades demonstradas

Rodando localmente

git clone https://github.com/cydgxbriel/hr-agent-mcp.git
cd hr-agent-mcp
cp .env.example .env       # preencher OPENAI_API_KEY
uv sync
uv run python -m etl.pipeline
uv run streamlit run app/main.py

APP_PASSWORD é opcional em desenvolvimento (protege o app quando expostopublicamente). BigQuery também é opcional: sem credencial configurada, oagente segue funcionando normalmente e a tool de analytics degrada de formagraciosa, informando que o recurso está indisponível em vez de falhar.

BigQuery (opcional)

1. Criar um projeto no GCP Sandbox (gratuito, sem cartão de crédito).
2. Criar uma service account com papéis BigQuery Data Editor + BigQueryJob User nesse projeto (Data Editor cria datasets; Job User executajobs de carga/consultas — privilégio mínimo).
3. Baixar a chave JSON da service account.
4. Preencher GCP_PROJECT_ID no .env com o id do projeto criado — semessa variável o cliente BigQuery permanece desabilitado, mesmo com acredencial configurada.
5. Apontar GOOGLE_APPLICATION_CREDENTIALS para o caminho do arquivo (usolocal) ou colar o conteúdo em GCP_SERVICE_ACCOUNT_JSON (uso noStreamlit Cloud, onde não há sistema de arquivos persistente).
6. Rodar uv run python -m etl.pipeline para carregar o datasetrh_analytics (tabela agregados_mensais) no BigQuery.

Dados

Todos os dados são 100% sintéticos, gerados com Faker (seed 42): colaboradores,batidas de ponto, ajustes e políticas de RH são personas e documentosfictícios, criados exclusivamente para esta demonstração. Nenhum dado realde nenhuma empresa é usado ou referenciado em nenhum ponto do projeto.

Stack

• Python 3.11+
• uv (gestão de ambiente e dependências)
• mcp / FastMCP (servidor MCP stdio)
• LangGraph (orquestração do agente ReAct)
• langchain-mcp-adapters (cliente MCP do agente)
• langchain-openai (gpt-4o-mini)
• langchain-community / FAISS (RAG)
• pandas (ETL)
• Faker (geração de dados sintéticos)
• google-cloud-bigquery
• Streamlit (interface de chat)
• pytest (28 testes)
• ruff (lint)