Agents Components API - Wazuh Dashboard Plugins

The Agents components provide reusable UI elements for displaying agent information, status, and synchronization states.

AgentStatus

Displays the current status of a Wazuh agent with visual indicators. Location: plugins/main/public/components/agents/agent-status.tsx:21

Props

TAgentStatus

required

Agent status valuePossible values:

"active" - Agent is connected and reporting
"disconnected" - Agent is not connected
"never_connected" - Agent has never connected
"pending" - Agent is pending registration

Agent

Complete agent object for detailed status information

Show properties

string

Agent ID

string

Agent name

string

Status string

number

Numeric status code for detailed information

string

Custom label to display instead of default status text

React.CSSProperties

Custom styles to apply to the component

Usage

import React from 'react';
import { AgentStatus } from '../components/agents/agent-status';

function AgentList({ agents }) {
  return (
    <div>
      {agents.map(agent => (
        <div key={agent.id}>
          <span>{agent.name}</span>
          <AgentStatus 
            status={agent.status} 
            agent={agent}
          />
        </div>
      ))}
    </div>
  );
}

Custom Label

<AgentStatus 
  status="active" 
  agent={agent}
>
  Online
</AgentStatus>

With Custom Styles

<AgentStatus 
  status="disconnected" 
  agent={agent}
  style={{ fontSize: '14px', fontWeight: 'bold' }}
/>

Status Codes

The component displays detailed status information when an agent object is provided:

status

Active - Agent is connected and sending events

status

Disconnected - Agent lost connection to manager

status

Never connected - Agent registered but never established connection

status

Pending - Agent is awaiting approval

AgentSynced

Displays the synchronization status of an agent. Location: plugins/main/public/components/agents/agent-synced.tsx

Props

Agent

required

Agent object containing synchronization information

Show properties

string

Configuration sync status: “synced” | “not synced”

string

Timestamp of last keep-alive

boolean

default:true

Whether to show the “Synchronized” label

Usage

import React from 'react';
import { AgentSynced } from '../components/agents/agent-synced';

function AgentDetails({ agent }) {
  return (
    <div>
      <h3>{agent.name}</h3>
      <AgentSynced agent={agent} />
    </div>
  );
}

Without Title

<AgentSynced agent={agent} showTitle={false} />

ColumnWithStatusIcon

Generic component for displaying text with a colored status icon. Location: plugins/main/public/components/agents/column-with-status-icon.tsx

Props

string

required

Text to display

string

required

Color of the status indicatorPossible values:

"success" - Green indicator
"danger" - Red indicator
"warning" - Orange indicator
"subdued" - Gray indicator
Any valid EUI color

Tooltip text to show on hover

Usage

import React from 'react';
import { ColumnWithStatusIcon } from '../components/agents/column-with-status-icon';

function CustomStatus({ status }) {
  const color = status === 'healthy' ? 'success' : 'danger';
  
  return (
    <ColumnWithStatusIcon
      text={status}
      color={color}
      tooltip={`System is ${status}`}
    />
  );
}

In a Table

const columns = [
  {
    field: 'name',
    name: 'Name',
  },
  {
    field: 'status',
    name: 'Status',
    render: (status: string) => (
      <ColumnWithStatusIcon
        text={status}
        color={getStatusColor(status)}
      />
    ),
  },
];

Agent Stats Components

Components for displaying agent statistics and summaries.

AgentsSummary

Displays summary statistics for all agents. Location: plugins/main/public/components/agents/stats/agents-summary.tsx

Props

object

required

Agent summary data

Show properties

number

Count of active agents

number

Count of disconnected agents

number

Count of agents that never connected

number

Count of pending agents

number

Total agent count

Usage

import React, { useEffect, useState } from 'react';
import { WzRequest } from '../../react-services';

function DashboardStats() {
  const [agentData, setAgentData] = useState(null);
  
  useEffect(() => {
    const fetchStats = async () => {
      const { data } = await WzRequest.apiReq(
        'GET',
        '/agents/summary/status',
        {}
      );
      setAgentData(data.data.connection);
    };
    fetchStats();
  }, []);
  
  if (!agentData) return <div>Loading...</div>;
  
  return <AgentsSummary agentData={agentData} />;
}

Agent Prompts

Dialog components for agent management actions.

UpgradeAgentPrompt

Prompt for upgrading agents to a new version. Location: plugins/main/public/components/agents/prompts/upgrade-agent-prompt.tsx

Props

Agent[]

required

Array of agents to upgrade

() => void

required

Callback when the prompt is closed

() => void

Callback when upgrade succeeds

Usage

import React, { useState } from 'react';
import { UpgradeAgentPrompt } from '../components/agents/prompts/upgrade-agent-prompt';
import { EuiButton } from '@elastic/eui';

function AgentActions({ selectedAgents }) {
  const [showUpgrade, setShowUpgrade] = useState(false);
  
  return (
    <>
      <EuiButton onClick={() => setShowUpgrade(true)}>
        Upgrade Agents
      </EuiButton>
      
      {showUpgrade && (
        <UpgradeAgentPrompt
          agents={selectedAgents}
          onClose={() => setShowUpgrade(false)}
          onSuccess={() => {
            setShowUpgrade(false);
            // Refresh agent list
          }}
        />
      )}
    </>
  );
}

Syscollector Components

Components for displaying system inventory data from agents.

SyscollectorInventory

Displays hardware, packages, and system information for an agent. Location: plugins/main/public/components/agents/syscollector/

Props

Agent

required

Agent to display inventory for

string

Specific inventory section to display:

"hardware" - Hardware information
"packages" - Installed packages
"processes" - Running processes
"ports" - Open ports
"network" - Network interfaces

Usage

import React from 'react';
import { SyscollectorInventory } from '../components/agents/syscollector';

function AgentInventory({ agent }) {
  return (
    <div>
      <h2>Agent Inventory</h2>
      <SyscollectorInventory 
        agent={agent} 
        section="hardware"
      />
    </div>
  );
}

Type Definitions

TAgentStatus

Agent status type definition.

export type TAgentStatus = 
  | 'active'
  | 'disconnected'
  | 'never_connected'
  | 'pending';

Agent

Agent object interface.

export interface Agent {
  id: string;
  name: string;
  ip?: string;
  status: TAgentStatus;
  status_code?: number;
  group?: string[];
  group_config_status?: 'synced' | 'not synced';
  os?: {
    name?: string;
    platform?: string;
    version?: string;
  };
  version?: string;
  dateAdd?: string;
  lastKeepAlive?: string;
  manager?: string;
  node_name?: string;
}

Utilities

Agent Status Helpers

Location: plugins/main/common/services/wz_agent_status.ts

agentStatusLabelByAgentStatus()

Get human-readable label for agent status.

import { agentStatusLabelByAgentStatus } from '../../../common/services/wz_agent_status';

const label = agentStatusLabelByAgentStatus('active');
// => "Active"

agentStatusColorByAgentStatus()

Get color code for agent status.

import { agentStatusColorByAgentStatus } from '../../../common/services/wz_agent_status';

const color = agentStatusColorByAgentStatus('active');
// => "success"

Complete Example

Full example of an agent management interface:

import React, { useEffect, useState } from 'react';
import {
  EuiPanel,
  EuiFlexGroup,
  EuiFlexItem,
  EuiBasicTable,
  EuiButton,
} from '@elastic/eui';
import { AgentStatus } from '../components/agents/agent-status';
import { AgentSynced } from '../components/agents/agent-synced';
import { AgentsSummary } from '../components/agents/stats/agents-summary';
import { WzRequest } from '../react-services';

function AgentManagement() {
  const [agents, setAgents] = useState([]);
  const [summary, setSummary] = useState(null);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    const fetchData = async () => {
      try {
        // Fetch agents
        const agentsResponse = await WzRequest.apiReq(
          'GET',
          '/agents',
          { params: { limit: 500 } }
        );
        setAgents(agentsResponse.data.data.affected_items);
        
        // Fetch summary
        const summaryResponse = await WzRequest.apiReq(
          'GET',
          '/agents/summary/status',
          {}
        );
        setSummary(summaryResponse.data.data.connection);
      } catch (error) {
        console.error('Failed to fetch agents:', error);
      } finally {
        setLoading(false);
      }
    };
    
    fetchData();
  }, []);
  
  const columns = [
    {
      field: 'id',
      name: 'ID',
      width: '75px',
    },
    {
      field: 'name',
      name: 'Name',
    },
    {
      field: 'ip',
      name: 'IP Address',
    },
    {
      field: 'status',
      name: 'Status',
      render: (status, agent) => (
        <AgentStatus status={status} agent={agent} />
      ),
    },
    {
      field: 'group_config_status',
      name: 'Sync',
      render: (_, agent) => (
        <AgentSynced agent={agent} showTitle={false} />
      ),
    },
    {
      field: 'version',
      name: 'Version',
    },
  ];
  
  return (
    <div>
      {summary && (
        <EuiPanel>
          <AgentsSummary agentData={summary} />
        </EuiPanel>
      )}
      
      <EuiPanel>
        <EuiBasicTable
          items={agents}
          columns={columns}
          loading={loading}
        />
      </EuiPanel>
    </div>
  );
}

export default AgentManagement;

Best Practices

Always Provide Agent Objects

When possible, pass the complete agent object to components for richer status information:

// Good
<AgentStatus status={agent.status} agent={agent} />

// Less informative
<AgentStatus status={agent.status} />

Handle Loading States

Show loading indicators while fetching agent data:

{loading ? (
  <EuiLoadingSpinner size="xl" />
) : (
  <AgentsSummary agentData={summary} />
)}

Refresh Data Periodically

Agent status changes frequently. Implement auto-refresh:

useEffect(() => {
  const interval = setInterval(fetchAgents, 30000);
  return () => clearInterval(interval);
}, []);

Overview Components

Dashboard and statistics components

Main Plugin API

Core plugin functionality

Agent Management

Agent management guide

API Console

Test agent API endpoints

​AgentStatus

​Props

​Usage

​Custom Label

​With Custom Styles

​Status Codes

​AgentSynced

​Props

​Usage

​Without Title

​ColumnWithStatusIcon

​Props

​Usage

​In a Table

​Agent Stats Components

​AgentsSummary

​Props

​Usage

​Agent Prompts

​UpgradeAgentPrompt

​Props

​Usage

​Syscollector Components

​SyscollectorInventory

​Props

​Usage

​Type Definitions

​TAgentStatus

​Agent

​Utilities

​Agent Status Helpers

​agentStatusLabelByAgentStatus()

​agentStatusColorByAgentStatus()

​Complete Example

​Best Practices

​Related Resources

Overview Components

Main Plugin API

Agent Management

API Console

AgentStatus

Props

Usage

Custom Label

With Custom Styles

Status Codes

AgentSynced

Props

Usage

Without Title

ColumnWithStatusIcon

Props

Usage

In a Table

Agent Stats Components

AgentsSummary

Props

Usage

Agent Prompts

UpgradeAgentPrompt

Props

Usage

Syscollector Components

SyscollectorInventory

Props

Usage

Type Definitions

TAgentStatus

Agent

Utilities

Agent Status Helpers

agentStatusLabelByAgentStatus()

agentStatusColorByAgentStatus()

Complete Example

Best Practices

Related Resources