Huntress Agents

Huntress Agents

Overview

Huntress agents are lightweight endpoint monitors deployed across MSP client organizations. They collect telemetry and enable Huntress's managed detection and response capabilities. This skill covers listing, filtering, and inspecting agents across your managed fleet.

Anti-triggers

• Claude subagents — "agent" here means a Huntress endpoint sensor, never an AI subagent definition under agents/*.md.
• What an agent detected — this skill covers the sensor's own health and deployment state; its detections are huntress-signals and its confirmed threats are huntress-incidents.
• Seat counts for invoicing — deployed-agent counts and invoiced seats diverge; use huntress-billing.
• An "agent" that is not an endpoint sensor — a HaloPSA agent is a human technician, and other security and network vendors ship their own sensors under the same word; use halopsa-agents, blumira-agents, or domotz-agents.

Key Concepts

Agent Lifecycle

Agents are installed on endpoints and report back to the Huntress platform. Each agent belongs to an organization and has a status indicating its health and connectivity.

Agent Filtering

Agents can be filtered by:

• Organization — Scope to a specific client
• Platform — Filter by OS (Windows, macOS, Linux)
• Status — Online, offline, or degraded

API Patterns

List Agents

huntress_agents_list

Parameters:

• organization_id — Filter by organization
• page_token — Pagination token for next page

Example response:

{
  "agents": [
    {
      "id": "agent-123",
      "hostname": "ACME-WS-042",
      "organization_id": "org-456",
      "platform": "windows",
      "version": "0.13.25",
      "status": "online",
      "last_seen_at": "2026-02-26T15:30:00Z"
    }
  ],
  "next_page_token": "eyJwYWdlIjoyfQ=="
}

Get Agent Details

huntress_agents_get

Parameters:

• agent_id — The specific agent ID

Example response:

{
  "agent": {
    "id": "agent-123",
    "hostname": "ACME-WS-042",
    "organization_id": "org-456",
    "platform": "windows",
    "version": "0.13.25",
    "status": "online",
    "ip_address": "192.168.1.42",
    "external_ip": "203.0.113.50",
    "os_version": "Windows 11 23H2",
    "last_seen_at": "2026-02-26T15:30:00Z",
    "created_at": "2025-06-15T10:00:00Z"
  }
}

Common Workflows

Fleet Health Check

1. Call huntress_agents_list to get all agents
2. Paginate through full result set
3. Group by status (online/offline)
4. Flag agents not seen in >24 hours as potentially unhealthy
5. Group by organization to identify clients with agent issues

Organization Agent Audit

1. Call huntress_agents_list with organization_id filter
2. Compare agent count against expected endpoint count
3. Check for outdated agent versions
4. Identify endpoints missing agents

Platform Inventory

1. List all agents across organizations
2. Group by platform (Windows, macOS, Linux)
3. Generate platform distribution report per client

Error Handling

Agent Not Found

Cause: Invalid agent ID or agent has been uninstalled Solution: Verify the agent ID; check if the endpoint was decommissioned

Empty Agent List

Cause: Organization has no agents deployed, or filter is too restrictive Solution: Verify organization ID; try listing without filters first

Best Practices

• Paginate through all results for accurate fleet counts
• Monitor last_seen_at to detect offline agents early
• Track agent version distribution to plan upgrades
• Use organization filtering to generate per-client reports
• Cross-reference agent counts with RMM tool endpoint counts

Related Skills

• api-patterns - Pagination and rate limiting
• organizations - Organization management
• incidents - Incidents affecting specific agents
• signals - Signals from specific agents