Agents

An agent is an AI actor hired onto one app group’s roster. Each agent carries its own machine ConnectedId (Type=AI) — permissions attach to that badge, not to a borrowed key, so an agent shows up in the same access review as the person who created it. Agents take no seat, never appear in member lists or SCIM /Users, and are born with a TTL: creation without an expiry is rejected, and an expired agent is automatically suspended.

Base path: /api/org/{slug}/app-groups/{groupId}/agents (authenticated). Mutations are hard-gated by the org.agent.* scopes.

Method · Route	Purpose	Required scope
GET `/`	List the roster (joined with badge status)	membership
GET `/templates`	Kind template catalog (preset scopes per kind)	membership
POST `/`	Hire an agent (`kind`, `displayName`, `expiresAt`, `scopes[]?`, `description?`, `systemPrompt?`, `model?`)	`org.agent.hire`
PUT `/{agentId}`	Update name / description / system prompt / model / TTL	`org.agent.update`
POST `/{agentId}/suspend` · `/{agentId}/activate`	Suspend or reactivate	`org.agent.suspend`
DELETE `/{agentId}`	Revoke — roster row retired, badge deactivated	`org.agent.revoke`

What `POST /` (hire) does

Issues a machine badge — ConnectedId with Type=AI, UserId=null, MembershipType=None.
Finds or creates the role for that kind — AGENT_{KIND}, e.g. AGENT_DESIGN. ⚠️ This role is shared by every agent of that kind in the organization. Widening it widens all of them at once. Hire a different kind when you want a different authority.
Grants the kind template’s scopes to that role, the first time the role is created. org.agent.hire is always refused — agents do not hire agents. Note that custom has an empty template, so a custom agent starts with no scopes at all and can do nothing until someone adds permissions to AGENT_CUSTOM through the normal roles screen.
Assigns the role to the badge (snapshotting permissions — the snapshot is the agent’s toolset).
Writes the roster row, recording expiresAt (TTL, required, must be in the future) and the ConnectedId of the person who hired it.

Kind templates

GET /templates returns the preset catalog. Every preset scope is a real entry in the derived permission catalog — nothing invented:

Kind	What it does	Writes?
`design`	Screens and branding (HTML/CSS)	screens
`db`	Table schemas and queries	schemas, queries
`api`	Key issuance and webhook wiring	keys, webhooks
`test`	Scenario verification	nothing — read/list only
`infra`	App settings and client registration	app config
`custom`	Pick scopes yourself	starts with zero

harnessReady: false means the Axowl console cannot drive that kind for you yet — it does not mean the agent is unusable. Every kind is hireable today, and its badge, scopes, TTL, gate and audit trail work the same either way.

Where an agent runs

Axowl issues and enforces the authority; it does not require you to run the model here.

Your runtime (any kind). The agent’s badge is a machine ConnectedId, so it can obtain an M2M token and call the public API directly. Scope enforcement, denial events and the TTL apply exactly as they do in the console — the gate lives on the server, not in the harness.
The Axowl console (kinds with harnessReady: true). For teams with no agent runtime of their own, the console runs the model for you and applies the result through the same gate. Token usage is metered per badge; agents never consume a seat.

Enforcement and audit

Tool gate. Every write an agent produces is checked against its badge’s permission snapshot before being applied — the check is server-side, so it holds whether the agent runs in the Axowl console or in your own runtime. A denial is not silent: it is recorded in the reply (“denied — agent lacks org.record_schema.update”) and sealed as an agent.action_denied audit event.
Suspension cuts credentials. Suspending or revoking an agent flips its badge status, which immediately blocks M2M token issuance and console execution.
Lifecycle is sealed. agent.hired, agent.suspended (manual or expired via the TTL worker) and agent.revoked are all sealed audit events — a revocation is an append-only fact, not a row someone can quietly delete.
Billing. Each console reply row carries the agent’s badge id alongside its token usage, so per-agent cost is a single aggregation over existing metering — agents are billed by usage, never by seats.

See also Service accounts (machine badges for external systems) and Roles & permissions.