Agent Resource Management Convergence — 17 endpoints, 15 SDK methods, 8 MCP tools unified

2026-03-10

agent-profilesagent-bootstrapagent-delegationagent-lifecycle

LOCKSTEP TRACEABILITY MATRIX --- api_endpoints: ["none — all 17 endpoints pre-existing"] sdk_methods_updated: ["none — all 15 methods pre-existing in both SDKs"] sdk_parity_status: "pre-existing" mcp_tools_updated: ["none — all 8 tools pre-existing, audit passed clean"] ---

What We Built

Consolidated BrainstormRouter's agent management system — previously scattered across 6 API route files, 2 SDKs, 8 MCP tools, a 506-line dashboard page, and 4 separate concept docs — into a single coherent product area with unified documentation.

Added 3 new documentation pages (API reference, lifecycle concept, SDK reference), 33 lifecycle state machine test cases, and verified cross-surface parity across all 9 surfaces.

Why It Matters

Enterprise teams deploying AI agent fleets need a single source of truth for agent identity, lifecycle governance, budget enforcement, and delegation authority. Before this phase, the agent management capability existed but was documented across scattered concept pages without a unified API reference or SDK guide. Now operators can find everything in one place: bootstrap an agent, manage its lifecycle, delegate budget, and monitor anomalies.

How It Works

Lifecycle State Machine

provisioned → active → quarantined ↔ active → suspended → terminated

Five states, seven valid transitions. Terminated is terminal. Enforcement happens at request time via JWT middleware — suspended agents get 402, terminated get 403.

Budget Delegation (Atomic)

const child = await client.agentProfiles.delegateAgent({
  agent_id: "child-worker-01",
  budget_allocation_usd: 1.0,
  ttl_seconds: 3600,
});

Parent budget decreases and child budget is set in a single Postgres transaction. Parents must retain at least $0.01. Children cannot escalate beyond parent's role.

Self-Awareness

const status = await client.agentProfiles.status();
// { profile, limits, anomaly, governance }

Agents can introspect their own profile, budget remaining, rate limit usage, and security events — all with a single call.

The Numbers

Metric	Value
API endpoints	17 across 6 route files
TS SDK methods	15 (including adminDelegate)
Python SDK methods	15 sync + 15 async
MCP tools	8
Lifecycle states	5
Valid transitions	7
Dashboard pages	2 (workforce + agents)
New test cases	33 (7 valid transitions, 18 invalid, 1 terminal, 4 reachability, 3 role subset)
Ship log entries	3 (ARM, bootstrap, convergence)

Competitive Edge

No competing platform (Portkey, OpenRouter, Lasso, Letta) offers a unified agent lifecycle with atomic budget delegation, self-awareness APIs, and TTL enforcement. BrainstormRouter treats agents as workforce members with HR-grade governance: provisioning, quarantine, suspension, termination, and budget reclamation — all auditable, all API-first.

Cross-Surface Parity Matrix

API Route	Method	TS SDK	Python SDK	MCP Tool	Docs	Dashboard
POST /v1/agent/bootstrap	POST	`bootstrap()`	`bootstrap()`	`br_bootstrap_agent`	API ref	Provision form
GET /v1/agent/status	GET	`status()`	`status()`	`br_agent_status`	API ref	—
GET /v1/agent/limits/me	GET	`limitsMe()`	`limits_me()`	`br_agent_limits`	API ref	Budget gauges
GET /v1/agent/anomaly/me	GET	`anomalyMe()`	`anomaly_me()`	`br_agent_anomaly`	API ref	Anomaly dots
GET /v1/agent/profiles	GET	`list()`	`list()`	`br_list_agents`	API ref	Agent roster
POST /v1/agent/profiles	POST	`create()`	`create()`	—	API ref	—
GET /v1/agent/profiles/me	GET	`me()`	`me()`	—	API ref	—
GET /v1/agent/profiles/:id	GET	`get()`	`get()`	—	API ref	Agent dossier
PATCH /v1/agent/profiles/:id	PATCH	`update()`	`update()`	—	API ref	—
DELETE /v1/agent/profiles/:id	DELETE	`delete()`	`delete()`	—	API ref	—
PATCH /v1/agent/profiles/lifecycle/:id	PATCH	`transition()`	`transition()`	—	API ref	Lifecycle badges
POST /v1/agent/delegate	POST	`delegateAgent()`	`delegate_agent()`	`br_delegate_agent`	API ref	Hierarchy tree
GET /v1/agent/sub-agents	GET	`listSubAgents()`	`list_sub_agents()`	`br_list_sub_agents`	API ref	Child list
DELETE /v1/agent/sub-agents/:id	DELETE	`terminateSubAgent()`	`terminate_sub_agent()`	`br_terminate_sub_agent`	API ref	Terminate btn
POST /auth/agent-profiles/:id/delegate	POST	`adminDelegate()`	`admin_delegate()`	—	—	Delegate bridge

Tenant Administration (not part of agent profiles SDK scope):

API Route	Method	TS SDK	Python SDK	MCP Tool	Docs	Dashboard
GET /v1/agent-limits	GET	—	—	—	API ref	—
PUT /v1/agent-limits	PUT	—	—	—	API ref	—
PATCH /v1/agent-limits	PATCH	—	—	—	API ref	—

Intentional omissions:

Profile CRUD (create, get by ID, update, delete, me) are admin operations not exposed via MCP — agents use bootstrap/status instead
/v1/agent-limits is tenant-level configuration, not an individual agent operation — excluded from SDK agentProfiles scope by design, managed via tenant settings or direct HTTP
adminDelegate uses the /auth/ Supabase bridge, not the /v1/ path — dashboard-specific

MCP Audit Results

All 8 agent MCP tools audited against HTTP RBAC (24 checks):

Names: match ✓
Descriptions: match ✓
Permissions: match ✓

agents.json entries exactly match tool-manifest.ts. src/mcp/server.ts evaluated — agent deps already wired, no changes needed.

Dashboard Verification Audit

Dashboard agent management spans two surfaces: site/dashboard/src/pages/workforce.ts (roster, hierarchy, shadow AI) and site/dashboard/src/components/agent-dossier.ts (full agent detail panel).

Workforce page (workforce.ts, 506 LOC):

Lifecycle state badges — 5 states with color-coded CSS classes (cc-lifecycle-provisioned, etc.) ✓
Delegation hierarchy — tree view with parent-child relationships and TTL indicators ✓
Budget governance — radial gauge per agent card showing daily budget ✓
Shadow AI detection — unmanaged API keys surfaced with "bring under governance" action ✓
Agent provisioning — button always visible (no admin gate on the button itself; the API enforces auth) ✓
Sub-agent termination — admin-gated terminate buttons; page refreshes on success (no budget refund amount displayed in UI) ✓

Agent dossier (agent-dossier.ts, 563 LOC):

Ownership metadata — ownerId and costCenter displayed in dossier header meta row ✓
Lifecycle transition actions — buttons matching backend state machine (fixed in this phase: removed invalid direct-to-terminated transitions) ✓
Budget editing — inline budget editor for daily and monthly limits ✓
Delegation — delegate sub-agent drawer with role selector and JWT display ✓

Corrections from initial audit: Roster cards do not display ownerId/costCenter (those appear in the dossier). Provisioning button is not admin-gated in the UI (API enforces auth). Terminate buttons do not display budget_refunded_usd (page refreshes instead).

Lockstep Checklist

N/A API Routes: All 17 endpoints pre-existing across 6 route files. No new endpoints in this phase.
N/A TS SDK: All 15 methods pre-existing. No API changes → no SDK updates needed.
N/A Python SDK: All 15 sync + 15 async methods pre-existing. No API changes → no SDK updates needed.
N/A MCP Schemas: 8 tools audited clean (24/24 checks pass). No updates needed.
[x] Docs: 3 new pages added (API reference, lifecycle concept, SDK agents).
[x] Dashboard: Fixed lifecycle transition map in agent-dossier.ts (removed invalid direct-to-terminated transitions). Verified workforce page and dossier against acceptance criteria.
[x] Tests: 33 new test cases for lifecycle state machine and role subset enforcement.