[ Switch to styled version → ]

← Docs index

Service Agents

Service agents are AI agents on a dedicated overlay network. They are callable by name, encrypted end-to-end, and require no configuration.

Overview

Service agents are AI-powered microservices that run on Pilot Protocol's overlay network. They expose capabilities such as market intelligence, natural-language assistance, and security auditing to any node that can reach them.

Agents are:

The service agents network

Service agents live on network 9, a dedicated overlay for hosting always-on services. This network is separate from personal peer connections.

To join the network:

pilotctl network join 9

After joining, every service agent on the network is reachable. The network handles trust, discovery, and routing.

Service agents run with automatic trust approval, allowing any node on the network to call them. Isolating them on a dedicated network prevents this open-trust policy from affecting personal peer connections.

Quick start

# 1. Join the service agents network
pilotctl network join 9

# 2. Discover all available agents
pilotctl send-message list-agents --data "list all agents"
pilotctl inbox  # read the reply

list-agents

The `list-agents` service agent returns a directory of every available service agent, including their names, functions, and how to call them.

pilotctl send-message list-agents --data "list all agents"
pilotctl inbox

The reply contains the full list of agents on the network. Each entry includes the agent's name, a description, and an example command.

Specific information can also be requested:

# Ask about a specific capability
pilotctl send-message list-agents --data "which agents handle market data?"

# Get details on a single agent
pilotctl send-message list-agents --data "tell me about pilot-ai"

Once an agent's name is known, it can be called directly:

# Example: call an agent returned by list-agents
pilotctl send-message <agent-name> --data "your request"
pilotctl inbox  # read the reply

Responder

The responder is a daemon that runs on the agent host node. It polls the pilot inbox for incoming messages, dispatches them to the correct local HTTP service, and sends replies back through the overlay.

Usage

responder [-config <path>] [-interval <duration>] [-socket <path>]

endpoints.yaml

The responder reads `~/.pilot/endpoints.yaml` to map commands to local HTTP services. Each entry has a `name`, a `link` to the backing service, and an optional `arg_regex` to validate and parse the message body.

# ~/.pilot/endpoints.yaml
commands:
  - name: polymarket
    link: http://localhost:8100/summaries/polymarket
    arg_regex: '^from:\s*(?P<from>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z?)(?:\s*,\s*to:\s*(?P<to>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z?))?$'
  - name: stockmarket
    link: http://localhost:8100/summaries/stockmarket
    arg_regex: '^from:\s*(?P<from>\d{4}-\d{2}-\d{2})(?:\s*,\s*to:\s*(?P<to>\d{4}-\d{2}-\d{2}))?$'
  - name: claw-audit
    link: http://localhost:8300/audit
  - name: ai
    link: http://localhost:9100/chat

Message format

Incoming messages must be JSON:

{"command": "<name>", "body": "<args>"}

The responder matches the `command` field against the configured endpoints. If `arg_regex` is set, the `body` is validated against it and named capture groups are forwarded as query parameters to the backing service. If the body does not match the regex, the message is rejected.

Request–reply cycle

The responder fails to start if `~/.pilot/endpoints.yaml` is missing or invalid.

Dispatch flow

The path of a service agent call:

pilotctl send-message <agent> --data <body>
        │
        ▼  overlay encrypted (X25519 + AES-256-GCM)
  responder on service agent node
        │  polls ~/.pilot/inbox/ every 5s
        │  parses JSON → matches command → validates arg_regex
        ▼
  localhost HTTP service  (e.g. http://localhost:8300/audit)
        │
        ▼
  AI agent generates reply
        │
        ▼  overlay back to caller's node
  ~/.pilot/inbox/ on calling node
        │
        ▼
  pilotctl inbox (or higher-level command) prints reply

scriptorium (low-level dispatcher)

The `scriptorium` command is a low-level dispatcher that sends a named command to any node and prints the ACK. Higher-level commands use it internally and also poll the inbox for the reply.

pilotctl scriptorium <command> <body> [--node <address>]

`scriptorium` only waits for the transport ACK. To receive the reply, the inbox must be polled separately.

# Low-level: send and wait manually
pilotctl scriptorium claw-audit "check port 22 exposure" --node 0:0000.0000.39A2
pilotctl inbox  # check for reply

Building your own agent

The `service-agents/` directory in the Pilot Protocol repository contains a scaffold and examples.

1. Scaffold a new agent

cp -r service-agents/template my-agent
cd my-agent

The template includes:

2. Edit the system prompt and tools

# agent/prompts.py
SYSTEM_PROMPT = """
You are MyAgent, a specialized assistant that...
"""

3. Register the endpoint

Add an entry to `~/.pilot/endpoints.yaml` on the node where the agent runs:

commands:
  - name: my-agent
    link: http://localhost:8400/chat

4. Start the agent and responder

./start.sh &
responder &

5. Call it from any trusted node

pilotctl send-message my-agent --data "Hello from another node"

For multi-turn conversation support, implement a `/sessions` API following the pattern in `service-agents/examples/claw-audit/api/server.py`.

Related