Skip to main content
Agents are users who handle support tickets. Teams allow you to organize agents into groups for better ticket management and access control.

​
Agents

Agents are created from the HD Agent doctype and are linked to User records in the system.

​
Agent Fields

​
user
Link
required
The User account associated with this agent. This becomes the agent’s unique identifier.
​
agent_name
string
The display name of the agent. Automatically synced with the User’s full name.When changed, updates the User’s first_name and last_name fields.
​
user_image
file
Profile image for the agent. Automatically synced with the User’s user_image field.
​
is_active
boolean
default:"true"
Whether the agent is active and can be assigned tickets.Inactive agents cannot receive new assignments but retain access to existing tickets.

​
Agent Roles

Agents can have one of two roles: Agent
  • Can view and respond to assigned tickets
  • Can create and manage their own saved replies
  • Can view knowledge base articles
  • Limited to tickets within their permissions
Manager (Agent Manager)
  • All Agent permissions
  • Can manage other agents and teams
  • Can configure assignment rules
  • Can access helpdesk settings
  • Has System Manager role for administrative tasks

​
Managing Agent Roles

Update an agent’s role programmatically: 
import frappe
from helpdesk.helpdesk.doctype.hd_agent.hd_agent import update_agent_role

# Promote agent to manager
update_agent_role(
    user="[email protected]",
    new_role="Manager"
)

# Demote manager to agent
update_agent_role(
    user="[email protected]",
    new_role="Agent"
)
When promoting to Manager:
  • Adds “Agent Manager” role
  • Adds “System Manager” role
When demoting to Agent:
  • Removes “Agent Manager” role
  • Removes “System Manager” role
  • Retains “Agent” role

​
Filtering Agents

The agent list supports filtering:
  • All: Show all agents (active and inactive)
  • Active: Show only active agents (is_active = 1)
  • Inactive: Show only inactive agents (is_active = 0)

​
Inviting Agents

New agents can be invited through the “Invite Agents” interface, which:
  1. Creates a User account
  2. Assigns the Agent role
  3. Creates an HD Agent record
  4. Sends an invitation email

​
Teams

Teams (HD Team doctype) allow you to organize agents into logical groups.

​
Team Fields

​
name
string
required
Unique name for the team (e.g., “Customer Support”, “Technical Support”).
​
team_members
Table
List of agents who are members of this team.Each member is an HD Team Member record with a link to an HD Agent.

​
Team Members

Team members are stored in the HD Team Member child doctype:
​
agent
Link
required
Link to an HD Agent record.
Each agent can be a member of multiple teams.

​
Creating Teams

Create a team programmatically: 
import frappe

# Create a new team
team = frappe.get_doc({
    "doctype": "HD Team",
    "name": "Customer Support"
})

# Add team members
team.append("team_members", {
    "agent": "[email protected]"
})
team.append("team_members", {
    "agent": "[email protected]"
})

team.insert()

​
Team-Based Restrictions

When the restrict_tickets_by_agent_group setting is enabled:
  • Agents can only view tickets assigned to their team(s)
  • Ticket assignment can be restricted to team members only
  • Saved replies can be team-scoped instead of global
See General Settings for configuration details.

​
Agent List Resource

The frontend uses createListResource to manage agents: 
const agents = createListResource({
  doctype: "HD Agent",
  fields: ["name", "agent_name", "user_image", "is_active"],
  filters: { is_active: ["in", [0, 1]] },
  orderBy: "modified desc",
  pageLength: 20,
  auto: true
});

// Filter active agents only
agents.filters = { is_active: ["=", 1] };
agents.reload();

// Search agents
agents.filters = { agent_name: ["like", "%search%"] };
agents.reload();

​
Team List Resource

Manage teams with: 
const teams = createListResource({
  doctype: "HD Team",
  fields: ["name"],
  orderBy: "modified desc",
  pageLength: 20,
  auto: true
});

​
Agent Activity Tracking

Agents are automatically tracked in the system:
  • Last login time
  • Assigned tickets count
  • Resolved tickets count
  • Average response time
These metrics can be used for reporting and performance analysis.

​
Best Practices

  1. Role Assignment: Start agents with the Agent role and promote to Manager only when needed
  2. Team Organization: Group agents by expertise (e.g., Technical, Billing, Sales)
  3. Active Status: Use the is_active flag instead of deleting agents to preserve ticket history
  4. Regular Audits: Periodically review agent and team assignments
  5. Naming Convention: Use clear, descriptive names for teams (e.g., “Tier 1 Support” vs “Team A”)

​
API Reference

​
Enable/Disable Agent

import frappe

# Disable agent
frappe.db.set_value("HD Agent", "[email protected]", "is_active", 0)

# Enable agent
frappe.db.set_value("HD Agent", "[email protected]", "is_active", 1)

​
Get Agent Details

import frappe

agent = frappe.get_doc("HD Agent", "[email protected]")
print(f"Agent: {agent.agent_name}")
print(f"Active: {agent.is_active}")
print(f"User Image: {agent.user_image}")

​
List Team Members

import frappe

team = frappe.get_doc("HD Team", "Customer Support")
for member in team.team_members:
    agent = frappe.get_doc("HD Agent", member.agent)
    print(f"- {agent.agent_name}")

Build docs developers (and LLMs) love

Get started for freeTalk to us