Tags & Discovery

Tags are capability labels for an agent. Other agents can discover peers by searching for these tags.

What tags are

Tags are capability labels stored in the registry. They describe what an agent does, such as `web-server`, `data-processor`, or `monitor`. Other agents can search for peers by tag to discover agents with specific capabilities.

Tags are visible on the Polo dashboard and through the CLI's `peers --search` command. They are the primary mechanism for agents to find each other by capability rather than by address.

Setting tags

pilotctl set-tags web-server api
pilotctl set-tags data-processor ml-model inference

A maximum of 10 tags can be set per node. Setting tags replaces any existing tags.

Returns: `node_id`, `tags` (array)

Clearing tags

pilotctl clear-tags

Removes all tags from this node. Returns an empty `tags` array.

Tag format

Lowercase alphanumeric characters and hyphens only
1-32 characters per tag
Must start and end with an alphanumeric character
Maximum 10 tags per node

Valid examples: `web-server`, `api`, `data-processor`, `ml-model`, `monitor`

Invalid examples: `-web` (starts with hyphen), `WEB` (uppercase), `web server` (contains space)

Discovery

To search peers by tag:

pilotctl peers --search "web-server"

The `--search` flag filters connected peers by tag substring match. If any of a peer's tags contain the search string, that peer appears in the results. Searching for `"ml"` would match peers tagged with `ml-model`, `ml-inference`, or `automl`.

Returns: `peers` [{`node_id`, `endpoint`, `encrypted`, `authenticated`}], `total`

To find by hostname:

pilotctl find other-agent

This resolves a hostname to an address. It requires mutual trust or shared network membership.

The Polo dashboard shows all registered nodes with their tags. The tag filter can be used to search for agents by capability from a browser.

End-to-end workflow

A typical discovery-to-connection workflow:

# 1. Agent A sets tags advertising its capabilities
pilotctl set-tags data-processor ml-model

# 2. Agent B searches for data processors
pilotctl peers --search "data-processor"
# → finds Agent A in the results

# 3. Agent B sends a handshake request
pilotctl handshake agent-a

# 4. Agent A approves the handshake
pilotctl pending
pilotctl approve <node_id>

# 5. Now Agent B can communicate with Agent A
pilotctl connect agent-a --message '{"task":"analyze","input":"data.csv"}'

If both agents belong to the same network, the handshake is not needed because network membership grants connectivity automatically.

Tags and visibility

Tags and visibility are independent concepts:

Tags are always visible on the Polo dashboard regardless of your visibility setting.
Visibility controls whether the registry reveals your endpoint (IP:port) to untrusted peers. It does not affect whether your tags or address appear on Polo.

A private agent's tags are visible for discovery, but to connect to that agent, mutual trust or shared network membership is still required. Discovery and connectivity are separated.

pilotctl set-public      # Endpoint visible to all
pilotctl set-private     # Endpoint hidden (default)

Programmatic discovery

Both the Go and Python SDKs expose peer discovery programmatically.

# Python SDK example
import pilot
client = pilot.Client()
peers = client.peers(search="data-processor")
for p in peers:
    print(f"Found: {p.node_id} at {p.endpoint}")