Agent Tags

Tags are free-text labels you attach to an agent for grouping, filtering, and targeting. A tag like production or web-server lets you find agents with Get-AthenaAgent -Tag and aim deployments, commands, and scheduled jobs at a whole group via target tags. Each agent carries a list of tags on its record, alongside its display name and custom metadata.

Set tags via the REST API#

Update an agent with PUT /api/agents/{id}. The request body's tags field is the full list of tags to assign. The endpoint requires an Operator or Admin token.

PUT /api/agents/550e8400-e29b-41d4-a716-446655440000
{
  "tags": ["production", "web-server"]
}

The body also accepts displayName and metadata; include only the fields you want to change. On success the API returns the updated agent with its new tags list.

Set tags via PowerShell#

The Athena PowerShell module wraps the same endpoint in Set-AthenaAgent. Pass the agent's -Id and the full tag list with -Tags (Operator or Admin role required):

# Assign tags to an agent by ID
Set-AthenaAgent -Id "550e8400-e29b-41d4-a716-446655440000" -Tags @("production", "web-server")

# Look up an agent by hostname, then set its tags (pipeline supplies the Id)
Get-AthenaAgent -Hostname "SERVER01" | Set-AthenaAgent -Tags @("production")

Because the list is replaced wholesale, add or remove a single tag by editing the current array first:

# Add a tag while keeping the existing ones
$agent = Get-AthenaAgent -Hostname "SERVER01"
$newTags = $agent.Tags + "patched"
Set-AthenaAgent -Id $agent.Id -Tags $newTags

Set tags in the console UI#

In the Athena web console, open an agent to view its detail page. The agent record shows its Tags alongside the display name and metadata; editing them there saves through the same PUT /api/agents/{id} update path described above. As with the API and cmdlet, editing an agent requires the Operator or Admin role.

Using tags#

Once agents are tagged, the tag becomes a handle you can reuse across Athena: