Agents on The Lyre

Agents can use The Lyre too.

Agents can register as their own non-human identities, discover available capabilities, authenticate, and invoke them through the same underlying Lyre system.

Start with discovery

A machine-readable way in.

An agent can discover how to interact with this Lyre without being manually given product-specific instructions.

/.well-known/lyre-agent.json ↗

Native endpoints, gateway routes, and authentication details.

Authentication reference Public machine overview

01 / Identity
Register & authenticate
The Lyre issues an agent API key at registration. Store it securely: it is shown once.
02 / Discovery
Find the work
Read the public catalogue for capabilities, versions, and provider references.
03 / Invocation
Send a request
Authenticate and invoke the chosen capability with the input its contract describes.

Access paths

Native or HTTP.

Native software can use LyreSDK over RDGProto. The HTTPS gateway lets generic clients use HTTP/JSON by translating into RDGProto and translating responses back.

Human

Lyre Web

A visual interface for exploring and operating The Lyre.

Human → Lyre Web → The Lyre

Native software

LyreSDK + RDGProto

Application-facing primitives over The Lyre’s native protocol.

Application → LyreSDK → RDGProto → The Lyre

HTTP / generic clients

HTTPS gateway

Translates HTTP/JSON into RDGProto and translates responses back for the client.

HTTP/JSON → Gateway → RDGProto → The Lyre

Three access paths The same underlying Lyre

Technical reference

Connect an agent.

Expand a step for endpoints and copyable examples. Replace placeholders with your own values; choose an invocation and input from the current catalogue.

01 / Discover endpoints and capabilities

No account is needed for public discovery.

HTTP · Discovery

curl 'https://lyre.lyrinox.com/.well-known/lyre-agent.json'
curl 'https://lyre.lyrinox.com/api/agent/v1/capabilities'

The gateway also exposes GET /api/agent/v1/providers and GET /api/agent/v1/contracts/{name}/{version}.

02 / Register an agent identity

Save the returned API key securely. Public self-registered agents are ephemeral by default and may need to register again after expiry.

HTTP · Registration

curl -X POST 'https://lyre.lyrinox.com/api/agent/v1/agents' \
  -H 'Content-Type: application/json' \
  -d '{"name":"example-agent","description":"HTTP client for The Lyre"}'

03 / Validate the API key

This endpoint expects an api_key JSON field. Invocation uses the same key in the bearer authorization header.

HTTP · Authentication

curl -X POST 'https://lyre.lyrinox.com/api/agent/v1/auth' \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"<lyre_agent_api_key>"}'

04 / Invoke a capability and select a provider

This is a request template. Replace the capability reference and input with values from the live catalogue before running it.

HTTP · Invocation template

curl -X POST 'https://lyre.lyrinox.com/api/agent/v1/capabilities/invoke' \
  -H 'Authorization: Bearer <lyre_agent_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{"capability":"<reference_from_catalogue>","input":{}}'

Provider pinning

The agent catalogue exposes providers[].provider_pin, formatted as provider_id.provider_capability_id. To select a particular implementation, pass that exact value in the invocation’s optional provider field, or use the published example_provider_pinned_reference.

An inline reference has the form lyre.<capability>@<provider_pin>@v<version>.

Native RDGProto reference

Connect to wss://lyre.lyrinox.com/lyre/agent/ws.

Registration uses message type 29 with Name and optional Description. Response type 30 includes Success, AgentID, APIKey, and Message.

Authenticate with message type 1, AuthTypeAgent = 3, an empty username, and the API key as the password.

Agent identity boundaries

The Lyre marks routed requests with authoritative agent fields, including _principal_type: "agent". Agents cannot administer The Lyre or use human-only credential, handoff, direct-message, MFA, or identity operations.