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:

1. Sign into the HCP portal and click Waypoint in the Services menu.
2. Click Agents in the sidebar, then click Create an agent group.
3. Enter an Agent group name and Description for the agent group. An agent group name defines which Waypoint agents should execute a particular action.
4. 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:

1. Sign into the HCP portal and click Waypoint in the Services menu.
2. Click Actions in the sidebar, then click Create an action.
3. Enter an Action name and Description for the action.
4. Under Action type select Agent.
5. Under Action details select your agent group.
6. 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 following example defines a clear-user-cacheaction that runs the redis-cli command directly. It also creates a populate-user-cache action that invokes a script named populate_cache.sh in the same directory. The action also passes the count variable defined in HCP Waypoint into the script.

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:

1. 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
   

2. 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
   

3. 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