Distributed multi-agent AI orchestration on Docker. Run isolated AI agents. Coordinate via NATS. Define workflows in YAML.

---

🤔 Why agent-mesh?

LangChain agents fall over at 5 concurrent tasks. CrewAI has no isolation. Autogen runs in a single Python process.

agent-mesh runs each agent in its own Docker container, talking over NATS, with a control plane that handles:

• 🛡️ Process isolation (one OOM doesn't kill the swarm)
• 🔁 Retries + circuit breakers per agent
• 📜 YAML-defined workflows (no Python required)
• 📊 Distributed tracing of agent decisions
• ⚖️ Per-agent rate limits + cost ceilings
• 🧩 Pluggable models (OpenAI, Anthropic, Ollama)

This is what production multi-agent looks like.

---

🏗️ Architecture

                 ┌─────────────────────────────────────────────┐
                 │            CONTROL PLANE  (Go)              │
                 │  ┌─────────────┬────────────┬────────────┐  │
                 │  │ Orchestrator│  Registry  │  Workflow  │  │
                 │  └─────────────┴────────────┴────────────┘  │
                 │            REST + gRPC API                   │
                 └─────────────────┬───────────────────────────┘
                                   │
                       ┌───────────┴────────────┐
                       │      NATS  (Bus)        │
                       │   subject: agent.*      │
                       └───────────┬────────────┘
                                   │
        ┌──────────┬──────────┬────┴────┬──────────┬──────────┐
        ▼          ▼          ▼          ▼          ▼          ▼
    ┌───────┐  ┌───────┐  ┌───────┐  ┌───────┐  ┌───────┐  ┌───────┐
    │Researcher│ Coder │ │Reviewer│ │ Writer │ │ Custom │ │ Custom │
    │ agent  │  │ agent │  │ agent │  │ agent  │  │ agent  │  │ agent  │
    └───────┘  └───────┘  └───────┘  └───────┘  └───────┘  └───────┘
       (each in its own Docker container, isolated, replaceable)

---

⚡ Quick Start

git clone https://github.com/kasimmj/agent-mesh
cd agent-mesh
cp .env.example .env  # add your model API keys
docker compose up -d

Then submit a workflow:

curl -X POST http://localhost:8080/workflows \
  -H "Content-Type: application/yaml" \
  --data-binary @examples/workflows/research-and-write.yaml

Watch agents collaborate in real-time:

docker compose logs -f
# Or: open http://localhost:8080/ui

---

📜 Workflow Format

A workflow is YAML. Each step calls an agent and feeds its output forward.

name: research-and-write
description: Research a topic and produce a polished article.

steps:
  - id: research
    agent: researcher
    input:
      topic: "{{ .input.topic }}"
      depth: 3
    timeout: 60s

  - id: draft
    agent: writer
    depends_on: [research]
    input:
      facts: "{{ .steps.research.output }}"
      style: "technical-blog"

  - id: review
    agent: reviewer
    depends_on: [draft]
    input:
      text: "{{ .steps.draft.output }}"
      criteria: ["clarity", "accuracy", "tone"]

  - id: refine
    agent: writer
    depends_on: [review]
    input:
      draft: "{{ .steps.draft.output }}"
      feedback: "{{ .steps.review.output }}"

  - id: finalize
    agent: writer
    depends_on: [refine]
    input:
      text: "{{ .steps.refine.output }}"
      mode: "polish"

output: "{{ .steps.finalize.output }}"

---

🧩 Built-in Agents

Agent	Image	Role
researcher	ghcr.io/kasimmj/agent-mesh-researcher	Web search + summarization + source citation
coder	ghcr.io/kasimmj/agent-mesh-coder	Code generation, edits, test writing
reviewer	ghcr.io/kasimmj/agent-mesh-reviewer	Critique, scoring, structured feedback
writer	ghcr.io/kasimmj/agent-mesh-writer	Long-form text, refinement, style transfer
executor	ghcr.io/kasimmj/agent-mesh-executor	Run code in a sandbox and return results
vision	ghcr.io/kasimmj/agent-mesh-vision	Image understanding, OCR, captioning

---

🛠️ Building a Custom Agent

Every agent implements one Go interface:

type Agent interface {
    Capabilities() Capabilities
    Handle(ctx context.Context, task Task) (Result, error)
}

Minimal example:

package main

import "github.com/kasimmj/agent-mesh/agents/base"

type Translator struct{ base.Agent }

func (t *Translator) Handle(ctx context.Context, task base.Task) (base.Result, error) {
    text := task.Input["text"].(string)
    target := task.Input["lang"].(string)
    // ... call your model
    return base.Result{Output: translated}, nil
}

func main() {
    base.Run(&Translator{
        Agent: base.Agent{
            Name:    "translator",
            Version: "0.1.0",
        },
    })
}

Build → Push → Mesh discovers it automatically via NATS.

---

📊 Observability

Every agent message goes through NATS, so you can replay:

nats sub "agent.>" --server localhost:4222

Distributed tracing (OpenTelemetry) is wired by default. Open Jaeger at localhost:16686.

Per-agent metrics in Prometheus (localhost:9090) with a pre-built Grafana dashboard at localhost:3000.

---

🛡️ Safety & Cost Controls

In config.yaml:

limits:
  global:
    max_cost_per_workflow: 1.00  # USD
    max_agent_invocations: 50
    timeout: 10m

  per_agent:
    researcher:
      rate_limit: 30/min
      max_tokens: 4000
      models: [claude-haiku-4, gpt-4o-mini]

If a workflow exceeds the budget, the orchestrator stops it cleanly and returns partial output.

---

🚀 Roadmap

• Core orchestrator + NATS bus
• YAML workflow DSL
• 6 built-in agents (researcher, coder, reviewer, writer, executor, vision)
• Web UI for workflow design (drag-and-drop)
• Multi-host deployment via Docker Swarm
• State persistence (resume from crash)
• Marketplace of community agents

---

📜 License

Apache-2.0. See LICENSE.

---

Star ⭐ to follow production multi-agent AI.