> For the complete documentation index, see [llms.txt](https://help.highlight.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.highlight.net/admin/admin-page/agent.md).

# Agent

Insight UI - Consolidated Admin

Highlight Agents contain different tasks or modules, such as performance testing for HTTP and Flow collection. Each agent connects back to the main Highlight platform using a secure, encrypted connection.

Agents are created and managed from the Admin page. You must create each agent in Highlight before installing it in your network. Each agent exists in the folder where it's created and can be selected for use in that folder or any folders beneath it. Unless you're a Service Provider setting up agents for customers, create agents in your home (Root) folder.

Read about [agent installation](https://support.highlight.net/help/device_setup/agent) or watch our [agent installation](https://support.highlight.net/help/video/agent_install) and [agent creation](https://support.highlight.net/help/video/agent_create) videos.

{% hint style="info" %}
**Permission needed:** Manage folders/locations
{% endhint %}

## Agents in the Admin Page

Agents and agent groups are listed in the Admin page beneath the folder they are defined in. Every agent belongs to an agent group — agents not assigned to a group appear under **Unassigned**.

<figure><picture><source srcset="/files/I0szOo320g6IlX4p1hYO" media="(prefers-color-scheme: dark)"><img src="https://25768351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F68Wb63XzG9guH74bkPEb%2Fuploads%2FBIPowg1Drk5yk6DDghqf%2Fagents-admin-light.png?alt=media" alt="Agents and agent groups in the Admin page"></picture><figcaption></figcaption></figure>

<table><thead><tr><th width="126">Column</th><th>Description</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>The agent or agent group name as assigned by a user</td></tr><tr><td><strong>Description</strong></td><td>The Agent ID — a Highlight-generated identifier</td></tr><tr><td><strong>Path</strong></td><td>The folder the agent is defined in</td></tr><tr><td><strong>Status</strong></td><td>The agent's current state — see below</td></tr></tbody></table>

Agents attempt to make contact every 10 seconds. The **Status** badge shows:

<table><thead><tr><th width="249">Badge colour &#x26; label</th><th>Shown if agent is</th></tr></thead><tbody><tr><td><strong>Green / "Enabled"</strong></td><td>Enabled AND last contact is within the last 3 minutes</td></tr><tr><td><p><strong>Amber /</strong> shows a time period</p><p>(i.e. "2 h" or "20 d")</p></td><td>Enabled AND last contact is greater than 3 minutes ago</td></tr><tr><td><strong>Amber / "No contact"</strong></td><td>Enabled but has never made contact</td></tr><tr><td><strong>Red / "Disabled"</strong></td><td>Disabled</td></tr></tbody></table>

## Agent Groups

Agent groups are used when planning resilience, allowing both agents in a group to independently poll their assigned Highlight folder(s). Groups may have one or more agents, with the first listed being the primary agent used for tech testing.

<figure><picture><source srcset="/files/iVak3u0Zqrqe0bNkh3dg" media="(prefers-color-scheme: dark)"><img src="https://25768351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F68Wb63XzG9guH74bkPEb%2Fuploads%2Fb7Ubk0V3O1csMVJcVoqG%2FAgentGroupCreate%20-%20light.png?alt=media" alt="Agent Group Create"></picture><figcaption></figcaption></figure>

### New Agent Group

Create a new agent group by entering a name and clicking **Save**.

### Connectivity Alerts

If one agent in a polling group cannot contact individual devices, Highlight sends a weekly notification to email addresses in the agents' Notify field. The email sends on Tuesday morning UTC and includes the total number of watches with at least 24 hours of good samples from one poller but only bad samples from the other.

IP/Name details are included for up to 200 watches, split between those not contactable by poller 1 and those not contactable by poller 2.

Alerting is enabled by default. Switch off **Connectivity alerts** to stop receiving these alert emails.

<figure><img src="https://25768351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F68Wb63XzG9guH74bkPEb%2Fuploads%2FheTIS6OfTbwSan9iKV7c%2FAgentConnectivityAlertEmail.png?alt=media" alt="Agent connectivity alert email"><figcaption><p>Sample agent connectivity alert email</p></figcaption></figure>

### Edit Agent Group

The dialog matches the create dialog. Open it by selecting the group row.

* **Save** — Use after altering an existing agent group name.
* **Delete** — An agent group can only be deleted if it does not contain any agents. Move agents to another group or to **Unassigned** to delete the group.

To assign an Agent group to a folder, refer to the [Agent Selection](/admin/admin-general-details/agent-selection.md) page.

## Create New Agent

Open the agent creation panel by selecting **+** on a folder or agent group and choosing **Create a new agent**. The folder the agent is being created in is shown at the top of the panel.

<figure><picture><source srcset="/files/lkmhSzKmrmhZWrjZAo4i" media="(prefers-color-scheme: dark)"><img src="https://25768351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F68Wb63XzG9guH74bkPEb%2Fuploads%2FXXk1R6UcmQDgXYuoByzb%2Fagent-create-main-light.png?alt=media" alt="Create Agent - Main section"></picture><figcaption></figcaption></figure>

### Agent Details

<table><thead><tr><th width="136">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>Agent</strong></td><td><strong>Enabled</strong> or <strong>Disabled</strong> toggle. For an existing agent, a message shows which user last enabled this agent and when.</td></tr><tr><td><strong>Name</strong></td><td>Any text that helps you identify this agent, which may include the hostname. This field is required.</td></tr><tr><td><strong>Notify</strong></td><td><p>One or more email addresses (separated with a comma) to receive alerts from Highlight should this agent go off-line or stop responding. Highlight will only send alerts for activated, enabled agents. This field is required and an actively monitored email address is highly recommended to ensure the agent gets prompt attention if down.</p><p>If the agent is one of a pair in an agent group used for polling, Highlight also sends a weekly email to the Notify address(es) for watches that are only accessible from one of the agents in the group.</p></td></tr><tr><td><strong>Notify after</strong></td><td>By default, an alert is sent after the agent has been offline for 30 minutes, then again after another 30 minutes. Both periods can be adjusted down in 5 minute intervals to receive quicker notification.</td></tr><tr><td><strong>Group</strong></td><td><p>At creation an agent will be <strong>Unassigned</strong> by default. If assigned to an existing group, the option to <strong>Make Primary</strong> will also become available.</p><p>The first agent listed in a group is the designated primary agent, which is used for technical testing. Typically a group also has one secondary agent, although further agents are permitted if used for flow collection.</p></td></tr><tr><td><strong>Create Button</strong></td><td>Clicking <strong>Create</strong> opens the <strong>Status</strong> section, which contains a single-use Activation Code. You need to copy and paste this code into the agent installation dialog on the intended server. The activation code is only visible once. If you require the code again it will need to be regenerated using <strong>Reset</strong> and entered into the agent dialog on the server.</td></tr></tbody></table>

To assign an Agent to a folder refer to [Agent Selection](#agent-selection) below.

## Edit Agent

To edit an agent click anywhere on the line or on the edit button. The panel contains collapsible sections.

### Details

See [Create New Agent](#create-new-agent) above.

### Status

<figure><picture><source srcset="/files/wTv5h5V3TfsePQw9N9BK" media="(prefers-color-scheme: dark)"><img src="https://25768351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F68Wb63XzG9guH74bkPEb%2Fuploads%2FK1Mh2Zy8Ie7oeULkzjJ2%2Fagent-status-light.png?alt=media" alt="Agent Status section"></picture><figcaption></figcaption></figure>

This section shows:

<table><thead><tr><th width="160">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>ID</strong></td><td>A Highlight-generated identifier, with a badge showing <strong>Activated</strong> or <strong>Not activated</strong>.</td></tr><tr><td><strong>Reset</strong></td><td>Use to reset the activation code. This causes an active agent to become inactive.</td></tr><tr><td><strong>Activation Code</strong></td><td>Displayed only after selecting <strong>Create</strong> for a new agent or <strong>Reset</strong> for an existing agent. Copy this code into the agent dialog on the server.</td></tr><tr><td><strong>Status</strong></td><td><strong>Communicating</strong> or <strong>Not communicating</strong>, indicating whether the agent is communicating.</td></tr><tr><td><strong>Last contact</strong></td><td>Shows the agent's last contact date and time. For a communicating agent, contact is continuous, but this time only updates when the panel opens.</td></tr></tbody></table>

### Host Details

This area is updated once a day if the agent is enabled and contact made. It shows:

<table><thead><tr><th width="130">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>Last update</strong></td><td>Shows the date and time of the most recent agent contact. This typically updates once a day.</td></tr><tr><td><strong>Hostname</strong></td><td>Shows the agent's name if contact has been made.</td></tr><tr><td><strong>IP addresses</strong></td><td>Shows the agent's IP addresses if contact has been made.</td></tr><tr><td><strong>OS version</strong></td><td>Shows the version, such as Microsoft Windows Server 2016 Standard, if contact has been made.</td></tr><tr><td><strong>Processor</strong></td><td>Shows the first processor found, if more than one, and its number of cores.</td></tr><tr><td><strong>Memory</strong></td><td>Shows how much memory is installed.</td></tr></tbody></table>

### Agent Server Software

The **Agent server software** button next to **Save** downloads the agent server software required for setting up a Highlight agent on a server.

### Save Button

Use to save any changes to an existing agent.

### Delete Button

{% hint style="warning" %}
Use with caution. Deleting an agent may mean Highlight can no longer collect and show data for any associated watches. The Agent Tools: Assignment section shows which folders are using a particular agent. Deletion of an agent cannot be undone.
{% endhint %}

## Agent Tools

Agent tools are useful for troubleshooting from within Highlight. They appear as **Agent Tools** sections within the Edit agent panel.

### Assignment

Review this section to determine which folders are using this agent. See the [Agent Selection](#agent-selection) section below for how to change which agent is in use for a folder.

<figure><picture><source srcset="/files/iChOL834aNf3IC9wRMPn" media="(prefers-color-scheme: dark)"><img src="https://25768351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F68Wb63XzG9guH74bkPEb%2Fuploads%2FmX8Rd7kcWUzwU71K6EUu%2Fagent-tools-assignment-light.png?alt=media" alt="Agent Tools - Assignment"></picture><figcaption></figcaption></figure>

### IP Tools

<figure><picture><source srcset="/files/pSX4wUrUShObdx81ykNm" media="(prefers-color-scheme: dark)"><img src="https://25768351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F68Wb63XzG9guH74bkPEb%2Fuploads%2FfoIj5L4Fs27nhpt0CO0R%2Fagent-tools-iptools-light.png?alt=media" alt="Agent Tools - IP Tools"></picture><figcaption></figcaption></figure>

<table><thead><tr><th width="112">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>Target</strong></td><td>Enter a hostname or IP address, then select <strong>Ping</strong> or <strong>Traceroute</strong>. Buttons remain disabled until the target is valid and while results load.</td></tr><tr><td><strong>Ping</strong></td><td>Verifies the target is reachable and returns results, including the average time taken to reach it.</td></tr><tr><td><strong>Traceroute</strong></td><td>Traces the route to the target and returns up to 30 hops.</td></tr></tbody></table>

## Agent Selection

Refer to the [agent selection](/admin/admin-general-details/agent-selection.md) page.&#x20;

## Agent Notification Sample Emails

{% hint style="info" %}
30 minutes is the default notification period for both the initial and secondary email. An admin user can adjust these down in 5 minute intervals to receive quicker notification. See the **Notify after** field in [Create New Agent](#create-new-agent) above.
{% endhint %}

### Initial Agent Offline Email

> **Subject:** Highlight Agent Agent101 has been offline for 32m\
> **From:** <noreply@highlight.net>\
> **Time:** 2021-07-28 11:02:02 UTC
>
> **Agent:** RYNKSZ\
> **Agent Group:** (blank)\
> **Hostname:** AGENT101-Desktop\
> **Operating System:** Microsoft Windows 10 Pro\
> **IP Addresses:** 192.168.100.108\
> **Last Contact:** 32m (2021-07-28 10:30:00 UTC)
>
> This could be because of a network or server failure. Please check the system and connectivity.
>
> Highlight will send you an email when an agent is offline for 30m, and another email if the agent remains offline for a further 30m.
>
> You will receive another email when the Agent comes back online.
>
> You are receiving this email because your email address is the notify address for Highlight Agent "Agent101". If you require any further assistance please contact <support@highlight.net>.

### Second and Final Agent Offline Email

> **Subject:** Highlight Agent Agent101 has been offline for 182m\
> **From:** <noreply@highlight.net>\
> **Time:** 2021-07-28 13:32:00 UTC
>
> **Agent:** RYNKSZ\
> **Agent Group:** (blank)\
> **Hostname:** AGENT101-Desktop\
> **Operating System:** Microsoft Windows 10 Pro\
> **IP Addresses:** 192.168.100.108\
> **Last Contact:** 182m (2021-07-28 10:30:00 UTC)
>
> This could be because of a network or server failure. Please check the system and connectivity.
>
> This is the last email you will receive until the Agent comes back online.
>
> You are receiving this email because your email address is the notify address for Highlight Agent "Agent101". If you require any further assistance please contact <support@highlight.net>.

### Agent Online Email

> **Subject:** Highlight Agent Agent101 is online again\
> **From:** <noreply@highlight.net>\
> **Time:** 2021-07-28 13:42:00 UTC
>
> **Agent:** RYNKSZ\
> **Agent Group:** (blank)\
> **Hostname:** DESKTOP-30T3A7T\
> **Operating System:** Microsoft Windows 10 Pro\
> **IP Addresses:** 192.168.100.108\
> **Last Contact:** 0s (online)
>
> Highlight Agent "Agent101" is online again after being offline for 192m.
>
> You are receiving this email because your email address is the notify address for Highlight Agent "Agent101". If you require any further assistance please contact <support@highlight.net>.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.highlight.net/admin/admin-page/agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.