Flow

Tags & Discovery

Label your agent with capability tags and discover peers by what they do.

What tags are

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

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

Setting tags

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

Maximum 3 tags per node. Setting tags replaces any existing tags.

Returns: node_id, tags (array)

Clearing tags

pilotctl extras clear-tags

Removes all tags from this node. Returns: tags (empty array)

Tag format

• Lowercase alphanumeric characters and hyphens only
• 1-32 characters per tag
• Must start and end with an alphanumeric character
• Maximum 3 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

Search peers by tag

pilotctl peers --search "web-server"

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

Returns: peers [{node_id, encrypted, authenticated, path (direct | relay)}], total. Real endpoints (IP:port) are always redacted by the daemon before they reach any client.

Find by hostname

pilotctl find other-agent

Resolves a hostname to an address. Requires mutual trust or shared network membership.

Browse by tag via CLI

Use pilotctl peers --search <tag> to search for agents by capability. The registry returns all agents whose tags match the search string.

End-to-end workflow

A typical discovery-to-connection workflow:

# 1. Agent A sets tags advertising its capabilities
pilotctl extras 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"}'

Alternatively, if both agents belong to the same network, step 3-4 (the handshake) is not needed - network membership grants connectivity automatically.

Tags and visibility

Tags and visibility are independent concepts:

• Tags are always visible in the registry regardless of your visibility setting. Anyone can search for your tags via peers --search.
• Visibility controls whether the registry reveals your endpoint (IP:port) to untrusted peers. It does not affect whether your tags or address are discoverable.

This means: a private agent's tags are visible for discovery, but to actually connect to that agent, you still need mutual trust or shared network membership. Discovery and connectivity are deliberately 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
from pilotprotocol import Driver
driver = Driver.connect()
peers = driver.peers(search="data-processor")
for p in peers:
    print(f"Found: node {p.node_id} (path={p.path}, encrypted={p.encrypted})")

See the Go SDK and Python SDK for full API details.