Building Multi-Agent Systems

This document provides a comprehensive guide to defining agents, swarms, and orchestrating multi-agent workflows using the agent-swarm-kit framework. It covers the step-by-step process from basic component definition through advanced orchestration patterns.

For information about the underlying service architecture that powers these components, see Service Architecture. For details about AI model integration and completion adapters, see AI Integration. For tool integration patterns and MCP server connectivity, see Tool Integration.

Core Building Blocks

Multi-agent systems in agent-swarm-kit are constructed from four fundamental components that must be defined in a specific order: tools, completions, agents, and swarms.

Tool Definition

Tools provide the functional capabilities that agents can execute. Each tool is defined using the addTool function with a schema that includes validation, execution logic, and model-facing function descriptions.

Tool Registration Flow

Completion Definition

Completions define AI model integrations that agents use for generating responses. The addCompletion function registers completion providers with their configuration.

Completion Provider Integration

Agent Schema Structure

Agents are defined using addAgent with an IAgentSchema that specifies their behavior, capabilities, and dependencies. The schema is processed through mapAgentSchema to normalize system prompts into arrays.

Agent Schema Transformation

Agent Configuration Patterns

Basic Agent Definition

The simplest agent configuration requires only a name, completion provider, and prompt:

Property	Type	Description
agentName	string	Unique identifier for the agent
completion	CompletionName	Reference to registered completion provider
prompt	string	Main instructions for the agent

Enhanced Agent Configuration

More sophisticated agents can include tools, storage, state management, and system prompts:

Agent Configuration Components

System Prompt Configuration

Agents support multiple types of system prompts that are processed in a specific order:

1. Static System Prompts (systemStatic) - Fixed instructions added to every conversation
2. Dynamic System Prompts (systemDynamic) - Context-aware instructions generated at runtime
3. Regular System Prompts (system) - Standard system-level instructions

Swarm Orchestration

Swarm Definition

Swarms coordinate multiple agents and define navigation patterns between them. The addSwarm function creates swarm configurations with agent lists and default routing.

Swarm Schema Structure

Navigation Between Agents

Agent navigation within swarms is typically implemented through specialized navigation tools that call changeAgent to transfer control between agents:

Agent Navigation Flow

Session Management

Session Creation

Sessions are created using the session function, which establishes a connection between a client and a swarm, returning methods for message processing and resource cleanup.

Session Lifecycle Management

Message Processing

The complete function processes user messages through the active agent in the swarm, handling tool calls, model interactions, and response generation:

Component	Responsibility
ClientSession	Message routing and history management
ClientAgent	AI model interaction and tool execution
ClientSwarm	Agent navigation and swarm coordination

Advanced Orchestration Patterns

Schema Override with overrideAgent

The overrideAgent function allows temporary modification of agent schemas during execution, useful for testing and dynamic behavior adjustment:

Agent Schema Override Process

Background Processing with fork

The fork function enables isolated agent execution similar to POSIX fork, allowing complex processing without interfering with main conversation flows:

Fork-based Background Processing

Scoped Execution

The framework provides scoped execution contexts that allow temporary configuration changes and isolated processing environments.

Documentation Generation

Automatic Schema Documentation

The DocService automatically generates Markdown documentation for all agents and swarms, including UML diagrams and comprehensive schema details:

Documentation Generation Pipeline

The documentation includes tool parameters, system prompts, dependencies, and MCP integrations, providing comprehensive reference material for development teams.

Validation and Error Handling

The framework includes comprehensive validation services that ensure schema consistency and runtime safety:

Validation Service	Purpose
AgentValidationService	Agent schema and dependency validation
SwarmValidationService	Swarm configuration and agent list validation
SessionValidationService	Session state and lifecycle validation
ToolValidationService	Tool schema and execution validation

Multi-agent systems benefit from the framework's automatic model recovery, which handles invalid outputs and tool call failures through rescue algorithms and fallback responses.