The Builder's Guide

// orchestration-controller.tsx
// Each agent runs in its own isolated provider with its own SSE stream.
// The controller manages the DAG topology and data handoffs.

import { AgentUIProvider, useAgentUI } from '@agentui/react';

interface AgentNode {
  id: string;
  endpoint: string;
  dependsOn: string[];      // IDs of upstream agents
  status: 'pending' | 'running' | 'done' | 'error';
}

const pipeline: AgentNode[] = [
  { id: 'ingest',   endpoint: '/api/stream?agent=ingest',   dependsOn: [],                  status: 'running' },
  { id: 'analyze-a', endpoint: '/api/stream?agent=analyze-a', dependsOn: ['ingest'],          status: 'running' },
  { id: 'analyze-b', endpoint: '/api/stream?agent=analyze-b', dependsOn: ['ingest'],          status: 'pending' },
  { id: 'writer',   endpoint: '/api/stream?agent=writer',   dependsOn: ['analyze-a', 'analyze-b'], status: 'pending' },
];

function OrchestrationDashboard() {
  return (
    <div className="dag-dashboard">
      {pipeline.map(node => (
        <AgentUIProvider key={node.id} endpoint={node.endpoint}>
          <AgentNodeCard node={node} />
        </AgentUIProvider>
      ))}
    </div>
  );
}

function AgentNodeCard({ node }: { node: AgentNode }) {
  // Each card gets its own independent agent state
  const { agentState, sendCommand, intervene } = useAgentUI();
  
  const canRun = node.dependsOn.every(dep => 
    pipeline.find(n => n.id === dep)?.status === 'done'
  );

  return (
    <div className={`node-card ${node.status}`}>
      <h4>{node.id}</h4>
      <p>Status: {agentState.status}</p>
      <p>Tokens: {agentState.tokens.length}</p>
      
      {/* Independent controls per agent */}
      <button onClick={() => sendCommand('PAUSE')}>Pause</button>
      <button onClick={() => intervene({ 
        systemPrompt: 'Focus on key metrics only.' 
      })}>Redirect</button>
    </div>
  );
}

// Swap the backend of a failed agent at runtime
// This is the power of the Adapter pattern — the UI doesn't change at all.

async function handleAgentFailure(agentId: string, error: Error) {
  console.log(`Agent ${agentId} failed: ${error.message}`);

  // 1. The operator clicks "Swap to Anthropic" in the UI
  //    This triggers an intervention on the agent's session:
  await fetch('/api/stream/intervention', {
    method: 'POST',
    body: JSON.stringify({
      action: 'swap_adapter',
      payload: {
        agentId,
        newAdapter: 'anthropic',
        model: 'claude-sonnet-4-20250514',
        // Carry over the accumulated context
        preserveContext: true,
      }
    })
  });
}

// Server-side handler in your custom adapter:
class OrchestrationAdapter extends BaseAgentAdapter {
  async handleIntervention(ctx: SessionContext, action: string, payload: any) {
    if (action === 'swap_adapter') {
      // Disconnect the failed adapter
      await this.adapters[payload.agentId].disconnect(ctx);
      
      // Hot-swap to a new backend
      this.adapters[payload.agentId] = createAdapter(payload.newAdapter, {
        model: payload.model,
      });
      
      // Reconnect and resume — the UI sees a seamless recovery
      await this.adapters[payload.agentId].connect(ctx);
      this.emitEvent(ctx, {
        type: 'state_change',
        payload: { status: 'running', swappedTo: payload.newAdapter }
      });
    }
  }
}

// mission-control.tsx
// Aggregate state from all agent sessions into a unified dashboard.

import { AgentUIProvider, useAgentUI } from '@agentui/react';
import { useState, useEffect, createContext, useContext } from 'react';

interface FleetMetrics {
  totalTokens: number;
  activeCount: number;
  pausedCount: number;
  errorCount: number;
  agents: AgentSummary[];
}

const FleetContext = createContext<FleetMetrics>(null!);

function MissionControl({ agents }: { agents: AgentConfig[] }) {
  const [fleet, setFleet] = useState<FleetMetrics>({
    totalTokens: 0, activeCount: 0, pausedCount: 0, errorCount: 0, agents: [],
  });

  return (
    <FleetContext.Provider value={fleet}>
      <FleetDashboard />
      
      {/* Each agent runs in isolation but reports to the fleet */}
      {agents.map(agent => (
        <AgentUIProvider key={agent.id} endpoint={agent.endpoint}>
          <AgentReporter 
            agentId={agent.id} 
            onStateChange={(summary) => {
              setFleet(prev => ({
                ...prev,
                totalTokens: prev.agents.reduce((sum, a) => sum + a.tokens, 0),
                activeCount: prev.agents.filter(a => a.status === 'running').length,
                agents: prev.agents.map(a => a.id === agent.id ? summary : a),
              }));
            }}
          />
        </AgentUIProvider>
      ))}
    </FleetContext.Provider>
  );
}

// Invisible component — just reports state upward
function AgentReporter({ agentId, onStateChange }) {
  const { agentState } = useAgentUI();
  
  useEffect(() => {
    onStateChange({
      id: agentId,
      status: agentState.status,
      tokens: agentState.tokens.length,
    });
  }, [agentState]);

  return null; // No UI — just a state bridge
}

// ── Global Emergency Controls ───────────────
function EmergencyPanel() {
  const fleet = useContext(FleetContext);
  
  const pauseAll = async () => {
    for (const agent of fleet.agents) {
      await fetch(`/api/stream/intervention?agent=${agent.id}`, {
        method: 'POST',
        body: JSON.stringify({ action: 'command', payload: { cmd: 'PAUSE' } })
      });
    }
  };

  return (
    <div className="emergency-panel">
      <button onClick={pauseAll} className="emergency-btn">
        🚨 PAUSE ALL AGENTS
      </button>
      <span>{fleet.activeCount} agents will be paused</span>
    </div>
  );
}

// Governance layer — wraps any adapter with budget controls
class GovernedAdapter extends BaseAgentAdapter {
  private tokenBudgets: Map<string, { used: number; limit: number }> = new Map();

  async connect(ctx: SessionContext) {
    // Initialize budget for this session
    this.tokenBudgets.set(ctx.sessionId, { used: 0, limit: 50000 });
    await this.innerAdapter.connect(ctx);

    // Intercept token events to track usage
    this.innerAdapter.onEvent(ctx, (event) => {
      if (event.type === 'token') {
        const budget = this.tokenBudgets.get(ctx.sessionId)!;
        budget.used += event.payload.length;

        // Auto-warn at 80%
        if (budget.used > budget.limit * 0.8) {
          this.emitEvent(ctx, {
            type: 'state_change',
            payload: { warning: 'budget_threshold', usage: budget.used / budget.limit }
          });
        }

        // Auto-pause at 100%
        if (budget.used >= budget.limit) {
          this.handleIntervention(ctx, 'command', { cmd: 'PAUSE' });
          this.emitEvent(ctx, {
            type: 'state_change',
            payload: { 
              status: 'paused',
              reason: 'Token budget exhausted',
              used: budget.used,
              limit: budget.limit
            }
          });
        }
      }

      // Forward to UI
      this.emitEvent(ctx, event);
    });
  }
}