---
title: Create agents in Telegraf Controller
description: Learn how Telegraf Controller creates agents from heartbeat plugin reports and how to verify new agents in the UI.
url: https://docs.influxdata.com/telegraf/controller/agents/create/
estimated_tokens: 906
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/agents/create/
date: '2026-10-06T09:35:17-06:00'
lastmod: '2026-10-06T09:35:17-06:00'
---

Agents represent Telegraf instances that send heartbeat data to Telegraf Controller
through the heartbeat output plugin.
Controller uses the heartbeat payload to create and track each agent.

* [How agent creation works](#how-agent-creation-works)
* [Configure agents](#configure-agents)
* [Verify a new agent](#verify-a-new-agent)

## How agent creation works

* The [heartbeat output plugin](/telegraf/v1/output-plugins/heartbeat/) in
  a Telegraf configuration reports agent data back to the `/agents/heartbeat`endpoint of your Telegraf Controller instance.
* The heartbeat payload includes a unique `instance_id` (also referred to as
  an “agent ID”) for the agent.
* When the first heartbeat arrives for an agent, Telegraf Controller
  automatically creates the agent record and marks it with the reported status.
  Subsequent agent heartbeats update the existing agent record.

## Configure agents

[Heartbeat output plugin](/telegraf/v1/output-plugins/heartbeat/) configuration
options determine what agent data Telegraf sends to Telegraf Controller.
The following heartbeat plugin configuration options are available:

* **url**: *(Required)* URL of heartbeat endpoint.
* **instance\_id**: *(Required)* Unique identifier for the Telegraf instance
  or agent (also known as the agent ID).
* **token**: *(Required with auth enabled)*Telegraf Controller API token for the heartbeat endpoint.
  The token must have **write** permissions on the **Heartbeat** API.
  Telegraf Controller rejects heartbeats sent with a token that lacks this
  permission with a `403` response.
* **interval**: Interval for sending heartbeat messages. Default is `1m` (every minute).
* **include**: Information to include in the heartbeat message.
  Available options are:
  * **hostname**: Hostname of the machine running Telegraf.
  * **statistics**: (Recommended)
    Agent metrics including number of metrics collected and written since the
    last heartbeat, logged error and warning counts, etc.
  * **configs**: (Recommended)
    Redacted list of configurations loaded by the Telegraf instance.

* **headers**: HTTP headers to include with the heartbeat request.

### Example heartbeat output plugin

The following is an example heartbeat output plugin configuration that uses
an `agent_id` [configuration parameter](/telegraf/controller/configs/substitute-values/#parameters)to specify the `instance_id`.

```toml
[[outputs.heartbeat]]
  url = "http://telegraf_controller.example.com/agents/heartbeat"
  instance_id = "&{agent_id}"
  token = "${TELEGRAF_CONTROLLER_TOKEN}"
  interval = "1m"
  include = ["hostname", "statistics", "configs"]

  [outputs.heartbeat.headers]
    User-Agent = "telegraf"
```

> [!Important]
> #### Authorize heartbeats using an API token
>
> If Telegraf Controller requires authorization on the **Heartbeat** API,
> include the `token` option in your heartbeat plugin configuration.
> Provide a Telegraf Controller token with **write** permissions on the**Heartbeat** API.
>
> We recommend defining the `TELEGRAF_CONTROLLER_TOKEN` environment variable
> when starting Telegraf and using it to define the token in your heartbeat
> plugin. On **Telegraf 1.38.x or earlier**, use `INFLUX_TOKEN` instead. For
> details, see [Use API tokens](/telegraf/controller/tokens/use/#for-heartbeat-requests).

## Verify a new agent

1. Open Telegraf Controller and go to **Agents**.
2. Confirm the agent appears in the list with the expected `instance_id`.
3. Click the **More button ()** and select **View Details** to verify metadata, [labels](/telegraf/controller/labels/), and the reporting rule assignment.