SkillOrchestra

​

Overview

​

Installation

pip install -U swarms

​

How It Works

Task -> Skill Inference -> Agent Scoring -> Agent Selection -> Execution -> Learning

1. Skill Inference — An LLM analyzes the incoming task and identifies which fine-grained skills are required (e.g., python_coding, data_analysis, technical_writing), each with an importance weight.
2. Agent Scoring — Each agent is scored using a weighted competence-cost formula against the required skills. This step is pure math — no LLM calls.
3. Agent Selection — The top-k agents with the highest scores are selected.
4. Execution — Selected agents execute the task. Multiple agents run concurrently via ThreadPoolExecutor.
5. Learning (optional) — An LLM evaluates the output quality, and agent skill profiles are updated via exponential moving average (EMA).

​

Scoring Formula

score = sum(competence_weight * competence_i * importance_i + cost_weight * normalized_cost_i * importance_i) / total_importance

• competence_i is the agent’s estimated probability of success on skill i
• normalized_cost_i is 1 - (cost - min_cost) / (max_cost - min_cost) (lower cost = higher score)
• importance_i is how important the skill is for the task

​

Key Components

​

Data Models

​

Attributes

​

Methods

​

run()

def run(self, task: str, img: Optional[str] = None, imgs: Optional[List[str]] = None) -> Any

• task (str): The task to execute
• img (Optional[str]): Optional image input
• imgs (Optional[List[str]]): Optional list of image inputs

​

__call__()

def __call__(self, task: str, *args, **kwargs) -> Any

• task (str): The task to execute

​

batch_run()

def batch_run(self, tasks: List[str]) -> List[Any]

• tasks (List[str]): List of tasks to execute

​

concurrent_batch_run()

def concurrent_batch_run(self, tasks: List[str]) -> List[Any]

• tasks (List[str]): List of tasks to execute

​

get_handbook()

def get_handbook(self) -> dict

​

update_handbook()

def update_handbook(self, handbook: SkillHandbook) -> None

• handbook (SkillHandbook): The new skill handbook

​

Architecture

​

Pipeline Flow

​

Scoring and Selection

​

Execution Modes

​

Best Practices

​

Agent Design

• Write descriptive agent descriptions — The auto-generated skill handbook is only as good as your agent descriptions. Be specific about what each agent can do.
• Use distinct specializations — Agents with overlapping skills reduce the effectiveness of skill-based routing. Make each agent clearly specialized.
• Keep system prompts focused — System prompts should reinforce the agent’s specialization, not try to make the agent a generalist.

​

Tuning Weights

• Default (0.7 competence / 0.3 cost) — Good for most use cases where quality matters more than cost.
• High competence weight (0.9 / 0.1) — Use when quality is critical and cost is not a concern.
• Balanced (0.5 / 0.5) — Use when you want a balance between quality and cost efficiency.
• High cost weight (0.3 / 0.7) — Use for high-volume, cost-sensitive workloads where “good enough” is acceptable.

​

Learning Configuration

• learning_rate=0.1 (default) — Slow adaptation, stable profiles. Good for production.
• learning_rate=0.3 — Faster adaptation. Good for initial calibration of a new team.
• max_loops=1 — Single pass, no refinement. Best for simple tasks.
• max_loops=2-3 — Execute, evaluate, refine. Good for complex tasks that benefit from iterative improvement.

​

Error Handling

from swarms import SkillOrchestra

try:
    result = orchestra.run(task)
except ValueError as e:
    # Configuration errors (no agents, invalid weights)
    print(f"Configuration error: {e}")
except Exception as e:
    # Execution errors (LLM failures, agent errors)
    print(f"Execution error: {e}")

​

Inspecting Routing Decisions

from swarms import SkillOrchestra

orchestra = SkillOrchestra(
    agents=agents,
    verbose=True,    # Logs skill inference and scoring details
    print_on=True,   # Prints formatted panels to console
)

​

Saving and Loading Handbooks

import json
from swarms import SkillOrchestra
from swarms.structs.skill_orchestra import SkillHandbook

# Save a tuned handbook
handbook_dict = orchestra.get_handbook()
with open("my_handbook.json", "w") as f:
    json.dump(handbook_dict, f, indent=2)

# Load and reuse later
with open("my_handbook.json") as f:
    data = json.load(f)

handbook = SkillHandbook.model_validate(data)
orchestra = SkillOrchestra(
    agents=agents,
    skill_handbook=handbook,
    auto_generate_skills=False,
)

​

Source Code