Boost Agent System: Folder & Class Upgrade

Nov 14, 2025 by Alex Johnson 43 views

Enhance Agent System: Folder Structure & Base Agent Upgrade

In this comprehensive guide, we'll dive deep into restructuring the foundation of our multi-agent support system. The goal? To create a more organized, scalable, and efficient architecture that can handle a growing number of agents and complex interactions. We'll start by addressing the need for a robust folder structure and then move on to enhancing our base agent classes. This will provide a solid framework for future development and improved performance.

The Core Challenge: Why a Refactor is Essential

Our current setup, while functional, is not optimized for the future. As we plan to expand to 243 agents across 17 swarms, the existing structure becomes a bottleneck. The core problem is that the original design of agents, base classes, and other supporting materials can not handle the complexity and quantity of the coming expansion. This refactoring is crucial for several key reasons:

Scalability: A well-defined folder structure is essential for scaling our system. It ensures that we can add new agents and features without causing chaos or breaking existing functionality.
Maintainability: The new structure will make it easier to find, understand, and modify code. This is critical for long-term maintenance and updates.
Collaboration: A clear structure promotes better collaboration among developers by providing a shared understanding of the codebase.
Efficiency: Enhanced base agent classes will streamline common tasks and reduce redundancy, making agents more efficient and improving overall performance.

From Basic to Advanced: The Target State

To address these challenges, we're transitioning from a basic, flat folder structure to a more sophisticated, tiered approach. The initial state of our project contains a src/agents/ folder and multiple files in this folder. With the implementation, we're looking to achieve a target state that includes a well-defined hierarchy with specific roles in place. The target state includes the following:

Base Agents: The core structure will be within the src/agents/base/ directory.
Tiered Domains: Folders for essential, revenue, operational, and advanced functionality will be included.
Modular Design: This design encourages a modular approach, where each component has a specific function and is independent of others.

Current State

src/agents/
├── base.py (basic BaseAgent)
├── router.py
├── billing.py
├── technical.py
├── usage.py
├── api.py
└── escalation.py

Target State

src/agents/
├── base/
│   ├── __init__.py
│   ├── base_agent.py (enhanced)
│   ├── agent_types.py (enums)
│   └── capabilities.py (mixins)
├── tier1_essential/
│   ├── routing/
│   ├── knowledge_base/
│   └── support/
├── tier2_revenue/
│   ├── sales/
│   ├── customer_success/
│   └── monetization/
├── tier3_operational/
└── tier4_advanced/

Step-by-Step: Implementing the New Folder Structure

Here's a detailed breakdown of the folder structure and implementation steps:

1. Complete Folder Structure

This is the complete view of the new folder structure. It includes a series of directories and files, designed to provide a comprehensive structure for managing agents and their respective tasks. Note that the structure is designed to be easily expandable, allowing you to add new agents and features as needed. This approach simplifies maintenance and promotes collaboration among developers.

multi-agent-support-system/
├── src/
│   ├── agents/
│   │   ├── base/
│   │   │   ├── __init__.py                     🆕 NEW
│   │   │   ├── base_agent.py                   ✏️ REFACTOR (from base.py)
│   │   │   ├── agent_types.py                  🆕 NEW (enums)
│   │   │   ├── capabilities.py                 🆕 NEW (mixins)
│   │   │   ├── decorators.py                   🆕 NEW
│   │   │   └── exceptions.py                   🆕 NEW
│   │   │
│   │   ├── tier1_essential/
│   │   │   ├── __init__.py                     🆕 NEW
│   │   │   │
│   │   │   ├── routing/
│   │   │   │   ├── __init__.py                 🆕 NEW
│   │   │   │   ├── meta_router.py              ✏️ REFACTOR (from router.py)
│   │   │   │   ├── support_router.py           🆕 NEW
│   │   │   │   ├── sales_router.py             🆕 NEW
│   │   │   │   ├── cs_router.py                🆕 NEW
│   │   │   │   ├── intent_classifier.py        🆕 NEW
│   │   │   │   ├── entity_extractor.py         🆕 NEW
│   │   │   │   ├── sentiment_analyzer.py       🆕 NEW
│   │   │   │   ├── complexity_assessor.py      🆕 NEW
│   │   │   │   ├── coordinator.py              🆕 NEW
│   │   │   │   ├── handoff_manager.py          🆕 NEW
│   │   │   │   ├── escalation_decider.py       🆕 NEW
│   │   │   │   └── context_injector.py         🆕 NEW
│   │   │   │
│   │   │   ├── knowledge_base/
│   │   │   │   ├── __init__.py                 🆕 NEW
│   │   │   │   ├── kb_searcher.py              🆕 NEW
│   │   │   │   ├── kb_ranker.py                🆕 NEW
│   │   │   │   ├── kb_synthesizer.py           🆕 NEW
│   │   │   │   ├── kb_feedback_tracker.py      🆕 NEW
│   │   │   │   ├── kb_gap_detector.py          🆕 NEW
│   │   │   │   ├── kb_suggester.py             🆕 NEW
│   │   │   │   ├── kb_updater.py               🆕 NEW
│   │   │   │   ├── kb_quality_checker.py       🆕 NEW
│   │   │   │   ├── faq_generator.py            🆕 NEW
│   │   │   │   └── kb_embedder.py              🆕 NEW
│   │   │   │
│   │   │   └── support/
│   │   │       ├── __init__.py                 🆕 NEW
│   │   │       │
│   │   │       ├── billing/
│   │   │       │   ├── __init__.py             🆕 NEW
│   │   │       │   ├── upgrade_specialist.py   ✏️ REFACTOR (from billing.py)
│   │   │       │   ├── downgrade_specialist.py 🆕 NEW
│   │   │       │   ├── refund_processor.py     🆕 NEW
│   │   │       │   ├── invoice_generator.py    🆕 NEW
│   │   │       │   ├── payment_troubleshooter.py 🆕 NEW
│   │   │       │   ├── pricing_explainer.py    🆕 NEW
│   │   │       │   └── discount_negotiator.py  🆕 NEW
│   │   │       │
│   │   │       ├── technical/
│   │   │       │   ├── __init__.py             🆕 NEW
│   │   │       │   ├── bug_triager.py          ✏️ REFACTOR
│   │   │       │   ├── crash_investigator.py   🆕 NEW
│   │   │       │   ├── sync_troubleshooter.py  🆕 NEW
│   │   │       │   ├── performance_optimizer.py 🆕 NEW
│   │   │       │   ├── login_specialist.py     🆕 NEW
│   │   │       │   ├── data_recovery_specialist.py 🆕 NEW
│   │   │       │   └── browser_compatibility_specialist.py 🆕 NEW
│   │   │       │
│   │   │       ├── usage/
│   │   │       │   ├── __init__.py             🆕 NEW
│   │   │       │   ├── onboarding_guide.py     ✏️ REFACTOR
│   │   │       │   ├── feature_teacher.py      🆕 NEW
│   │   │       │   ├── workflow_optimizer.py   🆕 NEW
│   │   │       │   ├── export_specialist.py    🆕 NEW
│   │   │       │   ├── import_specialist.py    🆕 NEW
│   │   │       │   └── collaboration_expert.py 🆕 NEW
│   │   │       │
│   │   │       ├── integration/
│   │   │       │   ├── __init__.py             🆕 NEW
│   │   │       │   ├── api_debugger.py         ✏️ REFACTOR
│   │   │       │   ├── webhook_troubleshooter.py 🆕 NEW
│   │   │       │   ├── oauth_specialist.py     🆕 NEW
│   │   │       │   ├── rate_limit_advisor.py   🆕 NEW
│   │   │       │   └── sdk_expert.py           🆕 NEW
│   │   │       │
│   │   │       └── account/
│   │   │           ├── __init__.py             🆕 NEW
│   │   │           ├── profile_manager.py      🆕 NEW
│   │   │           ├── team_manager.py         🆕 NEW
│   │   │           ├── notification_configurator.py 🆕 NEW
│   │   │           ├── security_advisor.py     🆕 NEW
│   │   │           ├── sso_specialist.py       🆕 NEW
│   │   │           ├── permission_manager.py   🆕 NEW
│   │   │           ├── data_export_specialist.py 🆕 NEW
│   │   │           ├── account_deletion_specialist.py 🆕 NEW
│   │   │           ├── compliance_specialist.py 🆕 NEW
│   │   │           └── audit_log_specialist.py 🆕 NEW
│   │   │
│   │   ├── tier2_revenue/                       🆕 NEW (placeholder for future)
│   │   ├── tier3_operational/                   🆕 NEW (placeholder)
│   │   └── tier4_advanced/                      🆕 NEW (placeholder)
│   │
│   ├── workflow/
│   │   ├── patterns/                            🆕 NEW
│   │   │   ├── __init__.py
│   │   │   ├── sequential.py                    🆕 NEW
│   │   │   ├── parallel.py                      🆕 NEW
│   │   │   ├── debate.py                        🆕 NEW
│   │   │   ├── verification.py                  🆕 NEW
│   │   │   └── expert_panel.py                  🆕 NEW
│   │   └── ...
│   │
│   └── services/
│       └── infrastructure/
│           └── agent_registry.py                 🆕 NEW (agent discovery)
│
├── tests/
│   ├── agents/
│   │   ├── tier1_essential/                     🆕 NEW
│   │   │   ├── routing/
│   │   │   ├── knowledge_base/
│   │   │   └── support/
│   │   └── ...
│   └── ...
│
└── docs/
    ├── issues/                                   🆕 NEW (this file!)
    │   ├── 001-infrastructure-database-schema.md
    │   └── 002-infrastructure-folder-structure.md
    └── agents/                                   🆕 NEW
        ├── tier1_essential/
        │   ├── routing.md
        │   ├── knowledge_base.md
        │   └── support.md
        └── ...

2. Key Implementation Steps

The implementation process involves creating new files, refactoring existing ones, and updating imports. This includes:

Enhanced BaseAgent Class: We'll enhance the BaseAgent class to include features like the ability to search a knowledge base, access enriched context, and collaborate with other agents.
Agent Types and Enums: Define AgentType and other relevant enums to represent different agent roles and domains.
Capabilities Mixins: Use mixins to add reusable capabilities to agents, such as knowledge base search and collaboration.
Agent Registry: Implement an AgentRegistry to enable dynamic agent discovery and instantiation.
Refactor Existing Agents: Migrate existing agents into the new structure, updating imports and ensuring all tests pass.

3. Complete Folder Structure Details

`src/agents/base/`

__init__.py: Marks the directory as a Python package.
base_agent.py: Contains the enhanced BaseAgent class.
agent_types.py: Defines enums for AgentType, Domain, SupportIntent, etc.
capabilities.py: Contains mixins for agent capabilities.
decorators.py: Place to create and store custom decorators.
exceptions.py: Store custom exception classes.

`src/agents/tier1_essential/`

__init__.py: Marks the directory as a Python package.
routing/: Contains routing-related agents.
- __init__.py: Marks the directory as a Python package.
- meta_router.py: Meta router agent.
- support_router.py: Router for support domain.
- sales_router.py: Router for sales domain.
- cs_router.py: Router for customer success domain.
- intent_classifier.py: Intent classifier agent.
- entity_extractor.py: Entity extractor agent.
- sentiment_analyzer.py: Sentiment analyzer agent.
- complexity_assessor.py: Complexity assessor agent.
- coordinator.py: Coordinator agent.
- handoff_manager.py: Handoff manager agent.
- escalation_decider.py: Escalation decider agent.
- context_injector.py: Context injector agent.
knowledge_base/: Contains knowledge base related agents.
- __init__.py: Marks the directory as a Python package.
- kb_searcher.py: Knowledge base searcher agent.
- kb_ranker.py: Knowledge base ranker agent.
- kb_synthesizer.py: Knowledge base synthesizer agent.
- kb_feedback_tracker.py: Knowledge base feedback tracker agent.
- kb_gap_detector.py: Knowledge base gap detector agent.
- kb_suggester.py: Knowledge base suggester agent.
- kb_updater.py: Knowledge base updater agent.
- kb_quality_checker.py: Knowledge base quality checker agent.
- faq_generator.py: FAQ generator agent.
- kb_embedder.py: Knowledge base embedder agent.
support/: Contains support related agents.
- __init__.py: Marks the directory as a Python package.
- billing/: Billing-related agents.
  - __init__.py: Marks the directory as a Python package.
  - upgrade_specialist.py: Upgrade specialist agent.
  - downgrade_specialist.py: Downgrade specialist agent.
  - refund_processor.py: Refund processor agent.
  - invoice_generator.py: Invoice generator agent.
  - payment_troubleshooter.py: Payment troubleshooter agent.
  - pricing_explainer.py: Pricing explainer agent.
  - discount_negotiator.py: Discount negotiator agent.
- technical/: Technical-related agents.
  - __init__.py: Marks the directory as a Python package.
  - bug_triager.py: Bug triager agent.
  - crash_investigator.py: Crash investigator agent.
  - sync_troubleshooter.py: Sync troubleshooter agent.
  - performance_optimizer.py: Performance optimizer agent.
  - login_specialist.py: Login specialist agent.
  - data_recovery_specialist.py: Data recovery specialist agent.
  - browser_compatibility_specialist.py: Browser compatibility specialist agent.
- usage/: Usage-related agents.
  - __init__.py: Marks the directory as a Python package.
  - onboarding_guide.py: Onboarding guide agent.
  - feature_teacher.py: Feature teacher agent.
  - workflow_optimizer.py: Workflow optimizer agent.
  - export_specialist.py: Export specialist agent.
  - import_specialist.py: Import specialist agent.
  - collaboration_expert.py: Collaboration expert agent.
- integration/: Integration-related agents.
  - __init__.py: Marks the directory as a Python package.
  - api_debugger.py: API debugger agent.
  - webhook_troubleshooter.py: Webhook troubleshooter agent.
  - oauth_specialist.py: OAuth specialist agent.
  - rate_limit_advisor.py: Rate limit advisor agent.
  - sdk_expert.py: SDK expert agent.
- account/: Account-related agents.
  - __init__.py: Marks the directory as a Python package.
  - profile_manager.py: Profile manager agent.
  - team_manager.py: Team manager agent.
  - notification_configurator.py: Notification configurator agent.
  - security_advisor.py: Security advisor agent.
  - sso_specialist.py: SSO specialist agent.
  - permission_manager.py: Permission manager agent.
  - data_export_specialist.py: Data export specialist agent.
  - account_deletion_specialist.py: Account deletion specialist agent.
  - compliance_specialist.py: Compliance specialist agent.
  - audit_log_specialist.py: Audit log specialist agent.

`src/agents/tier2_revenue/`

__init__.py: Marks the directory as a Python package. (Placeholder for future agents)

`src/agents/tier3_operational/`

__init__.py: Marks the directory as a Python package. (Placeholder for future agents)

`src/agents/tier4_advanced/`

__init__.py: Marks the directory as a Python package. (Placeholder for future agents)

`src/workflow/`

patterns/: Contains different workflow patterns.
- __init__.py: Marks the directory as a Python package.
- sequential.py: Sequential workflow pattern.
- parallel.py: Parallel workflow pattern.
- debate.py: Debate workflow pattern.
- verification.py: Verification workflow pattern.
- expert_panel.py: Expert panel workflow pattern.

`src/services/infrastructure/`

agent_registry.py: Agent registry for dynamic agent discovery.

4. Implementation Details

Step 1: Create Enhanced BaseAgent Class

The src/agents/base/base_agent.py file contains the enhanced BaseAgent class. This class includes essential methods for LLM calls, knowledge base searches, and context enrichment. It also features methods for updating agent state and determining when to escalate a conversation.

# [Code from the Implementation Details section]

Step 2: Create Agent Types & Enums

The src/agents/base/agent_types.py file defines enums for different agent types, domains, and intents. This provides a structured way to classify agents and manage their functionalities. The following enums are included:

# [Code from the Implementation Details section]

Step 3: Create Capabilities Mixins

The src/agents/base/capabilities.py file introduces mixins for agent capabilities. These mixins allow us to add functionalities like KB search and collaboration to agents easily. This approach promotes code reuse and modularity.

# [Code from the Implementation Details section]

Step 4: Create Agent Registry

The src/services/infrastructure/agent_registry.py file implements an AgentRegistry. This registry is essential for dynamic agent discovery and instantiation, allowing the system to manage and access agents efficiently. The registry uses a decorator pattern to register agents.

# [Code from the Implementation Details section]

Testing and Validation

Rigorous testing is a crucial part of this refactor. The testing requirements include:

Unit Tests: Writing comprehensive unit tests to ensure that each component functions as expected.
Integration Tests: Conducting integration tests to verify the interaction between different components.
End-to-End Tests: Performing end-to-end tests to validate the overall system behavior.

The test cases provided in the issue are:

# [Code from the Testing Requirements section]

Dependencies and Follow-up

This refactoring depends on a well-defined database schema and sets the stage for future developments, including the implementation of the Meta Router and Intent Classifier agents. Future tasks will focus on building upon this foundational structure.

Dependencies

#001: Database Schema (for context enrichment)

Follow-up Issues

#003: Implement Meta Router Agent
#004: Implement Intent Classifier

Conclusion

By implementing this new folder structure and enhancing the base agent classes, we're building a more robust, scalable, and maintainable system. This refactor lays the groundwork for future enhancements and ensures the long-term success of our multi-agent support system. With a clear architecture and solid foundation, we're well-equipped to support a growing number of agents and handle complex interactions with greater efficiency.

For more detailed information on agent-based systems, you can check out this resource:

Agent-Based Systems - Wikipedia