Breeze RMM AI Agent System Reference

Integrated AI agent allowing IT technicians to manage devices, troubleshoot issues, analyze security, and build automations through natural language chat.

Architecture Overview

 External Clients (Claude Desktop, Cursor)
          |  MCP over SSE/HTTP
          v
 +---------------------------+
 | Breeze MCP Server         |  /api/v1/mcp/*  (API Key auth)
 +---------------------------+
          |
 +------------------------------------------------------------------+
 |                     Hono API Server                               |
 |                                                                   |
 |  AI Chat Routes           MCP Server Routes                      |
 |  /api/v1/ai/*             /api/v1/mcp/*                          |
 |       |                        |                                  |
 |  +--------------------------------------------------+            |
 |  |         AI Agent Service (aiAgent.ts)             |            |
 |  |  Anthropic SDK + In-Process Tool Execution        |            |
 |  |                                                   |            |
 |  |  12 Custom Tools (aiTools.ts):                    |            |
 |  |   query_devices, get_device_details,              |            |
 |  |   execute_command, run_script, manage_alerts,     |            |
 |  |   security_scan, analyze_metrics,                 |            |
 |  |   manage_services, file_operations,               |            |
 |  |   create_automation, query_audit_log,             |            |
 |  |   network_discovery                               |            |
 |  +--------------------------------------------------+            |
 |       |                    |                    |                  |
 |  Existing Services    commandQueue.ts     Event Bus (Redis)       |
 +------------------------------------------------------------------+
          |                        |
    PostgreSQL              Go Agent (on devices)

File Map

Backend (API)

Frontend (Web)

Shared

Database Schema

5 tables in apps/api/src/db/schema/ai.ts:

Enums: ai_session_status (active/closed/expired), ai_message_role (user/assistant/system/tool_use/tool_result), ai_tool_status (pending/approved/executing/completed/failed/rejected)

API Routes

Chat Routes (/api/v1/ai/*)

MCP Server Routes (/api/v1/mcp/*)

Session ownership validated — each SSE session tracks apiKeyId. Max 100 sessions, 30-min TTL.

SSE Stream Events

Events emitted by POST /sessions/:id/messages:

type AiStreamEvent =
  | { type: 'message_start'; messageId: string }
  | { type: 'content_delta'; delta: string }
  | { type: 'tool_use_start'; toolName: string; toolUseId: string; input: Record<string, unknown> }
  | { type: 'tool_result'; toolUseId: string; output: unknown; isError: boolean }
  | { type: 'approval_required'; executionId: string; toolName: string; input: Record<string, unknown>; description: string }
  | { type: 'message_end'; inputTokens: number; outputTokens: number }
  | { type: 'error'; message: string }
  | { type: 'done' };

12 MCP Tools

Helper Functions in aiTools.ts

Guardrails (4-Tier System)

Defined in aiGuardrails.ts:

Action-based escalation: TIER3_ACTIONS maps tool+action combos that escalate (e.g., file_operations.write escalates from T1 to T3).

Approval Flow

1. AI invokes a Tier 3 tool
2. aiAgent.ts inserts aiToolExecutions record with status 'pending'
3. SSE emits approval_required event with tool name, input, description
4. Frontend shows AiApprovalDialog inline in chat
5. User clicks Approve/Reject -> POST /sessions/:id/approve/:executionId
6. waitForApproval() polls DB every 2s with circuit breaker (max 5 consecutive DB errors)
7. 5-minute auto-reject timeout
8. On approval: existing record updated to 'executing', tool runs, result returned

Cost Tracking

In aiCostTracker.ts:

Model pricing (cents per million tokens):

• claude-sonnet-4-5-20250929: 300 input / 1500 output
• claude-haiku-4-5-20251001: 100 input / 500 output

Page Context Injection

Frontend pushes context to aiStore.setPageContext():

type AiPageContext =
  | { type: 'device'; id: string; hostname: string; os?: string; status?: string; ip?: string }
  | { type: 'alert'; id: string; title: string; severity?: string; deviceHostname?: string }
  | { type: 'dashboard'; orgName?: string; deviceCount?: number; alertCount?: number }
  | { type: 'custom'; label: string; data: Record<string, unknown> };

Context is injected into the system prompt and sent with each message. The AiContextBadge component shows it visually in the chat header.

Data Flow: Chat Message

1. User types message in AiChatInput
2. aiStore.sendMessage(content)
   - Creates session if needed (POST /sessions)
   - Adds user message optimistically
   - POST /sessions/:id/messages with SSE stream
3. API receives message
   - checkAiRateLimit() — fail closed on Redis error
   - checkBudget() — fail closed on DB error
   - Insert user message to ai_messages
   - Build Anthropic messages array from conversation history
   - Call Anthropic API with tools + system prompt
4. Stream processing (generator function)
   - Yield message_start, content_delta events
   - On tool_use: check guardrails
     - Tier 1-2: execute immediately
     - Tier 3: insert execution record, yield approval_required, wait
     - Tier 4: return error
   - Yield tool_result events
   - On message_end: recordUsage() in transaction
   - Yield done
5. Frontend processes SSE events via processStreamEvent()
   - Updates Zustand store incrementally
   - Shows tool cards, approval dialogs, streaming text

Key Patterns & Safety

• Fail-closed: Rate limit and budget checks deny requests when Redis/DB is down
• Circuit breaker: waitForApproval breaks after 5 consecutive DB poll failures
• ILIKE escaping: escapeLike() helper prevents SQL wildcard injection in search
• Transaction wrapping: recordUsage uses db.transaction() for atomicity
• Session ownership: MCP SSE sessions track apiKeyId to prevent cross-session injection
• Polling circuit breaker: AiCostIndicator stops after 5 failures or auth errors
• Route ordering: /sessions/search registered before /sessions/:id in Hono
• No dual records: Approval flow updates existing execution record instead of creating a second one

Connecting External Clients

# Claude Desktop / Cursor MCP connection
claude mcp add breeze-rmm \
  --transport sse \
  --url https://your-api/api/v1/mcp/sse \
  --header "X-API-Key: brz_..."

API key needs ai:read, ai:write, or ai:execute scopes.