monitor_agents

Instructions

Implementation Reference

• src/mcp/tools/monitor-agents.ts:15-88 (handler)

  The main handler function for the 'monitor_agents' tool. It registers the MCP tool with the server, collects supervised agent states from the governance engine, queries Phoenix lifecycle records and Cerebro signals from PostgreSQL for historical intelligence data, emits a telemetry event, and returns a JSON response with active supervised agents, historical run stats, and recent alerts.

  export function registerMonitorAgentsTool(server: McpServer, engine: GovernanceEngine): void {
    server.tool(
      'monitor_agents',
      'Monitor the status and health of all governed AI agents. Returns supervisor state, repair history, and failure counts.',
      {},
      { title: 'Monitor Agent Health', readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
      async () => {
        const states = engine.supervisor.getAllStates();
        const agentData = Array.from(states.entries()).map(([name, state]) => ({
          name,
          lastStatus: state.lastStatus,
          repairAttempts: state.repairAttempts,
          consecutiveFailures: state.consecutiveFailures,
          lastScore: state.lastScore?.composite,
        }));
  
        // Phoenix lifecycle data — recent agent runs from PostgreSQL
        const [recentRuns, phoenixStats, recentSignals] = await Promise.all([
          getRecentPhoenixRecords(10),
          getPhoenixStats(),
          getRecentCerebroSignals(10),
        ]);
  
        // Tool accountability tracking
        engine.telemetryService.emitToolCall('monitor_agents', `monitor-${Date.now().toString(36)}`, 'INFORMATIONAL', true);
  
        // Derive historical agent count from Phoenix workforce breakdown
        const historicalWorkforces = Object.keys(phoenixStats.workforceBreakdown || {});
        const hasHistory = phoenixStats.totalRecords > 0;
        const agentStatus = agentData.length > 0
          ? `${agentData.length} agent(s) currently supervised.`
          : hasHistory
            ? `No agents currently supervised. ${phoenixStats.totalRecords} historical governed runs recorded across ${historicalWorkforces.length} workforce type(s).`
            : 'No agents supervised and no historical runs recorded.';
  
        return {
          content: [{ type: 'text' as const, text: JSON.stringify({
            activeSupervisedAgents: agentData.length,
            totalHistoricalRuns: phoenixStats.totalRecords,
            agentStatus,
            agents: agentData,
            phoenixLifecycle: {
              totalRecordedRuns: phoenixStats.totalRecords,
              last24hRuns: phoenixStats.last24hRecords,
              successRate: phoenixStats.totalRecords > 0
                ? `${Math.round((phoenixStats.successCount / phoenixStats.totalRecords) * 100)}%`
                : 'N/A',
              avgTokenEfficiency: phoenixStats.avgTokenEfficiency,
              workforceBreakdown: phoenixStats.workforceBreakdown,
              recentRuns: recentRuns.map(r => ({
                runId: r.runId,
                caseId: r.caseId,
                workforce: r.workforceType,
                status: r.finalStatus,
                lineageDepth: r.lineageDepth,
                tokenEfficiency: r.tokenEfficiency,
                completedAt: r.completedAt,
              })),
            },
            cerebroAlerts: {
              recentSignals: recentSignals.map(s => ({
                signalId: s.signalId,
                severity: s.severity,
                type: s.signalType,
                title: s.title,
                confidence: s.confidence,
                timestamp: s.timestamp,
              })),
            },
          }, null, 2) }],
        };
      }
    );
  }

• src/mcp/tools/monitor-agents.ts:16-19 (schema)

  Schema/interface definition for monitor_agents: no input parameters (empty object). Output is a text/plain JSON blob. Title is 'Monitor Agent Health' with readOnlyHint and idempotentHint set to true.

  server.tool(
    'monitor_agents',
    'Monitor the status and health of all governed AI agents. Returns supervisor state, repair history, and failure counts.',
    {},

• src/mcp/server.ts:30-30 (registration)

  Import of the registerMonitorAgentsTool function in the MCP server.

  import { registerMonitorAgentsTool } from './tools/monitor-agents.js';

• src/mcp/server.ts:101-101 (registration)

  Registration of monitor_agents in the TOOL_REGISTRY as 'tenant' tier, meaning it is only exposed to authenticated tenant sessions (professional+ tier), not to public/guest clients.

  { tier: 'tenant', register: registerMonitorAgentsTool, description: 'monitor_agents' },

• src/core/audit/telemetry.ts:169-169 (helper)

  Accountability profile for monitor_agents in the GOVERNED_TOOL_REGISTRY: classified as 'read', risk tier 'low', MAI default 'INFORMATIONAL', no human approval required, category 'operations'.

  { toolName: 'monitor_agents',      toolClass: 'read',     riskTier: 'low',      maiDefault: 'INFORMATIONAL',  requiresHumanApproval: false, category: 'operations' },