swarm

Swarm is a Rust-based framework for building and orchestrating a network of specialized agents that collaborate through flexible workflows. It implements a conductor (Planner Agent) and a suite of domain-specific agents (Domain Agents) that can be instantiated on demand via an Agent Factory. The system leverages the MCP (Model Context Protocol) and A2A (Agent-to-Agent) protocols to enable robust, interoperable communication between agents and external tools. When you run Swarm, you can either execute a predefined static workflow loaded from JSON or dynamically generate a workflow based on the capabilities of available agents, then execute the plan with an Executor Agent. A built-in Evaluation Service using an LLM-as-a-Judge component provides feedback to refine dynamic plans, creating a continuous improvement loop for complex tasks.

Prerequisites:

• Rust and Cargo installed (Rust is required to build and run Swarm).
• Git installed to clone the repository.
• An LLM API key setup (as described by your provider) for A2A, MCP, Judge, and Planner services.

Step-by-step:

1. Clone the repository: git clone https://github.com/fcn06/swarm.git
2. Navigate into the project: cd swarm
3. Build in release mode: cargo build --release
4. Set required environment variables (example, replace placeholders with real keys): export LLM_A2A_API_KEY=<YOUR-LLM-API-KEY> export LLM_MCP_API_KEY=<YOUR-LLM-API-KEY> export LLM_JUDGE_API_KEY=<YOUR-LLM-API-KEY> export LLM_PLANNER_API_KEY=<YOUR-LLM-API-KEY>
5. Run the Swarm server (the default configuration runs the release build): cargo run --release
6. Optional: integrate with an MCP client or A2A client to trigger planner/executor workflows as described in the documentation.

Notes:

• Ensure your environment has network access to your chosen LLM provider endpoints.
• The repository provides scripts and examples for both static and dynamic workflow demonstrations; consult the docs folder for paths to those scripts.

Tips and common issues:

• If dynamic workflow generation fails, verify that the Planner Agent has access to all required Domain Agents and their capabilities are correctly registered in the runtime.
• When using the LLM-as-a-Judge Evaluation Service, ensure your API keys have the appropriate permissions and rate limits for the expected workload.
• If you encounter port or service discovery issues, check the MCP Runtime networking configuration and verify that Agent Factory can instantiate new Domain Agents as needed.
• Environment variables for keys can be centralized in a .env file and loaded at startup if your deployment environment supports it.
• For larger deployments, consider scaling Domain Agents and ensuring the Executor has robust retry and timeout handling to avoid stuck workflows.