Skip to content

Agents & teams#

swarm ships with 40 agents organized into 7 teams. Teams are scoped by concern; agents are role-specialized within a team. A pipeline composes agents across teams to deliver an end-to-end outcome.

The teams#

Team Agents Responsibility
management 4 (ml_director, pipeline_planner, progress_tracker, communication_agent) Orchestration, planning, human-facing status
data 6 (data_request_agent, data_profiler, data_cleaner, data_validator, feature_engineer, data_team_lead) Get, profile, clean, validate, and enrich data
algorithm 9 (problem_classifier, algorithm_selector, model_recommender, repo_fetcher, repo_researcher, setup_agent, llm_specialist, vision_specialist, algorithm_team_lead) Pick the right algorithm + repo for the problem
training 6 (compute_estimator, hyperparam_tuner, trainer, smoke_tester, experiment_tracker, training_team_lead) Train, tune, track experiments
evaluation 5 (model_evaluator, error_analyzer, convergence_monitor, model_comparator, eval_team_lead) Evaluate, compare, explain
quality 5 (code_reviewer, documentation_agent, reproducibility_agent, audit_logger, qa_team_lead) Code quality, docs, audit, reproducibility
deployment 5 (model_packager, serving_deployer, inference_tester, serving_monitor, deploy_team_lead) Package, deploy, test, monitor

How an agent is defined#

Each agent is a dataclass in ml_team/config/agent_defs.py with:

AgentConfig(
    name="algorithm_selector",
    team="algorithm",
    role="Given a problem statement + data profile, pick the best-fit algorithm.",
    tools=["lookup_algorithm", "query_algorithm_registry"],
    rules_path="config/agent_rules/algorithm_selector.yaml",
    model_tier="standard",
)
  • role — the system-prompt framing the LLM sees
  • tools — the per-agent allowlist, enforced by the permission engine
  • rules_path — operational rules (error recovery, escalation paths) in YAML
  • model_tier — maps to an LLM (fast = Haiku-class, standard = Sonnet-class, deep = Opus-class)

Teams are composable, not hard-coded#

A pipeline doesn't instantiate all 7 teams — it picks the agents relevant to its problem. See Pipelines for how this works. Example: fast_prototype uses 5 agents from 3 teams; default_ml_pipeline uses 22 agents from 6 teams.

Agents as a catalogue#

At runtime, the agent catalogue is queryable:

# All agents
swarm agents list

# Filtered by team
swarm agents list --team algorithm

# One agent's definition
swarm agents get algorithm_selector

Or via REST:

curl http://localhost:8000/api/v1/agents
curl http://localhost:8000/api/v1/agents?team=algorithm

Extending: adding a new agent#

See How-to: Write a custom agent. The short version:

  1. Append an AgentConfig to config/agent_defs.py with its tools, rules_path, role
  2. Add an operational-rules YAML under config/agent_rules/<name>.yaml
  3. Reference the agent from your pipeline config
  4. Write a test in ml_team/tests/test_<your_agent>.py

Plugin-contributed agents#

A Claude Code plugin can ship agents in agents/<name>.md. swarm registers them under the namespace plugin-<plugin>::<agent> so they can't collide with built-ins. See Tools & plugins.

Why 40 agents and not one mega-agent?#

Three reasons:

  1. Specialization compresses context. A focused agent with a narrow role + small toolset has a cleaner system prompt, faster tool dispatch, and fewer failure modes.
  2. Permission granularity. Per-agent tool allowlists mean data_cleaner can't call deploy_model even if its LLM decides to try.
  3. Testability. 40 small agents mean 40 small unit tests. A mega-agent produces one test that asserts "it's kinda right, usually."

Next#