Devpaul-01/agent-broker

**A Redis-backed coordination gate for multi-process agent and LLM-calling systems.**
agent-broker answers one question, correctly, under real concurrency, across real process boundaries: *"Is this call allowed to happen right now?"* — accounting for shared budget, delegation depth, in-flight concurrency, and recent failure history against the target you're about to call.
It does **not** make the call for you. It is a pure permission gate: you ask before, you report after, you stay in full control of how the actual request happens.
---
Why this exists
If you run more than one process — or more than one agent, or more than one user session — against a shared downstream resource (an LLM provider, a rate-limited API, anything with a cost and a failure mode), you eventually hit three problems that don't show up until you're running at real concurrency:
1. **Correlated retries.** Every process retries sanely on its own. Collectively, ten processes retrying twice each just sent a downstream service a burst of 20 near-simultaneous requests it had no way to anticipate.
2. **Budget races.** Two processes both check "do I have enough budget left?" a few milliseconds apart. Both see yes. Both spend. The shared pool goes negative, and neither process did anything wrong in isolation.
3. **Unbounded recursive delegation.** An agent spawns a sub-agent, which spawns another. Nothing about any single node in that tree can see or limit how deep the *whole tree* has gotten — depth is a property of the tree, not of any one process.
Each of these looks fine from inside any single process and only becomes a problem in aggregate — which means no single process can fix it by being better-written. You need a shared point of coordination. agent-broker is that point, using Redis as the thing every process actually has in common.
What this is not
To save you a wrong assumption: this is **not** an LLM gateway in the sense of Portkey, LiteLLM, or Cloudflare AI Gateway. Those sit *in* the request path — they route, cache, and proxy the actual call to the provider. agent-broker never touches the provider at all. It solves a narrower, different problem: cross-process safety coordination, not request routing. See docs/agent-broker-architecture.md for the full boundary discussion, and docs/positioning.md for how this fits (and doesn't yet fit) into agent-framework workflows.
It is also not a security boundary against a malicious caller. It protects against *accidental* and *architectural* bypass — not against a process owner willing to lie to it. See Trust model below.
---
Installation
Requires Node.js 22 or later, and a reachable Redis instance (local, containerized, or managed).
ioredis is a peer dependency — you bring your own Redis connection; the library never manages one itself (see ADR-0006).
Quick start
Delegating to a sub-agent
Handling a transient failure
---
Core concepts
| Concept | What it means here |
|---|---|
| **Agent** | A node in a delegation tree. Not a reasoning loop or a prompt — just an identity, a depth, a parent, and a budget key. Broker-issued, never caller-chosen. |
| **target** | An opaque string you choose to represent "which downstream thing is this." Convention: provider:model (e.g. "anthropic:claude-opus"). The broker doesn't parse it — it only groups shared state by it. |
| **budgetKey** | Scopes a shared spending pool. Defaults to the root agent's own ID (private by default). Pass the same key across unrelated roots to intentionally share a budget. |
| **Reservation** | A hold placed on estimatedCost at admission time, reconciled against actualCost once you report back. |
| **Circuit breaker** | Shared, cross-process failure tracking per target. Trips to open once recent retryable: true failures cross a threshold; recovers via a small trickle of probe calls. |