Harish Kotra (he/him)

Posted on Feb 24

SwarmMind: Local Multi‑Agent Content Pipelines with Ollama + Walkie

#python #ai #programming #tutorial

Building multi‑agent systems is easy until you need them to talk. Most demos short‑circuit communication with in‑memory calls, which hides the real engineering work: process boundaries, peer discovery, secure message transport, and failure handling. SwarmMind is a compact, production‑minded example of a real multi‑agent pipeline using Ollama for local LLM inference and Walkie for P2P communication, wired together as a content creation pipeline (research → draft → edit).

This post explains the architecture, message contract, and operational details so you can adapt it to your own agent workflows.

Why Ollama + Walkie

Ollama gives you local model inference with a stable HTTP API—ideal for predictable latency, privacy, and cost control. Walkie provides P2P, encrypted, server‑less channels so agents can communicate across terminals or machines without standing up a broker. Together they let you build distributed agent systems that are still simple to run locally.

Key properties we rely on:

Ollama: deterministic local inference, model pinning, simple HTTP JSON API.
Walkie: P2P DHT discovery, encrypted channels, zero server setup, CLI‑friendly.

Architecture Overview

SwarmMind implements three agents with explicit roles and communication channels:

Researcher → generates research notes and outline.
Writer → produces a draft blog post from the brief.
Editor → polishes and finalizes the post.

Agents are independent processes and communicate only via Walkie channels. No shared Python objects, no in‑memory shortcuts.

Message Contract (JSON)

To keep the pipeline explicit and debuggable, agents exchange structured JSON:

{
  "from": "agent_name",
  "timestamp": "ISO8601",
  "type": "research|draft|final",
  "content": "actual content here",
  "metadata": {
    "topic": "optional",
    "notes": "optional"
  }
}

This contract makes it easy to log, replay, or extend the system (e.g., add a fact‑checker) without rewriting how agents talk.

Agent Behavior

Each agent extends a shared BaseAgent that:

Joins Walkie channels
Waits for messages
Processes input with Ollama
Sends structured output downstream
Logs every step

Researcher

Input: topic string
Output: research brief with key facts, angles, audience considerations, and outline
Channel: draft-room

Writer

Input: research brief
Output: full blog draft (intro, body, conclusion)
Channel: edit-room

Editor

Input: draft
Output: final post plus a brief changelog
Output: prints to stdout and writes output/final-blog-post.md

Ollama Client

The OllamaClient is a small async wrapper around POST /api/generate:

Retries with exponential backoff
Timeouts (default 30s, configurable)
Fallback models (configured per agent)
Cleaned responses (trimmed and normalized)

This ensures failures degrade gracefully instead of crashing the pipeline.

Walkie Integration

Walkie is used via subprocess calls in WalkieWrapper:

create_channel, join_channel, send_message, read_messages, status
Automatic daemon recovery attempt on common socket/daemon errors
Message parsing for both JSON and CLI text formats

The result is a real distributed system: launch each agent in separate terminals (or machines) and they still coordinate.

Demo vs Distributed Modes

SwarmMind supports two run modes:

1) Demo (single process)

python main.py --demo --topic "The Future of Edge AI"

Runs all three agents sequentially for a fast demo.

2) Distributed (multi‑process)

# Terminal 1
python main.py --agent researcher --topic "The Future of Edge AI"

# Terminal 2
python main.py --agent writer

# Terminal 3
python main.py --agent editor

True process‑level separation, real Walkie channels.

What Makes This Production‑Ready

Async I/O for Ollama and Walkie
Structured logging per agent + global log
Health checks for Ollama + Walkie
Model fallbacks to keep the pipeline alive
Unit tests for the Ollama and Walkie clients
Makefile targets for install/demo/distributed

Where to Go Next

SwarmMind is intentionally small, but the architecture scales:

Add agents (fact‑checker, SEO optimizer)
Add a UI layer (Gradio already included)
Swap the pipeline for code review or research synthesis
Run agents across multiple machines without changing code

If you’re building multi‑agent systems, treat communication as a first‑class component—not an afterthought. Ollama + Walkie is a pragmatic foundation that keeps everything local, reliable, and easy to debug.

Github Repo is here.

DEV Community