Create and manage agents

This page describes how to manage HCP Waypoint agents to run actions. Platform engineers often perform these tasks. Refer to Actions for additional information.

Create an agent group

To create an agent group, complete the following steps:

From the HCP Waypoint overview, click Agents in the side navigation.
Click Create an agent group.
Enter an Agent group name and Description for the agent group. An agent group name defines which Waypoint agents should execute a particular action.
Click Create agent group.

After you create the agent group, HCP Waypoint shows an example agent configuration file.

Create an action

To create an action, complete the following steps:

From the HCP Waypoint overview, click Actions.
Click Create an action.
Enter an Action name and Description for the action.
Under Action type select Agent.
Under Action details select your agent group.
Enter the action identifier that matches the name of the action block in your agent configuration.

Create an agent configuration file

An agent configuration file defines one or more actions that the agent can run. For more information, refer to the agent configuration syntax documentation for more information.

The below example defines two Waypoint actions. The clear-user-cacheaction runs the redis-cli command directly. The populate-user-cache action invokes a script named populate_cache.sh in the same directory, passing it a variable named count defined in HCP Waypoint.

group "internal-us-west-2" {
  action "clear-user-cache" {
    run {
      command = "redis-cli KEYS \"user_cache_*\" | xargs redis-cli DEL"
    }
  }

  action "populate-user-cache" {
    run {
      command = "./populate_cache.sh ${var.count}"
    }
  }
}

For information on using variables in an action, refer to the action variables reference documentation.

Install the HCP CLI

The HCP Waypoint agent ships as a part of the HCP CLI. To install the CLI, refer to the install HCP CLI documentation. You can also use the official HCP container image to run agents in Docker, Kubernetes, Nomad, or other container orchestrators.

Authenticate and run the agent

You must authenticate each HCP Waypoint agent with HCP before you can run the agent. You can authenticate the agent with HCP the following ways:

Interactively using the hcp auth login command. Refer to the HCP CLI documentation for more information. After you authenticate using the link provided by the HCP CLI, use the hcp waypoint agent run command to start the agent and pass it the path to your agent configuration file:
```
$ hcp waypoint agent run --config=agent.hcl
```

Non-interactively with a service principal using environment variables.

$  HCP_CLIENT_ID=<client-id> HCP_CLIENT_SECRET=<client-secret> hcp waypoint agent run --config=agent.hcl

Non-interactively with with a credentials file. You can create a credentials file by first creating a service principal, then creating a service principal key. First create a new service principal:

$ hcp iam service-principals create example-sp --project="<project-id>"
Resource Name: iam/project/12345678-1234-1234-1234-123456789010/service-principal/example-sp
Resource ID:   example-sp-12345678-1234-1234-1234-123456789010
Display Name:  example-sp
Created At:    2025-05-23T19:15:13.738Z

Note the Resource ID field, or retrieve it with the hcp iam service-principals read command:

$ hcp iam service-principals read example-sp --format=json | jq -r ".id"

Use the resource ID to grant the service principal the roles/admin role in your project:

$ hcp projects iam add-binding --member=example-sp-12345678-1234-1234-1234-123456789010 --role=roles/admin

Next, create a service principal key, and include the --output-cred-file to create a credentials file:

$ hcp iam service-principals keys create example-sp --output-cred-file=cred_file.json

Finally, start the HCP Waypoint agent and pass the path to the credential file with the HCP_CRED_FILE environment variable:

$ HCP_CRED_FILE=cred_file.json hcp waypoint agent run --config=agent.hcl