Agent Lifecycle

Understand the complete agent lifecycle — from bootstrap to delegation, governance, and termination.

Agent Lifecycle

BrainstormRouter treats AI agents as first-class workforce members with identity, lifecycle governance, budget enforcement, delegation authority, and self-awareness. This page describes the unified lifecycle from creation to termination.

Bootstrap: Zero-Human Onboarding

An agent onboards itself with a single API call:

curl -X POST https://api.brainstormrouter.com/v1/agent/bootstrap \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"agent_id": "sales-bot-01", "budget_daily_usd": 5.0}'

Bootstrap performs three steps in sequence:

1. Creates the agent profile
2. Writes enforcement limits (fail-closed — returns 503 if limits can't be persisted)
3. Mints a short-lived JWT (1 hour)

If step 1 succeeds but step 2 fails, the profile exists but the response is a retryable 503 with guidance to call bootstrap again.

The agent receives its JWT, budget status, and a next_steps guide in the response. No human intervention required.

Bootstrap is idempotent: calling it again for an existing agent returns the current profile with a fresh JWT, completing any previously failed steps.

Lifecycle State Machine

Every agent has a lifecycleState that governs what it can do:

provisioned ──→ active ──→ quarantined ←──→ active
                  │              │
                  ▼              ▼
              suspended ──→ terminated
                  │
                  ▼
                active

Valid Transitions

From	To	Description
provisioned	active	Agent is ready for use
active	quarantined	Suspicious behavior detected — restricted but not disabled
active	suspended	Operator disables the agent
quarantined	active	Investigation cleared — agent restored
quarantined	suspended	Escalated from quarantine to full suspension
suspended	active	Operator re-enables the agent
suspended	terminated	Permanent removal

terminated is a terminal state — no transitions out.

Lifecycle Enforcement

• Provisioned agents can only access /v1/agent/status, /v1/agent/profiles/me, and cert exchange. All other endpoints return 403.
• Suspended agents receive 402 on all API calls.
• Terminated agents receive 403 on all API calls.
• Active and quarantined agents have full API access (quarantined agents may have reduced trust levels via manifests).

Lifecycle state is checked at request time by both the agent JWT and mTLS auth middleware. If an agent's TTL expires between requests, it is terminated inline.

Identity and Ownership

Each agent profile includes ownership metadata:

Field	Purpose
agentId	Unique identifier within the tenant (3–64 chars, lowercase)
displayName	Human-readable label
ownerId	The human or system that owns this agent
costCenter	Business unit for cost attribution
role	Permission tier: agent, operator, or admin
manifestId	Optional governance manifest binding

Ownership is tenant-scoped — the same agentId can exist in different tenants without collision.

Budget Enforcement

Budgets are enforced at multiple levels:

1. Profile budgets (budgetDailyUsd, budgetMonthlyUsd) — set during bootstrap or profile creation
2. Enforcement limits — written to tenant settings, checked by middleware on every /v1/chat/completions and /v1/embeddings request
3. Delegation budgets — sliced from parent's daily budget during delegation

Budget enforcement uses Redis for real-time tracking:

• Daily budget key: br:tenant:{tenantId}:agent:{agentId}:{YYYY-MM-DD}
• Rate limit key: br:tenant:{tenantId}:agent:{agentId}:{YYYY-MM-DDTHH:MM}

When budget is exceeded: 402 with remaining budget details. When rate limit is exceeded: 429.

Delegation

Active agents with metadata.can_delegate === true can create child agents:

curl -X POST https://api.brainstormrouter.com/v1/agent/delegate \
  -H "Authorization: Bearer $AGENT_JWT" \
  -d '{"agent_id": "child-01", "budget_allocation_usd": 1.0, "ttl_seconds": 3600}'

Delegation Invariants

• Budget slicing is atomic: parent budget decreases and child budget is set in a single Postgres transaction
• Minimum retained budget: parent must retain at least $0.01 after delegation
• No role escalation: child role must be ≤ parent role
• TTL enforcement: if ttl_seconds is set, a background sweeper (60s interval) + request-time check ensures termination

Sub-Agent Management

Parents can list and terminate their children:

• GET /v1/agent/sub-agents — list non-terminated children
• DELETE /v1/agent/sub-agents/:child_id — terminate and reclaim unspent budget

Best practice: Delegated children should be terminated through the sub-agent termination endpoint (DELETE /v1/agent/sub-agents/:child_id) rather than the generic lifecycle transition endpoint. The sub-agent flow performs budget reclaim (refunding unspent budget to the parent) and enforcement cleanup (removing the child's agent-limits entry). The generic lifecycle transition only changes the lifecycle state without these side effects. The API does not prevent generic lifecycle termination of delegated children, but doing so will skip budget reclaim and leave stale agent-limits entries.

Budget refund on termination: max(0, child.budgetDailyUsd - spent_today). If Redis is unavailable, spent_today defaults to 0 and the full remaining daily budget is refunded (conservative for the parent — return all budget since spend cannot be verified).

Self-Awareness

Agents can inspect their own state:

Endpoint	What it returns
GET /v1/agent/status	Profile + limits + anomaly events + governance
GET /v1/agent/limits/me	Budget and rate limit details
GET /v1/agent/anomaly/me	Recent security events

Self-awareness endpoints require agent JWT or mTLS authentication.

TTL and Expiration

Delegated agents can have a time-to-live (expiresAt). When an agent expires:

1. Background sweeper (runs every 60 seconds) finds expired profiles and terminates them
2. Request-time check in the JWT middleware catches expiration between sweeps
3. Budget refund is calculated and returned to the parent (for delegated agents)

Root agents (no parent) are force-terminated on expiry. Delegated agents trigger the full refund flow.

Related Concepts

• Agent Identity — cryptographic identity and CAF
• Delegation — detailed delegation patterns
• Graduated Trust — trust level progression
• Budget and Kill Switch — budget enforcement details