Agent Lifecycle and Configuration

The current Agent model

Agent
├── Organization ownership
├── Agent Access
├── Runtime: Hermes or OpenClaw
├── Lifecycle: STOPPED, RUNNING, or ERROR
├── Exact Template or Override pin
├── Exact Skill assignments and pins
├── Model inheritance or explicit override
├── Tool Integration credentials
├── Runtime deployment and LiteLLM identity
└── Zero or more Communication Connections
    ├── Platform Plugin
    ├── Provider credentials
    ├── Provider settings and policies
    ├── Independent health
    └── Durable Deliveries

An Agent is not synonymous with a messaging bot or provider installation. Hermes and OpenClaw are the two persisted Runtime choices in agent_type; both use the same versioned, Runtime-neutral Communications protocol. Platform is not an Agent field, and changing Communication Platforms never changes Runtime.

Keep domain ownership separate

Create a headless Agent

Every new Agent is headless, STOPPED, owned by one Organization, and grants explicit Agent Owner access to its creator. General Organization access is restricted by default.

Creation does not start the Runtime, select a Communication Platform, require messaging credentials, create a provider app or Connection, derive status from a Platform, or persist Platform on the Agent. Tool Integration credentials may be supplied when selected Skills require them; they are not messaging credentials.

Runtime is selected at creation and the direct Agent update contract does not provide a Runtime-change field. An Agent can have no Connections, one Connection, multiple Connections for one Platform, or Connections for different Platforms.

Use the persisted lifecycle states

create ─────────────────────────────→ STOPPED
STOPPED or ERROR ─── start ─────────→ RUNNING
RUNNING ──────────── stop ──────────→ STOPPED
start deployment failure ───────────→ ERROR
any non-deleted state ─── delete ──→ soft-deleted

Starting an already running Agent returns a conflict. Stopping an Agent that is not running also returns a conflict. A successful start from ERROR clears the prior lifecycle error. There are no persisted STARTING, STOPPING, PAUSED, or provider-specific lifecycle states.

Configure each owned surface

1. Profile holds Agent identity and Runtime-relevant settings.
2. Template selects the exact shared or Agent Override snapshot.
3. Messaging Connections manages provider transport independently.
4. Skills manages exact published Skill assignments.
5. Keys and Integrations manages tool credentials, never messaging-provider credentials.
6. Agent-owned Template Override manages private Template customization.
7. Danger zone contains destructive Agent actions.

Communication Connections have their own create, edit, enable, disable, reconnect, and retire operations; statuses are PENDING, CONNECTING, CONNECTED, DEGRADED, and ERROR. Their changes reconcile the Connection and increment its revision when needed, without restarting the Agent or changing its Runtime or lifecycle.

Inherit a model or choose an override

An Agent can Use organization default or Choose a specific model. An empty stored Agent model means inheritance; sending { "model": null } clears an explicit override and returns the Agent to inheritance.

effective_model
  = explicit Agent model
  or Organization effective default

Organization effective default
  = Organization-owned default
  or platform default

Organization default changes do not rewrite overrides or hot-reload running Agents. A running inheriting Agent keeps its running_model until restarted. At start, an explicit override is rechecked against the Organization allowlist; an invalid override prevents start. An inherited platform default may be outside that list because deployment controls it.

Pin Templates, Overrides, and Skills

Each Agent pins one exact shared Platform Template Version, Organization Template Version, or Agent Template Override Version. Publishing a newer version never moves an Agent. For a stopped Agent, Apply changes the pin and materializes it on next start. For a running Agent, Apply & Restart stops, changes the pin, then starts again.

An Agent Template Override is Agent-owned, begins from a complete shared snapshot, uses one mutable draft and immutable published Override Versions, and is isolated from sibling Agents. Publishing an Override Version does not activate it automatically.

Skills come from Platform, Organization, and the Agent’s private Skills. Each assignment pins skill_id + pinned_version; start mounts those exact files. Publishing a newer Skill Version does not move an assignment, and Skills do not create credentials, permissions, or Communication Connections.

Use the right credential boundary

Apply changes deliberately

Direct Runtime-relevant Agent updates are rejected while the Agent is running. Apply & Restart is explicit orchestration: stop, update, then start.

Start authorizes lifecycle management; loads the pinned Template or Override; resolves and rechecks the model; renders Template Markdown; loads exact Skills; decrypts tool credentials; materializes supported aai-cli and Google Workspace artifacts; creates fresh Ingest and Communications credentials; builds Runtime ConfigMap, Secret, PVC, Service, and Deployment resources; then persists RUNNING and running_model. Provider messaging tokens remain in Communications.

Stop, recover, and delete safely

Stop captures a best-effort log snapshot, removes active Runtime Deployment resources and generated configuration and secret material, persists STOPPED, clears running_model, and preserves the Agent record, configuration, Connections, history, and cost attribution. Stop is not deletion and does not retire Connections.

Deletion removes Runtime resources, soft-deletes the Agent, retires owned Connections, cancels applicable pending Deliveries, releases provider credential identities, attempts to block the LiteLLM key, and preserves the historical identity required for cost attribution. Retiring one Connection remains a separate operation.

Authorize Agent operations

Relevant permissions are agent.read, agent.update, agent.lifecycle.manage, agent.secret.manage, agent.delete, and agent.access.manage. Connection mutations require access to the owning Agent; credential creation, replacement, and retirement additionally require secret-management authority. Do not infer authorization solely from Organization membership.

POST   /api/v1/organizations/{organization_id}/agents
GET    /api/v1/organizations/{organization_id}/agents/{agent_id}
PATCH  /api/v1/organizations/{organization_id}/agents/{agent_id}
POST   /api/v1/organizations/{organization_id}/agents/{agent_id}/start
POST   /api/v1/organizations/{organization_id}/agents/{agent_id}/stop
GET    /api/v1/organizations/{organization_id}/agents/{agent_id}/healthz
DELETE /api/v1/organizations/{organization_id}/agents/{agent_id}

An Agent create request may contain name, agent_type, template_key, an optional Template version or model override, optional exact Skill pins and tool credentials, and approval mode. It contains no Platform or Connection fields.

Agent updates and release notices

When an Agent pod is running an older platform release than the deployed cluster baseline, the Agent detail page displays an advisory Agent Update Banner directly above tabs. The banner highlights that a new version of the Agent is available, links to the GitHub release notes, and provides an Update action that orchestrates a graceful stop and restart to roll the pod onto the latest runtime baseline.

Continue with the focused guides

• Agent Lifecycle, Agent Configuration, and Choose a Runtime
• Communication Connections and Organization Agent Settings
• Templates, Skill Versions, and Agent Overrides
• Integrations and Credentials, Health and Logs, and Roles, Permissions, and Agent Access