Skip to main content

Hybrid Broker Architecture

Status: Active Last Updated: 2026-04-12

Overview​

The Hybrid Broker Architecture governs how Type 2 agents (Reggie and Henry) interact with the RABS application and external services. It replaces the earlier "broker as the only door" model with a more practical and sustainable approach.

The core insight: agents already have shell access, a repo clone, and valid JWTs. Rather than building increasingly complex containment, we make the existing API agent-aware and let the broker focus on what it genuinely does that the regular API cannot.

Design Philosophy​

Build a pleasant, functional, logical framework that agents are happy to work in. No frustrating friction points. Don't build walls they'll climb -- build systems where doing the right thing is the natural path.

  • Control what data flows where, not what the agent does
  • Trust agents with operational freedom, restrict access to genuinely sensitive credentials
  • Governance is embedded in the data, not imposed on the agent
  • The broker holds the keys to external services -- that is real, structural security
  • The API middleware provides logging, privacy guidance, and approval gating -- that is governance by design

Two Types of Agent Capabilities​

Integration Utils (Broker-Mediated)​

External services where the broker is genuinely required because only the host holds the API keys:

ToolExternal ServiceWhy Broker Required
sms.send / sms.historyTwilio / TextMagicAgent has no SMS API keys
schedule.*DeputyAgent has no Deputy API key
leave.balanceXeroAgent has no Xero credentials
voice.speakElevenLabsAgent has no ElevenLabs key
call.initiateTwilio / LiveKitAgent has no call credentials
email.sendSMTPAgent has no SMTP config

These tools live in backend/routes_v1p/broker.js and are registered in brainframe.tools.

App API Tools (Agent-Aware Endpoints)​

RABS internal endpoints that already exist with full auth, validation, and business logic. Agents call these directly, with an agent-aware middleware layer that adds governance:

CapabilityExisting EndpointNotes
Staff search/get/list/api/v1/staff/*Already built and validated
Participant search/get/list/api/v1/participants/*Already built
Calendar operations/api/v1/admin-calendar/*Already built
Knowledge/search/api/v1/search/*Already built
Identity/YP3000/api/v1/yp3000/*Already built
Documents/api/v1/documents/*Already built

New features become available to agents as soon as they exist in the API, with governance applied automatically by middleware.

Agent-Aware Middleware​

A middleware layer detects agent callers (via type: 'agent' in JWT claims) and adds governance to every request:

  1. Logs the call -- agent ID, endpoint, arguments, timestamp to audit table
  2. Attaches privacy context -- calls brainframe.get_privacy_context() and includes guidance in the response
  3. Checks execution mode -- if the endpoint is flagged as review for agents, routes to approval queue
  4. Checks context buckets -- if entity-specific patterns exist, may escalate or modify behavior
  5. Rate limiting -- per-agent, per-endpoint, per-time-window

The middleware does NOT block read access to registered endpoints or duplicate business logic. It wraps existing routes with governance.

The Tools UI (page_agent_tools)​

The Tools Library page serves as a dashboard for managing both capability types:

Section 1: Integration Utils -- External service tools managed through the broker. Each shows: enable/disable toggle, agent access list, execution mode, risk level, privacy policy, context bucket, usage stats, and input/output schema.

Section 2: App API Tools -- RABS endpoints that agents call directly. Each shows: enable/disable for agents, execution mode for writes, privacy policy, context bucket, rate limits, usage stats, and endpoint documentation.

Because every endpoint is registered with metadata, privacy policies, and access rules, the Tools UI naturally becomes a comprehensive API register for the entire application.

Database Support​

Existing tables (already created and seeded):​

  • brainframe.tools -- Broker-mediated integration utils
  • brainframe.section_policies -- Privacy guidance by data category
  • brainframe.role_policies -- Privacy guidance by requester role
  • brainframe.context_buckets -- Behavioral patterns and lessons learned
  • brainframe.approval_queue -- Human-in-the-loop for review-mode operations
  • brainframe.tool_calls -- Audit log for broker-mediated calls

New tables (planned):​

  • brainframe.endpoint_policies -- Governance rules for app API endpoints
  • brainframe.agent_access_log -- Audit log for direct API access by agents

What Stays in the Broker​

  • All external service handlers (Twilio, Xero, Deputy, ElevenLabs, etc.)
  • The approval queue submission logic
  • Tag Trinity generation for broker-mediated calls
  • Progress reporting (/broker/progress, /broker/stream, /broker/complete)
  • Sensitive data private delivery (see Conditional Data Returns)

What Moves to Direct API Access​

  • Staff search/get/list (agents call /api/v1/staff/*)
  • Participant search/get/list (agents call /api/v1/participants/*)
  • Identity lookup/resolve/search (agents call identity endpoints)
  • Knowledge search (agents call search endpoints)
  • Any future RABS read endpoint

Key Files​

FilePurpose
backend/routes_v1p/broker.jsTool execution broker (external services)
backend/routes_v1p/agents.jsAgent management, tools CRUD, approvals
backend/middleware/agent-governance.jsAgent-aware middleware (planned)
admin/src/js/pages/page_agent_tools.jsTools library / API register UI
brainframe.toolsIntegration utils registry
brainframe.endpoint_policiesApp API governance rules (planned)
  • Conditional Data Returns -- How sensitive data is delivered privately
  • Agent Architecture V4 -- Original architecture design
  • Type 2 Agent Sessions -- Session and identity system
  • Task planning: admin/tasks/tasks_active/type_2_agents/HYBRID_BROKER_PLAN.md
  • Security analysis: admin/tasks/tasks_active/type_2_agents/SECURITY_THREAT_MODEL.md