HR Agent

An AI Digital Employee that performs all HridaOne HRMS operations on behalf of every employee — without requiring a separate login.

The HR Agent connects hrida-ai-studio's chat and workflow interface directly to the HridaOne HRMS backend. Every employee can ask it about their leave balance, payslips, attendance, or raise a support ticket — and get an accurate, real-time answer pulled from the live HRMS data — all without ever opening hridaone separately.

---

What the HR Agent can do

The agent exposes 11 HR tools backed by live HridaOne API calls:

Tool	What it does	Who can call it
get_my_profile	Current user's name, designation, department, email, status	All employees
search_employees	Search by name, email, or department (up to 10 results)	All employees
get_employee_profile	Detailed profile for any employee by ID	All employees
get_attendance_today	Clock-in, clock-out, total hours for today	All employees
get_attendance_calendar	Monthly attendance calendar (Present/Absent/Leave/WFH)	All employees
get_leave_balance	Remaining Earned, Sick, Casual, Compensatory leaves	All employees
get_my_leaves	Leave request history, filterable by status	All employees
apply_for_leave	Submit a leave application (pending manager approval)	All employees
get_payslip	Gross, net, deductions, PF, TDS for any month	All employees
create_support_ticket	Open an HR support ticket	All employees
get_admin_attendance_stats	Live org-wide attendance dashboard	HR Managers / Admins

Data scope is enforced by HridaOne's own RBAC — an employee can only see their own payslip, a manager sees their team, and an HR Admin sees everyone.

---

Architecture

User chat / Workflow run
      │
hrida-ai-studio backend
      │  Digital Employee filter:
      │    • Injects _context_id + _user_email into system message
      │    • Writes hrida:kc_token:{user_id} → Redis (10 min TTL)
      ▼
hrida-mcpo (port 8009)
      │  Routes tool calls to the hr-agent subprocess
      ▼
mcp_server.py  (stdio subprocess)
      │  Extracts _context_id and _user_email from LLM tool arguments
      ▼
tool.py
      │  Reads hrida:kc_token:{context_id} from Redis → user's KC token (SSO path)
      │  Fallback: email/password service account login (auto-refreshes on 401)
      │  get_my_profile: falls back to search_employees(email) when service account is used
      ▼
HridaOne REST API (port 8081)
      │  Validates token, enforces user-scoped RBAC
      ▼
Response returned to user

Key principle: Each user's Keycloak access token is stored in Redis before any tool call. The MCP subprocess reads it by looking up the _context_id the LLM passes as a hidden argument. HridaOne validates the token and enforces scope — employees can only see their own data, managers see their team, admins see everyone.

When Keycloak SSO is not configured (email/password login to Hrida AI Studio), the filter injects the logged-in user's email as _user_email. Tools that return "my" data use this email to search for the correct employee record via the service account, so users still get their own data rather than the service account's.

---

Prerequisites

Service	Default port	Notes
HridaOne HRMS	8081	Must be running and reachable
Redis	6379	Used for per-user KC token IPC
hrida-mcpo	8009	Starts the hr-agent subprocess
hrida-ai-studio backend	8080	Writes tokens, serves the Digital Employee

---

Setup

1. Create the HridaOne service account

The HR Agent needs a dedicated Admin account in HridaOne. Use the helper script:

cd hrida-ai-studio/scripts/hr-agent
python create_service_account.py \
  --api-url http://localhost:8081 \
  --email   hr-agent@yourcompany.com \
  --password "ChangeMe@2024!" \
  --tenant  ""          # leave empty for single-tenant

The script:

1. Checks that HridaOne is reachable
2. Creates the account via POST /api/auth/register (or confirms it already exists)
3. Verifies login end-to-end (/api/auth/me)
4. Updates hrida-mcpo/config.json automatically

Run with --dry-run to preview without making changes.

Manual creation

If registration is disabled (multi-tenant deployments require admin-created accounts), create the account from the HridaOne admin panel first, then re-run the script — it will detect the existing account and update the config.

2. Configure config.json

After the script runs, hrida-mcpo/config.json will contain:

"hr-agent": {
  "command": "uv",
  "args": [
    "run",
    "--with", "mcp>=1.17.0",
    "--with", "requests>=2.31.0",
    "--with", "redis>=5.0.0",
    "python",
    "/path/to/hrida-ai-studio/scripts/hr-agent/mcp_server.py"
  ],
  "env": {
    "HRIDAONE_API_URL":              "http://localhost:8081",
    "HRIDAONE_EMAIL":                "hr-agent@yourcompany.com",
    "HRIDAONE_PASSWORD":             "ChangeMe@2024!",
    "HRIDAONE_JWT_TOKEN":            "",
    "HRIDAONE_TENANT_CODE":          "",
    "HRIDAONE_USE_PER_USER_TOKEN":   "true",
    "REDIS_URL":                     "redis://localhost:6379"
  }
}

HRIDAONE_USE_PER_USER_TOKEN — set to "true" to enable per-user token isolation. When a user's Keycloak token is in Redis, tool calls are made as that user (true SSO isolation). When it is not (email/password login), the agent uses the service account and looks up the user's employee record by email.

HRIDAONE_JWT_TOKEN — optionally paste a pre-issued HridaOne JWT here to skip the login call on mcpo startup. Leave empty to use email/password auto-login. The token auto-refreshes when it expires (401 triggers a fresh login transparently).

HRIDAONE_EMAIL / HRIDAONE_PASSWORD is the service account used when no user-specific token is available. It must have ADMIN role in HridaOne to access org-wide data.

2. Start mcpo

cd hrida-mcpo
uvx hrida-mcpo --config config.json --port 8009

3. Create the HR Agent Digital Employee

In the hrida-ai-studio Admin Panel:

1. Go to Admin Panel → Digital Employees
2. Click + Add Agent and choose the HR Agent template
3. Set hrida-mcpo Base URL to http://localhost:8009
4. Set Introduction Message, Scope Description, and Escalation Contact
5. Click Run Setup — the bootstrap wires the knowledge base, filter, tool server, and agent model

4. Make it available to all employees

After setup, go to the agent's User Access section and leave the grants list empty — this makes the HR Agent visible to every user who has chat access. See Access Control for more options.

---

Token resolution priority

The agent resolves which HridaOne token to use in this order (highest priority first):

Priority	Source	When used
1	Redis: hrida:kc_token:{context_id}	User logged in via Keycloak SSO; true per-user isolation
2	HRIDAONE_JWT_TOKEN env var	Pre-configured service account token at mcpo startup
3	Email/password login	Auto-login on first call, cached until process restart or 401

Token auto-refresh: If the cached token (priority 2 or 3) has expired and HridaOne returns 401 Unauthorized, the agent automatically re-logs in with the service account credentials and retries the call transparently. No restart of mcpo is needed.

The Keycloak path (priority 1) enables true per-user data isolation. The service account path (priorities 2–3) is used for system-triggered operations and as the fallback when SSO is not configured.

---

How users see their own data (without SSO)

When a user chats with the HR Agent without Keycloak SSO, the service account token is used for HridaOne API calls. Without additional logic, get_my_profile would return the service account's profile — not the user's.

The HR Agent solves this without requiring SSO:

1. The Digital Employee filter reads the logged-in user's email from Hrida AI Studio's session (jane.doe@yourcompany.com).
2. It injects _user_email='jane.doe@yourcompany.com' into the system message alongside _context_id.
3. The LLM passes both hidden parameters in every tool call.
4. When get_my_profile is called and the service account is active, tool.py detects the mismatch (service account email ≠ _user_email) and automatically calls search_employees(jane.doe@yourcompany.com) to fetch the correct employee record.
5. For leave, attendance, and payslip tools, the system prompt instructs the LLM to call search_employees(email) first to obtain the employee ID, then use that ID for the subsequent data call.

The result: users always see their own HR data regardless of whether SSO is configured.

SSO gives true isolation

With Keycloak SSO, HridaOne enforces scope at the database level — a manager can see their team's data but not other departments. Without SSO, the service account has ADMIN access and the email-based lookup is only an application-level filter. For stricter data governance, enable SSO. See SSO Integration.

---

Multi-user behavior

Multiple employees can use the HR Agent simultaneously. Each conversation is isolated:

• The Digital Employee filter writes each user's Keycloak token to a separate Redis key (hrida:kc_token:{user_id}) and injects their email as _user_email.
• The injected _context_id and _user_email arguments carry the user's identity to the MCP subprocess.
• The subprocess reads only that user's token from Redis (SSO path) or routes queries by email (service account path).
• HridaOne receives the request scoped to the correct employee.

No user ever sees another user's data — even when the MCP server process is shared.

---

Verifying the connection

# 1. Check HridaOne is reachable
curl http://localhost:8081/api/health

# 2. Verify service account login works
curl http://localhost:8081/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@hrida.ai","password":"YourPassword"}'

# 3. Check all 11 tools are registered
curl http://localhost:8009/hr-agent/openapi.json | python -m json.tool

If step 3 returns 11 paths (one per tool), the agent is ready.

---

Environment variables

Variable	Default	Description
HRIDAONE_API_URL	http://localhost:8081	HridaOne backend base URL
HRIDAONE_EMAIL	—	Service account email (fallback auth)
HRIDAONE_PASSWORD	—	Service account password (fallback auth)
HRIDAONE_JWT_TOKEN	—	Pre-issued service account JWT (skips login call on startup; auto-refreshes on 401)
HRIDAONE_TENANT_CODE	—	X-Tenant-Code header value — required for multi-tenant deployments
HRIDAONE_USE_PER_USER_TOKEN	false	Set to "true" to enable Redis-based per-user KC token lookup (requires SSO)
REDIS_URL	redis://localhost:6379	Redis URL for per-user KC token storage and lookup

---

Troubleshooting

Agent returns "Login failed" or "HridaOne authentication failed" → Check HRIDAONE_EMAIL/HRIDAONE_PASSWORD in config.json. Run the service account setup script to verify credentials end-to-end:

python scripts/hr-agent/create_service_account.py --dry-run

Service account does not exist yet → Run the setup script to create it:

python scripts/hr-agent/create_service_account.py --api-url http://localhost:8081 --email hr-agent@company.com --password "Secret@2024!"

Users see the service account's data instead of their own (without SSO) → Expected behavior when HRIDAONE_USE_PER_USER_TOKEN is disabled. With the email-injection fix, get_my_profile and related tools automatically route by the logged-in user's email. If you still see wrong data, confirm HRIDAONE_USE_PER_USER_TOKEN is set to "true" in config.json and restart mcpo.

Tool calls return 401 Unauthorized after running for a while → The service account token has expired. Since v2 the agent auto-refreshes on 401 (re-logs in transparently). If you still see the error, the credentials may be wrong — verify with a manual login:

curl http://localhost:8081/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"hr-agent@company.com","password":"Secret@2024!"}'

get_admin_attendance_stats returns 403 → The token in use doesn't have ADMIN role in HridaOne. The service account must be created with "role": "ADMIN". Re-run create_service_account.py or update the account's role in the HridaOne admin panel.

redis.exceptions.ConnectionError in logs → Redis is not running or REDIS_URL is wrong. The agent falls back to the service account automatically, but per-user KC token isolation is lost. Start Redis (redis-server) and restart mcpo.

Cannot reach HridaOne → Verify the URL and port: curl http://localhost:8081/api/health. For Docker deployments, use the container name (http://hridaone-app:8080) rather than localhost.

---

Related

• Tools Reference — Parameters and example prompts for all 11 HR tools
• SSO Integration — Enable Keycloak SSO for true per-user data isolation
• Architecture & Token Flow — How tokens travel from the browser to HridaOne
• Troubleshooting — 401s, JIT provisioning, missing tools, stuck runs
• Access Control — Control which employees can use the HR Agent
• Digital Employees Overview — The full multi-agent platform