---
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: 2239
product: Telegraf
version: v1
---

# Create agents in Telegraf Controller

#### Telegraf Controller is in Public Beta

Telegraf Controller is in public beta and will be part of the future Telegraf Enterprise offering. While in beta, Telegraf Controller is **not meant for production use**. The Telegraf Controller documentation is a work in progress, and we are actively working to improve it. If you have any questions or suggestions, please [submit an issue](https://github.com/influxdata/docs-v2/issues/new?labels=Telegraf%20Controller). We welcome any and all contributions.

Beta expectations

-   **No configuration or agent limits**  
    While in beta, Telegraf Controller doesn't place any limits on the number of configurations you can store or the number of Telegraf agents you can track. However, upon being generally available, the free distribution of Telegraf Controller will have limits introduced, with the option to increase limits through a Telegraf Enterprise license.
-   **Potential breaking changes**  
    While in beta, we will do our best to no longer make breaking changes to Telegraf Controller, however, they may be necessary. The majority of changes we make will be additive and non-breaking, and include any necessary migrations. When we do need to make breaking changes, we will do our best to communicate them clearly and in advance to minimize disruption.
-   **Flexible release schedule**  
    While in beta, we will continue to create new releases of Telegraf Controller, but likely at irregular intervals. We will provide [Telegraf Controller release notes](/telegraf/controller/reference/release-notes/) to make it easy to track updates.

Provide beta feedback

-   Use the **Feedback** feature in the Telegraf Controller UI.
-   [Join the InfluxDB Community Slack](https://influxdata.com/slack) and post feedback in the **#telegraf-enterprise-alpha** channel.
-   Post feedback in the [InfluxData Community](https://community.influxdata.com).

Join our public channels

-   [InfluxDB Community Slack *(Preferred)*](https://influxdata.com/slack)
-   [InfluxData Community](https://community.influxdata.com)
-   [InfluxDB Subreddit](https://reddit.com/r/influxdb)

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.
-   **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/dynamic-values/#parameters) to specify the `instance_id`.

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

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

#### 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 `INFLUX_TOKEN` environment variable when starting Telegraf and using that to define the token in your heartbeat plugin.

## 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, and the reporting rule assignment.