AI payroll assistant · 2025–2026
Payslip Agent
Explore how a payroll assistant handles payslips, questions, tax calculations, and protected documents while keeping each employee’s data separate.
Role and context
- Contribution
- FastAPI assistant, streaming responses, MCP tools, and identity and session isolation.
- Setting
- Internal payroll assistant at PeopleStrong · 2025–2026
- Scope
- Design overview only. Employee records, protected documents, and internal endpoints are not shared.
The problem
Payroll answers depend on sensitive employee data and exact calculations. The assistant needed to retrieve the right records without sharing user context between overlapping requests.
A closer look
Keeping employee identity separate
- Constraint
- Overlapping requests could not rely on shared, mutable employee context.
- Decision
- Employee and organization identity travel with each request, with expiring sessions in Redis. Retrieval, content queries, documents, and tax calculations use separate tools.
- Tradeoff
- Every tool call now needs explicit context rather than reading shared process state.
- Not included
- Contract tests cover tool registration and session validation. Employee data and internal test fixtures are not shared.
Explore the implementation
The FastAPI assistant streams responses and uses tools for payslips, documents, explanations, and tax calculations.
Four MCP tools handle retrieval, document access, content queries, and Indian tax calculations with session validation.
Request-scoped identity and expiring Redis sessions replace shared user context.
The implementation includes decimal calculations, protected documents, PII-aware logs, token-usage reporting, and tests for tool registration and session validation.
Architecture overview
View architecture
- Employee request
An employee asks a payroll question or requests a document.
- Identity gate
Employee and organization identity determine which records the tools can access.
- Tool layer
Separate tools handle payslips, explanations, documents, and tax calculations.
- Payroll sources
Payroll records and protected documents are retrieved through authenticated access.
- Session state
Each conversation has its own session with an expiry time.
- Response / document
The employee receives an answer, calculation, or document after access checks.
Select a step to explore the flow.
Design decisions
Request-scoped identity
Each request carries its own employee and organization context.
Separate tools
Payslip retrieval, documents, content queries, and tax calculations use separate tools.
Expiring sessions
Each session belongs to a user and has an expiry time.
Authenticated access
Payroll records and documents require authenticated access.
Results & limits
Implementation checks
The implementation includes request-scoped identity, expiring sessions, decimal calculations, protected document access, and PII-aware logging. Tests cover registration and session validation. This is an implementation summary, not an independent security certification.
Takeaway
User identity belongs in each request, not in shared process state.