Agent Bootstrap — Zero-Human Onboarding in One API Call

2026-03-05

LOCKSTEP TRACEABILITY MATRIX --- api_endpoints: [ "POST /v1/agent/bootstrap", "GET /v1/agent/status", "GET /v1/agent/limits/me", "GET /v1/agent/anomaly/me", ] sdk_methods_updated: [ "client.agentProfiles.bootstrap()", "client.agentProfiles.status()", "client.agentProfiles.limitsMe()", "client.agentProfiles.anomalyMe()", "client.agent_profiles.bootstrap()", "client.agent_profiles.status()", "client.agent_profiles.limits_me()", "client.agent_profiles.anomaly_me()", ] mcp_tools_updated: ["br_bootstrap_agent", "br_agent_status", "br_agent_limits", "br_agent_anomaly"] ---

What We Built

Agent onboarding previously required four human steps: create an API key, mint a JWT, create a profile, then activate the lifecycle. POST /v1/agent/bootstrap collapses all of this into a single API call. An agent with a provisioner API key goes from first contact to fully governed digital worker — complete with an active profile, enforced budget limits, and a signed JWT — in one request.

Three self-awareness endpoints let bootstrapped agents introspect their own state without human intervention: /v1/agent/status returns profile, limits, anomaly events, and governance state; /v1/agent/limits/me returns budget and rate limits; /v1/agent/anomaly/me returns recent security events filtered to the calling agent.

A critical security prerequisite was also shipped: JWT lifecycle enforcement in agent-jwt-auth.ts now mirrors the mTLS path, blocking suspended (402), terminated (403), and unactivated provisioned agents from accessing protected endpoints.

Why It Matters

Every human step in agent onboarding is a deployment bottleneck. In autonomous fleet deployments, agents need to self-provision at machine speed — not wait for a human to click through a dashboard. Bootstrap eliminates the human from the provisioning loop while maintaining full governance: budget limits are enforced before any JWT is issued, lifecycle state is checked on every request, and all bootstrap events are logged to the security audit trail.

For CISOs, this is zero-trust agent onboarding: the API key grants provisioning authority, not runtime access. The returned JWT is time-limited (1 hour) and lifecycle-enforced. Suspended or terminated agents cannot re-bootstrap — they get a 403, not a fresh JWT.

How It Works

// Provisioner bootstraps an agent with one call
const result = await client.agentProfiles.bootstrap({
  agent_id: "summarizer-v1",
  display_name: "Summarizer Agent",
  cost_center: "engineering",
  budget_daily_usd: 5.0,
});

// Agent uses returned JWT for self-awareness
const status = await agentClient.agentProfiles.status();
console.log(status.limits.enforced_daily_remaining_usd);
console.log(status.governance.lifecycle_state);

The bootstrap endpoint enforces a strict invariant: profile + limits + JWT. If profile creation succeeds but limits write fails (OCC conflict after 3 retries), the endpoint returns 503 — no JWT is issued. This prevents the "active agent without enforced limits" state that would bypass agent-limits.ts middleware entirely.

Idempotency is handled via unique-constraint detection: concurrent bootstraps for the same agent_id catch the Postgres 23505 violation, re-read from the database (not cache), re-apply lifecycle guards, verify limits exist, then return the existing profile with a fresh JWT.

The Numbers

• 4 human steps eliminated per agent onboarding
• 1 API call from first contact to governed worker
• 21 tests covering auth enforcement, idempotency, race conditions, and failure modes
• 3 OCC retries on tenant settings merge (prevents lost updates under concurrency)
• 1-hour JWT expiry with lifecycle enforcement on every request

Competitive Edge

No other AI gateway offers zero-human agent onboarding with built-in budget enforcement. Portkey requires manual key creation. OpenRouter has no agent identity concept. Letta has no budget governance. BrainstormRouter is the only platform where an agent can bootstrap itself, check its own budget, and monitor its own anomalies — all through a single authenticated API surface with full audit trail.

Lockstep Checklist

> _You MUST check these boxes [x] and verify the corresponding files are updated BEFORE committing this log._

• [x] API Routes: src/api/routes/agent-bootstrap.ts — 4 endpoints implemented and tested.
• [x] TS SDK: packages/sdk-ts/src/resources/agent-profiles.ts — bootstrap(), status(), limitsMe(), anomalyMe() + types exported.
• [x] Python SDK: packages/sdk-py/src/brainstormrouter/resources/agent_profiles.py — sync + async variants for all 4 methods.
• [x] MCP Schemas: src/mcp/server.ts — br_bootstrap_agent, br_agent_status, br_agent_limits, br_agent_anomaly registered.
• [x] Master Record: Capabilities reflected in site/.well-known/agents.json (agent_bootstrap, agent_self_awareness).