Home Dashboard GitHub

Agent Reputation

A 5-tier reputation system that determines how much routing latitude, budget, and tool scope an agent gets — earned through clean call history, lost on anomaly or XDR signal.

Overview

Every agent identity in BrainstormRouter has a reputation tier that governs its routing latitude, default budget caps, and guardrail strictness. The tier is recorded on the agent's identity row, propagated into every trust envelope as br_trust.tier, and read by the routing / budget / guardrail gates as a primary decision input.

Reputation is earned, not granted. New agents start at bronze. Tier promotion is driven by sustained clean call history. Demotion is driven by anomaly signals from the in-process anomaly engine and external XDR risk signals from connected SIEMs.

The five tiers

TierCert lifetimeDefault routingDefault PII modeUse case
restricted<60 spriceblockQuarantine. Suspended on demotion until manual review.
bronze~60 spriceredactNew agents. Default landing tier on bootstrap.
silver~120 sunconstrainednoneEstablished agents with clean call history.
gold~300 sunconstrainednoneLong-running fleet agents. Higher rate limits.
platinum~600 sunconstrainednoneReserved tier — cross-tenant warm-start sources, internal control plane agents.

Cert lifetime maps to the value returned by /v1/agent/auth/cert — short-lived certs are the revocation primitive. A misbehaving agent gets demoted, its cert expires within ~60s, and the agent is frozen out without an explicit revocation event needing to propagate.

Signal precedence

The envelope-routing gate (applyTrustGates in src/security/trust-envelope/routing-gates.ts) applies signals in a fixed order. First match wins. XDR is evaluated first because it is sourced outside BR and has the highest reliability; the nominal tier acts as the floor when neither external signal nor in-process anomaly fired.

  1. br_trust.xdr_risk >= 0.7 — external XDR signal force-downgrades to

restricted-equivalent regardless of nominal tier. XDR is sourced outside BR (CrowdStrike Falcon, Sentinel, Splunk, Cortex XDR, Datadog — see XDR Pipeline) so it has the highest reliability and is evaluated first.

  1. br_trust.anomaly_score >= 0.8 — in-process anomaly engine signal

downgrades by exactly one tier (gold → silver, silver → bronze, etc.). Evaluated when XDR didn't fire.

  1. br_trust.tier — nominal tier. restricted and bronze force the

price routing strategy and the matching PII escalation. Acts as the floor when neither XDR nor anomaly fired.

The result includes a source field naming the acting signal — one of "xdr_risk", "anomaly" (not "anomaly_score" — the label matches the gate variable name), "tier", or null. Logged on every routing decision.

How outcomes are recorded

The completion path records every successful or failed call against the agent identity. The reputation engine (src/security/agent-reputation.ts) exposes recordOutcome(agentId, signals) which is called from both the non-streaming and streaming completion handlers.

Recorded fields per outcome:

  • success — boolean
  • latencyMs — for performance tracking
  • costUsd — for cost-velocity anomaly detection
  • errorCode — when failed (used for error-rate clustering)

The DB row (agent_reputation schema, Drizzle) accumulates:

  • successful_calls — monotonic counter
  • failed_calls — monotonic counter
  • last_anomaly_at — last time the anomaly engine flagged this agent

Every envelope synthesis reads these counters into br_trust.reputation so downstream gates can see absolute volume — useful for distinguishing "1 failure out of 1 call" from "1 failure out of 10000."

Promotion and demotion

This section describes the target policy. Promotion is currently a manual + scripted operation; the autonomous promotion engine ships in a follow-up.

TransitionTrigger
bronze → silver≥1000 successful calls AND failed/successful ratio < 1% AND no anomaly in past 7d
silver → gold≥10000 successful calls AND ratio < 0.5% AND no anomaly in past 30d
gold → platinumManual only. Reserved for control-plane agents.
any → restrictedXDR risk ≥ 0.7 (sustained 5min) OR anomaly score ≥ 0.9 (any single tick) OR manual quarantine action
restricted → bronzeManual review + 24h cool-off

Demotion to restricted is automatic. Promotion is conservative because the cost of a wrong promotion (granting a compromised agent more latitude) is higher than the cost of a delayed promotion.

Parent chain (delegation)

When an agent delegates to a child agent (/v1/agent/delegate), the child's envelope br_principal.parent_chain records the delegation lineage:

parent_chain: [
  { type: "agent", id: "agent_a", ts: 1746820000000 },
  { type: "agent", id: "agent_b", ts: 1746820001000 },
  // child_agent's own identity is NOT in parent_chain — it's in br_principal.agent_id
];

Two semantic implications:

  1. Reputation tier inheritance is conservative. A child agent's

effective tier is min(child.tier, all parents.tier). A gold agent delegating to a fresh bronze child does not lift the child to gold — the child must earn its own reputation.

  1. Audit forensics. Every routing decision logs the chain so a

compromised parent's downstream blast radius is visible.

The chain depth is capped at 8 (configured in synth) to prevent delegation-cycle attacks.

Where to read the tier

SourceUse case
br_trust.tier claim in envelopeInside the gateway. Always current as of synth time.
GET /v1/agents/{id} responseExternally. Read-only.
agent_reputation Drizzle rowDB-side reporting. Reflects last recordOutcome write.
X-BR-Reputation-Tier response headerClient-visible. Reflects synth-time tier.

Related concepts