Skip to content

SwarmKit v1.1 — MCP Integration Layer + Sub-Agent Architecture

Released: 2026-05-14 Milestone: M8 (MCP Integration Layer) PRs: #123–#150 (28 PRs) Versions: v1.1.0 → v1.1.10

Highlights

Sub-Agent Architecture

The biggest change in v1.1: agents can now delegate to focused sub-agents instead of handling everything with one overloaded agent. A coordinator with 40+ tools that hallucinated is now a coordinator with 4 delegate tools that orchestrates focused researchers.

# Before: one agent, 40+ tools, confused
sterling-architect:
  skills: [search-jira, get-pipeline, search-apis, grep-code, ...]  # 40+ tools

# After: coordinator + focused sub-agents
sterling-architect:  # 4 delegate tools
  ├── jira-researcher      # 10 tools
  ├── config-analyst       # 12 tools
  ├── docs-researcher      # 10 tools
  └── sterling-developer   # 15 tools

Compiler changes that enable this: - Sequential delegation: parent keeps delegation tools after a child completes - Forced synthesis: when tool loop hits 25 turns, force a text response - Invalid delegation detection: catches self-delegation and tells the model - All-children-done stripping: once every child has returned, remove delegation tools to force synthesis - Utility tool exclusion: coordinators with only write-notes aren't nudged to "use tools" - Dynamic recursion limit: 10 steps per agent in topology, minimum 50

MCP Integration Layer

  • Lazy server startup: only start MCP servers the topology actually uses
  • Permission tiers: open|cautious|strict|readonly per server with per-tool overrides
  • MCP timeout + retry: 180s timeout with 2 retries on network failures
  • Side-effect cache skip: download/write/create tools bypass the cache

Multimodal Support

  • Image content blocks on all 7 model providers (Anthropic, OpenAI, Google, Ollama, OpenRouter, Groq, Together)
  • image_block(path) helper for file-to-base64 conversion
  • Skill-driven image flow: MCP tools return ImageContent, compiler passes through to model
  • Document reader MCP server: view_image for visual analysis, draw.io/SVG parsing, CSV, text, file discovery
  • MarkItDown integration: Microsoft's document-to-markdown for PDF/DOCX/Excel with inline images

Run Trace

New swarmkit trace command shows the full agent call graph and token usage for any past run.

swarmkit trace -w .            # list recent runs
swarmkit trace <run-id> -w .   # show call graph

Run: abc123
Topology: sterling-assistant
Duration: 450.2s
Total tokens: 19,042 (input: 11,495 / output: 7,547)

Agent Call Graph:
root (llama-3.3), 447 tokens
  └─→ sterling-architect (kimi-k2.5), 9,436 tokens
        ├─→ jira-researcher (kimi-k2.5), 2,456 tokens
        ├─→ config-analyst (kimi-k2.5), 1,010 tokens
        ├─→ docs-researcher (kimi-k2.5), 993 tokens
        └─→ developer (kimi-k2.5), 4,417 tokens

Tokens by model:
  moonshotai/kimi-k2.5        11,439
  meta-llama/llama-3.3         7,603

Sterling OMS Workspace

Major improvements to the real-world Sterling workspace:

  • Sub-agent topology: architect coordinates 4 focused researchers
  • CDT ingestion: hub rules (from YFS_CONDITION), monitoring rules, queue resolution, org/process type name resolution, enterprise-specific status names
  • CDT MCP server: pipeline graphs with hub rules and monitoring, service graphs with conditions on edges
  • FTS: chunk_id in search results with get-full-chunk for reading full content
  • Deep research prompts: mandatory Jira investigation workflow, Confluence search tips

Breaking Changes

None — v1.1 is backward compatible with v1.0.x workspaces. Existing topologies work without changes.

Upgrade

uv tool upgrade swarmkit-runtime
# or: pip install --upgrade swarmkit-runtime

Full Changelog

Framework (compiler + runtime)

Version Change
v1.1.0 Lazy MCP startup, permission tiers, document reader, multimodal providers, compiler image wiring
v1.1.1 Cache skip for side-effect tools, MarkItDown CWD, tool loop 15
v1.1.2 Forced synthesis at tool limit (25 turns)
v1.1.3 Fix forced synthesis — include last tool results in context
v1.1.4 Sequential delegation — only remove completed child's tools
v1.1.5 Keep all delegation tools (remove none), MCP timeout/retry (180s)
v1.1.6 Dynamic recursion limit based on topology agent count
v1.1.7 Don't nudge coordinators with only utility tools
v1.1.8 Invalid self-delegation detection, strip tools when ALL children done
v1.1.9 Run trace with agent call graph and token tracking
v1.1.10 Trace parent agent tracking for proper hierarchy

Sterling workspace

PR Change
#129 Multimodal topology + model upgrades
#131-132 Deep research prompts, Kimi K2.5, stale skill removal
#134 MarkItDown CWD to knowledge root
#137 Hub rules, monitoring rules, status names, pipeline graphs
#139 FTS chunk_id + get-full-chunk skill
#140-142 Sub-agent architecture (architect → 4 researchers)
#150 Correct hub rules from YFS_CONDITION table