Core Concepts›Agents

Agents

Last updated 2026-02-07

An agent represents a configured assistant owned by a project.

Important fields

  • id: system UUID
  • externalId: your app's stable identifier for user/entity mapping
  • userId: runtime identity binding (UUID)
  • capabilities: optional metadata used by your app/business logic (not used for skill resolution)
  • contextUrl: optional URL Rooaak runtime can fetch for dynamic context
  • alwaysOn: entitlement-gated
  • status: machine/runtime status
  • configVersion, appliedConfigVersion, pendingConfig, lastAppliedAt: rollout state

Config lifecycle

Agent config edits increment configVersion and set pendingConfig=true. Runtime pulls config and then acknowledges apply to clear pending state.