HR Management Multi-Agent System

A comprehensive AI-powered HR management solution built on the Nasiko A2A (Agent-to-Agent) platform. This system uses 9 specialized agents orchestrated by a central manager to automate HR workflows.

Architecture Overview

                    ┌─────────────────────┐
                    │   HR Manager Agent  │
                    │    (Orchestrator)   │
                    └──────────┬──────────┘
                               │
        ┌──────────────┬───────┼───────┬──────────────┐
        │              │       │       │              │
        ▼              ▼       ▼       ▼              ▼
┌─────────────┐ ┌───────────┐ ┌───────────┐ ┌─────────────┐
│ Recruitment │ │ Onboarding│ │  Helpdesk │ │   Payroll   │
│   Agent     │ │   Agent   │ │   Agent   │ │   Agent     │
└─────────────┘ └───────────┘ └───────────┘ └─────────────┘
        │              │       │       │
        ▼              ▼       ▼       ▼
┌─────────────┐ ┌───────────┐ ┌───────────┐ ┌─────────────┐
│    Tax      │ │ Analytics │ │Compliance │ │  LinkedIn   │
│   Agent     │ │   Agent   │ │   Agent   │ │  Outreach   │
└─────────────┘ └───────────┘ └───────────┘ └─────────────┘
        │              │              │              │
        └──────────────┼──────────────┼──────────────┘
                       │              │
            ┌──────────┴──────────┐   │
            │   Shared Services   │   │
            │  MongoDB + Redis    │   │
            └─────────────────────┘   │
                                      │
                          ┌───────────┴───────────┐
                          │  LinkedIn API / Mock  │
                          └───────────────────────┘

Communication Protocol

All agents communicate via the A2A JSON-RPC 2.0 protocol, compatible with the Nasiko platform.

{
  "jsonrpc": "2.0",
  "id": "unique-id",
  "method": "message/send",
  "params": {
    "session_id": "session-123",
    "message": {
      "role": "user",
      "parts": [{"kind": "text", "text": "What's my leave balance?"}]
    }
  }
}

Agents

1. HR Manager Agent (Orchestrator) — Port 5000

Central agent that routes user requests to specialized agents.

• Intent Classification: Keyword + LLM-based query analysis
• Multi-Agent Coordination: Can combine responses from multiple agents
• Session Management: Maintains conversation context across turns
• Health Monitoring: Checks agent availability

2. Recruitment Agent — Port 5001

Handles hiring workflows.

• Resume parsing and skill extraction
• Candidate scoring with AI
• Interview scheduling (Google Calendar)
• Vacancy management

3. Onboarding Agent — Port 5002

Guides new hires through onboarding.

• Checklist creation and tracking
• Document collection and verification
• Equipment assignment (laptop, access card)
• Orientation scheduling

4. Helpdesk Agent — Port 5003

First point of contact for employee queries.

• Policy Q&A (RAG-based)
• Leave management (apply, balance, approval)
• Document requests (employment letter, etc.)
• Escalation handling

5. Payroll Agent — Port 5004

Handles compensation queries.

• Salary breakdown and payslips
• Bonus history
• HRA calculation and claims
• Promotion status

6. Tax Agent — Port 5005

Indian income tax specialist.

• Tax liability calculation (old vs new regime)
• Tax-saving scheme recommendations (80C, 80D, NPS)
• IT declaration submission
• Form 16 retrieval

7. Analytics Agent — Port 5006

Data-driven HR insights.

• Performance reviews and team metrics
• Vacancy pipeline and hiring reports
• Attrition risk analysis
• Skill matrix and headcount reports

8. Compliance Agent — Port 5007

Indian statutory compliance specialist.

• PF (EPF + EPS) contribution calculation
• ESI eligibility and contribution calculation
• Gratuity calculation under Payment of Gratuity Act
• Professional Tax (state-wise)
• Compliance filing calendar (monthly deadlines)
• Labour law information (working hours, maternity, POSH, minimum wage)

9. LinkedIn Outreach Agent — Port 5010 (New)

AI-powered LinkedIn candidate sourcing and outreach automation.

• Profile Search: Search for LinkedIn candidates by job title, skills, experience, and location
• Candidate Scoring: Score and rank candidates against job requirements (skills 40%, experience 30%, location 20%, education 10%)
• Outreach Message Generation: Generate personalized connection requests and InMail messages
• Candidate Details: Retrieve detailed profile information for specific candidates
• Uses mock LinkedIn data by default (6 Indian developer profiles) — set USE_MOCK_DATA=false for real API

Quick Start

Prerequisites

• Docker & Docker Compose
• OpenAI API Key
• MongoDB (included in docker-compose)
• Redis (included in docker-compose)

1. Environment Setup

cp .env.example .env
# Edit .env with your OPENAI_API_KEY

2. Start Infrastructure

docker-compose -f docker-compose.infra.yml up -d

3. Start All Agents

docker-compose up --build -d

4. Verify Health

# Check all agents
for port in 5000 5001 5002 5003 5004 5005 5006 5007 5010; do
  echo "Port $port: $(curl -s http://localhost:$port/health | python3 -m json.tool 2>/dev/null || echo 'not running')"
done

Usage

Send queries to the Manager Agent (port 5000), which routes to the right specialist:

# Ask about leave balance (→ routed to Helpdesk Agent)
curl -X POST http://localhost:5000/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "session_id": "user-123",
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "What is my leave balance for EMP001?"}]
      }
    }
  }'

# Ask about PF (→ routed to Compliance Agent)
curl -X POST http://localhost:5000/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "message/send",
    "params": {
      "session_id": "user-123",
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Calculate my PF contribution on ₹30,000 basic salary"}]
      }
    }
  }'

# Multi-domain query (→ routed to multiple agents)
curl -X POST http://localhost:5000/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "message/send",
    "params": {
      "session_id": "user-123",
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Give me my complete salary breakdown including tax and PF details"}]
      }
    }
  }'

# Search for candidates on LinkedIn (→ routed to LinkedIn Outreach Agent)
curl -X POST http://localhost:5000/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "4",
    "method": "message/send",
    "params": {
      "session_id": "user-123",
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Find Python developers in Bangalore with 3+ years experience and generate outreach messages for the top candidates"}]
      }
    }
  }'

Shared Library (hr-common)

The hr-common package provides shared utilities:

• HRDatabase: MongoDB wrapper with role-based collection access control
• GridFSStorage: File storage for documents
• RedisCache: Caching with TTL
• A2AClient: Inter-agent communication client
• Pydantic Models: Shared data models

Database Schema

Collection	Used By	Description
employees	All agents (read)	Employee master data
candidates	Recruitment	Job applicants
vacancies	Recruitment, Analytics	Open positions
interviews	Recruitment	Interview schedules
leaves	Helpdesk	Leave requests
leave_balances	Helpdesk	Leave balances
documents	Onboarding	Employee documents
onboarding_checklists	Onboarding	Onboarding progress
payroll	Payroll	Salary records
allowances	Payroll	Employee allowances
promotions	Payroll	Promotion history
tax_declarations	Tax	IT declarations
tax_schemes	Tax	Tax scheme info
escalations	Helpdesk	Complaint tracking
policies	Helpdesk	Company policies
performance_reviews	Analytics	Performance data
audit_log	All agents (write)	Audit trail

Caching Strategy

Data Type	TTL	Invalidation
Employee profile	5 min	On update
Leave balance	1 min	On leave change
Salary details	1 hour	Monthly
Policy docs	24 hours	Manual
Performance	1 hour	On review

Development

Running Individual Agents

cd hr-helpdesk-agent
docker-compose up --build

Local Development (without Docker)

cd hr-helpdesk-agent/src
pip install -r requirements.txt
python __main__.py --port 5003

Adding a New Tool

1. Add function with @tool decorator in tools.py
2. Add to tools list in agent.py
3. Update system prompt if needed

Adding a New Agent

1. Create directory: hr-<name>-agent/src/
2. Add models.py, tools.py, agent.py, __main__.py
3. Add AgentCard.json and Dockerfile
4. Register in docker-compose.yml
5. Add to manager's AGENT_REGISTRY and INTENT_KEYWORDS

Integration with Nasiko Platform

Register agents with the Nasiko gateway:

nasiko agent register --local-path ./hr-manager-agent

The agents follow the A2A JSON-RPC 2.0 protocol and are compatible with the Nasiko orchestration layer.

Port Mapping

Agent	Internal Port	External Port
Manager	5000	5000
Recruitment	5000	5001
Onboarding	5000	5002
Helpdesk	5000	5003
Payroll	5000	5004
Tax	5000	5005
Analytics	5000	5006
Compliance	5000	5007
LinkedIn Outreach	5000	5010

License

MIT License - Feel free to use and modify for your organization.