Registry-Based Agent Architecture

Overview

The ABS Platform now uses a registry-based architecture for agent implementation, which provides centralized business logic management, improved maintainability, and consistent patterns across all agents.

Architecture Pattern

Before: Monolithic Agents

Each agent file contained everything: - Business logic implementation - State management logic
- Event processing logic - Signal evaluation logic - Configuration data - Type definitions - Complex condition evaluators - Custom state update functions

Problems: - ❌ Code Duplication: Business logic scattered across multiple files - ❌ Inconsistent Patterns: Each agent had its own implementation style - ❌ Hard to Maintain: Changes required modifying multiple files - ❌ Large Files: ~200-300 lines per agent file - ❌ Poor Reusability: Logic tied to specific agent instances

After: Registry-Based Agents

Each agent file is minimal and focused: - Only imports from registry - Delegates all business logic to registry - Simple, consistent structure - No custom logic implementation

Benefits: - ✅ Centralized Logic: All business logic in one place - ✅ Consistent Interface: All agents use identical patterns - ✅ Easy Maintenance: Changes only need to be made in the registry - ✅ Small Files: ~60-70 lines per agent file - ✅ Reusable: Logic can be shared across multiple agent instances

Directory Structure

models/
├── battery-swap-service/
│   └── agent-pool/                    # Reusable agent implementations
│       ├── battery-swap-registry.ts   # Centralized business logic
│       ├── quota-agent.ts            # Minimal agent wrapper
│       ├── payment-agent.ts          # Minimal agent wrapper
│       ├── inventory-agent.ts        # Minimal agent wrapper
│       ├── subscription-agent.ts     # Minimal agent wrapper
│       ├── service-agent.ts          # Minimal agent wrapper
│       └── termsheet-agent.ts        # Minimal agent wrapper
└── templates/
    └── agent-pool/                   # Template agent implementations
        ├── template-registry.ts      # Template business logic
        ├── agent1.ts                # Minimal agent wrapper
        ├── agent2.ts                # Minimal agent wrapper
        └── README.md                # Documentation

Registry Pattern

Registry Structure

// Model-specific registry (e.g., battery-swap-registry.ts)
export interface ModelAgentLogic {
  process: (params: any, state: any, event: Event) => any;
  evaluateSignals: (params: any, state: any) => string[];
}

export const modelAgentRegistry: Record<string, ModelAgentLogic> = {
  'agent-name-v1': agentLogic,
  // ... more agents
};

export function getModelAgentLogic(logic: string): ModelAgentLogic {
  const agentLogic = modelAgentRegistry[logic];
  if (!agentLogic) {
    throw new Error(`Unknown agent logic: ${logic}`);
  }
  return agentLogic;
}

Agent Implementation

// Minimal agent file (e.g., quota-agent.ts)
import { getModelAgentLogic } from "./model-registry";

export const createAction: ActionFactory<AgentParams> = ({ params, deps }) => {
  const { name, ...agentParams } = params;

  // Get agent logic from registry
  const agentLogic = getModelAgentLogic('agent-name-v1');

  const fn = (event: Event, ctx: Ctx): ActionResult => {
    const currentState = ctx.state || AGENT_CONFIG.initial_state;

    // Process event using registry logic
    const newState = agentLogic.process(agentParams, currentState, event);

    // Evaluate signals using registry logic
    const signals = agentLogic.evaluateSignals(agentParams, newState);

    return {
      effects: signals,
      nextState: 'Processed',
      trace: [
        { rule: 'registry-process', pass: true },
        { rule: 'signal-evaluation', pass: signals.length > 0 }
      ],
      state: newState
    };
  };

  return fn;
};

Key Benefits

1. Single Source of Truth

• Before: Business logic was duplicated across 6 agent files
• After: All business logic is centralized in one registry file

2. Easier Maintenance

• Before: To change quota logic, you had to modify quota-agent.ts
• After: To change quota logic, you modify the registry (affects all quota agents)

3. Consistency

• Before: Each agent had its own implementation style
• After: All agents use identical patterns from the registry

4. Testing

• Before: Test business logic embedded in each agent
• After: Test business logic once in the registry

5. Reusability

• Before: Logic was tied to specific agent instances
• After: Logic can be reused across multiple agent instances

Real-World Analogy

Old Approach: Each restaurant has its own kitchen, recipes, and chefs New Approach: All restaurants use the same centralized kitchen and recipes, but each restaurant can still customize its menu and service style

The ActionFactory is still needed because each agent instance might have different parameters (like different quota limits, payment terms, etc.), but the core business logic is now shared and consistent.

Migration Path

For New Models:

1. Create agent-pool/ directory
2. Create [model]-registry.ts with centralized logic
3. Create minimal agent files that import from registry
4. Follow the established pattern

For Existing Models:

1. Extract business logic from agent files
2. Create centralized registry
3. Refactor agents to use registry
4. Remove old logic from agent files

Best Practices

1. Registry Location: Place registries in models/[model]/agent-pool/
2. Naming Convention: Use [model]-registry.ts for registry files
3. Agent Logic Interface: Keep consistent process and evaluateSignals methods
4. Type Safety: Use TypeScript interfaces for parameters and states
5. Documentation: Include README.md in agent-pool directories
6. Versioning: Use semantic versioning for agent logic (e.g., agent-v1, agent-v2)

Future Enhancements

• Cross-Model Registries: Share common logic across different models
• Dynamic Loading: Load agent logic dynamically based on configuration
• Plugin System: Allow third-party agent logic plugins
• Performance Optimization: Lazy loading of agent logic
• Validation: Runtime validation of agent logic compatibility