primitives agent

Agent

Agents are the human intermediaries between property seekers and listings. They schedule visits, respond to user questions, and accumulate satisfaction ratings. The Agent primitive is intentionally lean: it captures who the agent is and how busy they are, leaving the matching logic to the visit scheduling flow.

Active contributors: Saksham, Ravi

Model

File: app/models/agents.py

The Agent table is small but indexed for load-balancing queries. Key columns:

• name, contact_number, description, avatar_url - profile fields surfaced in the agent directory
• languages - JSON list of supported languages, used to match non-English speakers
• agent_type - AgentType enum (general, specialist, senior). Drives assignment priority.
• experience_level - ExperienceLevel enum (beginner, intermediate, expert)
• is_active - whether the agent can be assigned new leads at all
• is_available - real-time availability flag, toggled by the visit assignment flow
• working_hours - JSON dict of day-of-week to time windows
• total_users_assigned - denormalized counter used as the load-balancing tiebreaker
• user_satisfaction_rating - rolling average of AgentInteraction.user_satisfaction (1-5)
• is_seed_data - marks demo agents

Relationships

• User - one-to-many. A user may be linked to one agent for the duration of an engagement.
• Visit - one-to-many. Visits are the primary workload unit; each visit optionally carries an agent_id.
• AgentInteraction - one-to-many. Every chat, call, and email between an agent and a user is logged with response_time_seconds and user_satisfaction. This table feeds the satisfaction rating.

Load balancing

When a visit is scheduled, the service layer picks an agent by:

1. Filter to is_active = true and is_available = true.
2. Join to User and count live assigned users per agent (count(User.id)).
3. Sort by user count ascending (least-loaded first), limit 1.

The working_hours column and user_satisfaction_rating exist on the model but are not currently used in the assignment query. There is no dedicated app/services/agent.py file; assignment logic lives in app/services/agent/crud.py (assign_agent_to_user) and the agents REST endpoint module (app/api/api_v1/endpoints/agents.py).

REST surface

The /api/v1/agents router exposes the agent directory, profile details, and interaction history. Agent tools also surface through the admin MCP server (/mcp-admin) under the agent_* prefix - see features/mcp-servers.md.