Swarm Management
This document covers the swarm management system in agent-swarm-kit, which orchestrates multiple agents, manages navigation between agents, and coordinates multi-agent workflows. Swarms serve as the primary orchestration layer that routes messages to the appropriate agents and maintains conversation state across agent transitions.
For information about individual agent execution and tool calling, see Client Agent. For session-level coordination and client isolation, see Session Management.
Core Swarm Architecture
A swarm is a collection of agents organized under a single orchestration unit that manages agent selection, navigation, and message routing. The ClientSwarm class implements the core swarm functionality, providing a unified interface for multi-agent coordination.
Swarm Component Structure
Swarm Schema and Configuration
Swarms are defined using the ISwarmSchema interface, which specifies the agent collection, default agent, and behavioral configuration:
Agent Navigation and Routing
The swarm manages navigation between agents through a navigation stack and active agent tracking. This allows for complex conversation flows where different agents handle different aspects of a conversation.
Navigation Stack Management
Agent Resolution and Error Handling
The swarm uses a NoopAgent fallback mechanism when requested agents are not found in the swarm configuration:
The NoopAgent class provides a safety mechanism that logs attempts to use non-existent agents while delegating operations to the default agent.
Active Agent Management
The swarm maintains an active agent that handles incoming messages and executes operations. Active agent management includes lazy initialization, memoization, and lifecycle tracking.
Active Agent Resolution
Message Flow and Output Handling
Swarms coordinate message flow between agents and manage output emission to external consumers through a subject-based event system.
Message Execution Flow
Output Subject Management
The ClientSwarm uses Subject patterns for asynchronous output handling and coordination:
Integration with Service Layer
Swarms integrate with the service architecture through connection services, validation services, and schema services to provide a complete orchestration platform.
Service Layer Integration
Persistence and State Management
Swarms support persistence of navigation state and active agent information:
Configuration and Lifecycle
Swarms are configured through schema definitions and managed through service lifecycle patterns including initialization, memoization, and disposal.
Swarm Lifecycle Management
Validation and Error Recovery
Swarms include validation mechanisms for agent availability and navigation consistency:
