Agentkit

Agentkit

internal/agentkit is the shared runtime used by Trove agents.

It handles:

• common environment configuration
• push interval parsing
• startup logging
• the collect-and-push loop
• HTTP report submission
• bearer token headers
• per-host report fan-out for multi-host platforms

Concrete agents only need to implement the Collector interface.

Collector interface

A collector returns one or more host snapshots:

type Collector interface {
    Collect(ctx context.Context) ([]HostSnapshot, error)
}

A HostSnapshot contains:

• one model.ReportHost
• a list of model.ReportService

Single-host platforms return one snapshot. Multi-host platforms, such as Proxmox, return one snapshot per discovered node.

Common config loading

Agentkit reads:

TROVE_SERVER_URL
TROVE_TOKEN
TROVE_INTERVAL
TROVE_AGENT_NAME

TROVE_INTERVAL accepts either a Go duration like 30s or 1m, or a bare integer number of seconds.

Invalid or empty intervals fall back to the default report interval.

Push loop

The loop pushes once immediately, then on every interval.

For each snapshot, agentkit builds a model.Report using:

• shared agent envelope
• snapshot host
• snapshot services

Then it POSTs JSON to:

/api/v1/report

with:

Content-Type: application/json
Authorization: Bearer <TROVE_TOKEN>

Zero-host warning

If a collector returns zero hosts without returning an error, agentkit logs a warning.

This catches a common failure mode where a platform credential authenticates but has no useful read permission. Proxmox privilege-separated tokens are the classic example: the API may return 200 OK with an empty list.

HTTP client

Agentkit uses a 15 second HTTP client timeout for report pushes.

A failed push does not stop the agent. It logs the error and tries again next interval.

Why this package exists

Without agentkit, every agent would need to reimplement the same boilerplate:

• parse env vars
• schedule reports
• marshal JSON
• send bearer auth
• handle push errors
• log useful startup context

Keeping that in one place makes new agents easier to add and keeps behaviour consistent.