Swarm Assessment

OverviewCopy Anchor Link

The Swarm Assessor analyzes incoming tasks and automatically assigns the best available LLM model to each agent in the swarm. Instead of hardcoding models, let the assessor match agents to models based on task requirements, agent roles, model capabilities, and cost constraints.

Task Input
    │
    ▼
┌──────────────┐     ┌────────────────┐     ┌──────────────┐
│ TaskAnalyzer │────▶│  RoleMatcher   │────▶│ ModelScorer  │
│              │     │                │     │              │
│ complexity   │     │ role needs     │     │ score models │
│ domains      │     │ expertise      │     │ rank & pick  │
│ reasoning    │     │ custom hints   │     │              │
└──────────────┘     └────────────────┘     └──────────────┘
                                                    │
                            ┌───────────────────────┘
                            ▼
                     ┌──────────────┐
                     │ModelDiscovery│
                     │              │
                     │ local Ollama │
                     │ cloud APIs   │
                     └──────────────┘

Enabling the AssessorCopy Anchor Link

Use withAssessor() on the swarm builder:

import { Cogitator, Agent } from '@cogitator-ai/core';
import { swarm } from '@cogitator-ai/swarms';

const team = swarm('dev-team')
  .strategy('hierarchical')
  .supervisor(new Agent({ name: 'lead', model: 'ollama/llama3.2', instructions: 'Coordinate.' }))
  .workers([
    new Agent({ name: 'coder', model: 'ollama/llama3.2', instructions: 'Write code.' }),
    new Agent({ name: 'reviewer', model: 'ollama/llama3.2', instructions: 'Review code quality.' }),
  ])
  .agentMetadata({ coder: { expertise: ['code'] } })
  .withAssessor({
    preferLocal: true,
    minCapabilityMatch: 0.3,
    maxCostPerRun: 0.5,
    enabledProviders: ['ollama', 'openai', 'anthropic'],
  })
  .build(cogitator);

On the first team.run(...) of the swarm, the assessor runs before execution: it analyzes the task, discovers available models, and reassigns each agent to its optimal model (emitting assessor:complete). Later runs of the same Swarm keep those assignments; team.getLastAssessment() returns the result.

Assessor ConfigurationCopy Anchor Link

TaskAnalyzerCopy Anchor Link

The TaskAnalyzer examines the input text and extracts structured requirements:

import { TaskAnalyzer } from '@cogitator-ai/swarms';

const analyzer = new TaskAnalyzer();
const reqs = analyzer.analyze('Analyze this screenshot and write a detailed code review');

The analysis returns a TaskRequirements object:

In 'ai' and 'hybrid' mode the same TaskRequirements come from AiTaskAnalyzer, which runs the assessor model with a structured-output schema:

import { AiTaskAnalyzer } from '@cogitator-ai/swarms';

const aiAnalyzer = new AiTaskAnalyzer(cogitator, 'google/gemini-3.5-flash-lite');
const aiReqs = await aiAnalyzer.analyze('Analyze this screenshot and write a detailed code review');

RoleMatcherCopy Anchor Link

The RoleMatcher takes each agent's role and metadata and adjusts the task requirements to match what that specific agent needs (agents without a role are assessed as workers):

import { RoleMatcher } from '@cogitator-ai/swarms';

const matcher = new RoleMatcher();
const roleReqs = matcher.analyzeRole(swarmAgent, taskRequirements);

Role-based adjustments:

For workers, expertise further refines requirements: code / program / develop require tool calling and add the code domain, research / analysis raise the reasoning level, writing / content add creative, math / statistics add math, and image / visual / design require vision.

ModelDiscoveryCopy Anchor Link

The ModelDiscovery class discovers all available models across providers:

import { ModelDiscovery } from '@cogitator-ai/swarms';

const discovery = new ModelDiscovery({
  ollamaUrl: 'http://localhost:11434',
  enabledProviders: ['ollama', 'openai', 'anthropic', 'google'],
});

const models = await discovery.discoverAll();

Discovery sources:

• Ollama — queries the /api/tags endpoint (5 s timeout; an unreachable server yields no local models) to find locally installed models, and infers capabilities and context windows from known model families (llama3, qwen, mistral, llava, etc.)
• Cloud APIs — a built-in catalog with pricing and capabilities: OpenAI gpt-6-astra, gpt-6.1-sol, gpt-6-luna; Anthropic claude-opus-5-5, claude-sonnet-5-5, claude-haiku-4-5; Google gemini-3.1-pro-preview, gemini-3.8-flash, gemini-3.5-flash-lite

Results are cached for cacheTTL. getCloudModels(providers?) returns the catalog alone. An optional second constructor argument, canRunModel(model), filters the cloud catalog (the assessor passes one that checks the Cogitator can route the model).

Each discovered model includes:

interface DiscoveredModel {
  id: string;
  provider: 'ollama' | 'openai' | 'anthropic' | 'google' | 'azure' | 'mistral';
  displayName: string;
  capabilities: {
    supportsVision?: boolean;
    supportsTools?: boolean;
    supportsJson?: boolean;
    supportsStreaming?: boolean;
  };
  pricing: { input: number; output: number };
  contextWindow: number;
  isLocal: boolean;
  isAvailable: boolean;
}

ModelScorerCopy Anchor Link

The ModelScorer ranks every discovered model against role-specific requirements. Scoring factors include:

• Hard requirements — vision or tool-calling support; models without required capabilities score 0
• Context window — penalty for < 32K tokens when long context is needed
• Cost — local models get a +15 bonus; expensive models are penalized for cost-sensitive tasks
• Reasoning — advanced models (GPT-6 Astra / 6.1 Sol, Claude Opus and Sonnet, Gemini Pro, large local models) are boosted for advanced reasoning tasks
• Speed — fast models (GPT-6 Luna, Claude Haiku, Gemini Flash, small local models) are boosted for speed-sensitive tasks
• Domain match — coding models get a boost for code tasks
• Role fit — supervisors prefer advanced models, workers prefer cost-effective ones

Models below minCapabilityMatch are dropped; if none is left, the agent keeps its model and the assessment carries a warning. With preferLocal, the best local model wins when it scores at least 80% of the best overall. SwarmAssessor / createAssessor(config, cogitator) expose analyze(task, swarmConfig), assignModels(swarmConfig, result) and suggestModels(requirements) for use outside a swarm. Pass the Cogitator to get the same behaviour as inside a Swarm: it runs the 'ai' / 'hybrid' analysis and limits cloud models to the providers it can route. Without it every enabled provider is offered and the task is analyzed with the rules.

Dry RunCopy Anchor Link

Preview assignments without executing the swarm:

const assessment = await team.dryRun({ input: 'Build a REST API with authentication' });

console.log('Task complexity:', assessment.taskAnalysis.complexity);
console.log('Detected domains:', assessment.taskAnalysis.domains);

for (const a of assessment.assignments) {
  console.log(`${a.agentName}: ${a.originalModel} -> ${a.assignedModel} (score: ${a.score})`);
  console.log(`  Reasons: ${a.reasons.join(', ')}`);
  console.log(`  Fallbacks: ${a.fallbackModels.join(', ')}`);
}

console.log(`Estimated cost: $${assessment.totalEstimatedCost.toFixed(4)}`);
console.log('Warnings:', assessment.warnings);

Budget OptimizationCopy Anchor Link

When maxCostPerRun is set and the estimated cost of a run is above it, the assessor downgrades agents, most expensive first, to the first cheaper model in their fallback list (the next-best scored models) until the estimate fits the budget. The estimate uses a token count per task complexity (500 / 1500 / 4000 tokens) and the catalog prices; local models cost nothing.

const team = swarm('budget-team')
  .strategy('hierarchical')
  .supervisor(leadAgent)
  .workers([devA, devB, devC])
  .withAssessor({
    maxCostPerRun: 0.1,
    preferLocal: true,
  })
  .build(cogitator);

Locked ModelsCopy Anchor Link

If an agent should always use a specific model regardless of assessment, set locked: true in its swarm metadata:

const auditor = new Agent({
  name: 'auditor',
  model: 'openai/gpt-5.5',
  instructions: 'Perform security audit.',
});

const team = swarm('audit-team')
  .strategy('round-robin')
  .agents([auditor, helper])
  .agentMetadata({ auditor: { locked: true } })
  .withAssessor({ preferLocal: true })
  .build(cogitator);

Locked agents are skipped during assessment and keep their original model assignment. Unlocked agents are replaced by clones of themselves running the assigned, provider-qualified model (for example ollama/llama3.2:3b) — name, instructions and tools are preserved. Pipeline stages are reassigned as well.