Enterprise Operations

Scale from a single agent to hundreds across teams with bulk registration, credential rotation, deployment snapshots, and fleet-wide observability.

Agent lifecycle

Register → Deploy → Monitor → Rotate → Update → Retire
    │         │        │         │         │        │
    ▼         ▼        ▼         ▼         ▼        ▼
 POST      set      stats/     update    set      set
/agents  deployment  events   credentials deployment deployment
                                           version   status=retired

Bulk registration

Register multiple agents in a single operation:

import { bulkRegisterAgents } from "@keeptrusts/agent";

const agents = await bulkRegisterAgents({
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN!,
  apiUrl: process.env.KEEPTRUSTS_API_URL!,
  agents: [
    { name: "compliance-reviewer", description: "Reviews policy compliance" },
    { name: "cost-optimizer", description: "Monitors and optimizes spend" },
    { name: "incident-responder", description: "Handles escalation triage" },
    { name: "knowledge-indexer", description: "Indexes knowledge base assets" },
  ],
});

for (const agent of agents) {
  console.log(`${agent.name}: ${agent.id}`);
}

Fleet management

List all agents

import { listAgents } from "@keeptrusts/agent";

const fleet = await listAgents({
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN!,
  apiUrl: process.env.KEEPTRUSTS_API_URL!,
});

for (const agent of fleet) {
  console.log(`${agent.name} (${agent.id}) — ${agent.deployment?.status ?? "undeployed"}`);
}

Filter by deployment status

const active = await listAgents({
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN!,
  apiUrl: process.env.KEEPTRUSTS_API_URL!,
  status: "active",
});

Agent detail

import { getAgent } from "@keeptrusts/agent";

const agent = await getAgent({
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN!,
  apiUrl: process.env.KEEPTRUSTS_API_URL!,
  agentId: "agt_abc123",
});

console.log(agent.name);
console.log(agent.deployment);
console.log(agent.gateways);
console.log(agent.created_at);

Deployment management

Deployment snapshots

Every deployment change is recorded as a snapshot:

const agent = createAgentRuntime({ /* ... */ });

// Deploy a new version
await agent.setDeployment({
  status: "active",
  version: "2.1.0",
  metadata: {
    environment: "production",
    region: "us-east-1",
    commit: "abc123f",
  },
});

// List deployment history
const snapshots = await agent.listSnapshots();
for (const snap of snapshots) {
  console.log(`${snap.version} — ${snap.status} at ${snap.deployed_at}`);
  console.log(`  Metadata: ${JSON.stringify(snap.metadata)}`);
}

Canary deployments

Roll out a new agent version incrementally:

// Step 1: Deploy to canary gateway
await agent.setDeployment({
  status: "canary",
  version: "2.2.0-rc1",
  metadata: { environment: "canary", traffic_percent: 5 },
});

await agent.addGateway("gateway-canary");

// Step 2: Monitor for issues
const stats = await agent.getStats();
if (stats.policy_blocks === 0 && stats.escalations === 0) {
  // Step 3: Promote to production
  await agent.setDeployment({
    status: "active",
    version: "2.2.0",
    metadata: { environment: "production" },
  });
  await agent.addGateway("gateway-prod-us-east");
  await agent.removeGateway("gateway-canary");
}

Rollback

// Get the last known-good snapshot
const snapshots = await agent.listSnapshots();
const lastGood = snapshots.find(s => s.status === "active" && s.version !== "2.2.0");

if (lastGood) {
  await agent.setDeployment({
    status: "active",
    version: lastGood.version,
    metadata: { ...lastGood.metadata, rollback_from: "2.2.0" },
  });
}

Credential rotation

Rotate credentials without agent downtime:

// Step 1: Generate new credentials (console or API)
const newAccessKey = "kt-new-rotated-key";
const newBearerToken = "new-rotated-bearer";

// Step 2: Update the running agent
agent.updateCredentials({
  accessKey: newAccessKey,
  bearerToken: newBearerToken,
});

// Step 3: Verify the agent still works
const result = await agent.chat({
  model: "gpt-5.4-mini-mini",
  messages: [{ role: "user", content: "Health check." }],
});

// Step 4: Revoke old credentials (console or API)

Automated rotation schedule

import { rotateAccessKey } from "@keeptrusts/agent";

// Rotate every 30 days
async function scheduledRotation() {
  const { newKey, expiresAt } = await rotateAccessKey({
    bearerToken: process.env.KEEPTRUSTS_API_TOKEN!,
    apiUrl: process.env.KEEPTRUSTS_API_URL!,
    agentId: "agt_abc123",
    ttlDays: 30,
  });

  // Store new key in your secrets manager
  await secretsManager.put("KEEPTRUSTS_API_TOKEN", newKey);

  // Update running agent
  agent.updateCredentials({ accessKey: newKey });

  console.log(`Rotated. New key expires: ${expiresAt}`);
}

Gateway linking

Multi-gateway agents

Link a single agent to multiple gateways for geographic distribution:

await agent.addGateway("gateway-prod-us-east");
await agent.addGateway("gateway-prod-eu-west");
await agent.addGateway("gateway-prod-ap-southeast");

const gateways = await agent.listGateways();
console.log(`Agent linked to ${gateways.length} gateways`);

Targeted gateway removal

// Remove from staging during production rollout
await agent.removeGateway("gateway-staging");

Fleet-wide observability

Aggregate stats across agents

const fleet = await listAgents({
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN!,
  apiUrl: process.env.KEEPTRUSTS_API_URL!,
  status: "active",
});

let totalCost = 0;
let totalBlocks = 0;

for (const agentInfo of fleet) {
  const runtime = createAgentRuntime({
    agentId: agentInfo.id,
    // ...shared config
  });
  const stats = await runtime.getStats();
  totalCost += parseFloat(stats.total_cost);
  totalBlocks += stats.policy_blocks;
}

console.log(`Fleet total cost: $${totalCost.toFixed(2)}`);
console.log(`Fleet policy blocks: ${totalBlocks}`);

Fleet health check

async function fleetHealthCheck() {
  const fleet = await listAgents({ /* ... */ status: "active" });
  const unhealthy: string[] = [];

  for (const agentInfo of fleet) {
    const runtime = createAgentRuntime({ agentId: agentInfo.id, /* ... */ });
    const stats = await runtime.getStats();

    // Flag agents with high block rates
    if (stats.total_requests > 0) {
      const blockRate = stats.policy_blocks / stats.total_requests;
      if (blockRate > 0.1) {
        unhealthy.push(`${agentInfo.name}: ${(blockRate * 100).toFixed(1)}% block rate`);
      }
    }
  }

  if (unhealthy.length > 0) {
    await alertOps(`Unhealthy agents:\n${unhealthy.join("\n")}`);
  }
}

Retirement

Gracefully retire an agent:

// Step 1: Stop routing traffic
await agent.removeGateway("gateway-prod-us-east");
await agent.removeGateway("gateway-prod-eu-west");

// Step 2: Mark as retired
await agent.setDeployment({
  status: "retired",
  version: agent.deployment.version,
  metadata: { retired_reason: "Replaced by v3 architecture", retired_by: "ops-team" },
});

// Step 3: Collect final evidence
const finalBundle = await agent.createEvidenceBundle({
  startTime: agent.created_at,
  endTime: new Date().toISOString(),
});

Retired agents retain their event history and trail records indefinitely for compliance purposes.

Team-scoped agents

Assign agents to teams for organizational boundaries:

const agent = await registerAgent({
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN!,
  apiUrl: process.env.KEEPTRUSTS_API_URL!,
  name: "team-alpha-reviewer",
  description: "Code review agent for Team Alpha",
  teamId: "team_alpha",
});

Team-scoped agents:

• Inherit the team's wallet for cost attribution
• Are visible only to team members in the console
• Follow the user → team → org wallet cascade for spend