Skip to content
Quayside

Register an agent class

You have a new agent you want to bring under Quayside governance. Three ways to register it.

Via the dashboard

The most common path.

  1. Open /classes/new
  2. Fill in slug, name, purpose, owner, initial lifecycle (default active)
  3. Register class

You land on the class detail page. The class is immediately usable — instances claim against it on first call, audit aggregates against it, policy attaches to it.

Via the CLI

For scripts, IaC, or copy-pasting from a notebook.

Terminal window
quayside class register \
  --slug eng/code-reviewer \
  --name "Code Reviewer" \
  --purpose "Reviews PRs on the platform team; posts inline comments." \
  --owner alice@example.com

You can also list, show, and deprecate:

Terminal window
quayside class list
quayside class list --status draft


quayside class show eng/code-reviewer


quayside class deprecate eng/code-reviewer

Via HTTP

What both of the above are doing under the hood.

Terminal window
curl -X POST http://localhost:8000/api/v1/registry/classes \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "eng/code-reviewer",
    "name": "Code Reviewer",
    "purpose": "Reviews PRs on the platform team; posts inline comments.",
    "owner_principal_id": "alice@example.com",
    "lifecycle_status": "active"
  }'

Returns 201 Created with the new class row.

What you can’t do

  • Register a class as external or sunset — those statuses are reached via other paths (shadow discovery and lifecycle transition respectively)
  • Use a slug that’s already in use — returns 409 Conflict
  • Use an invalid slug — returns 422 (slugs must be lowercase, with hyphens / underscores / dots / slashes)
  • Supersede a class that doesn’t exist — returns 404

Conventions for slugs

We recommend <team>/<agent-name> so the slug doubles as documentation of ownership:

  • eng/code-reviewer
  • support/tier1-bot
  • finance/expense-classifier
  • ops/incident-summary

This isn’t enforced. You can use any slug that matches the validation regex (^[a-z0-9][a-z0-9._/\-]*$).

What happens next

The class needs a policy before the proxy will know what detectors to run for it. The dev seed gives every newly-created tenant one example policy, but for your new class:

  • Either copy an existing policy via the dashboard’s policy editor
  • Or POST a PolicyBody to /api/v1/policy/class/{id}/drafts and publish it

Until a class has a published policy, calls to the proxy for that class will return 404 (no active policy) from the policy service.