uagents-stigmergy

Extend Fetch.ai uAgents with stigmergic intelligence. Build agents that coordinate through pheromone trails, not central control.

$ pip install uagents-stigmergy

What You Get

Everything you need to build stigmergic agents on Fetch.ai

Pheromone-Based Communication

Agents leave digital pheromone trails that other agents can sense and follow. Information propagates through the environment, not direct messaging.

Emergent Intelligence

No central coordinator. Solutions emerge from the collective behavior of simple agents following simple rules.

Flexible Networking

Choose between peer-to-peer gossip, centralized field servers, or hybrid mode with automatic failover.

Fetch.ai Native

Built on uAgents framework. Deploy to Agentverse with one click. Full integration with FET token economics.

INTERACTIVE

Architecture Explorer

Click on any component to see its documentation, code examples, and API reference. Toggle between network modes to see how data flows change.

Mode:

100%

uagents-stigmergy Architecture

hybrid mode

SDK Overview

The uagents-stigmergy SDK extends Fetch.ai's uAgents framework with stigmergic intelligence capabilities.

Core Layer

Pheromone field, trails, ACO algorithms

Mixin Layer

Integration point for any uAgent

Network Modes

Gossip, Central, or Hybrid coordination

Fetch.ai Integration

Agentverse, Bureau, FET token

Click any component in the diagram to see its documentation, code examples, and API reference.

Quick Start

python

pip 400">"text-purple-400">install uagents-stigmergy

400">"text-purple-400">from uagents 400">"text-purple-400">import Agent
400">"text-purple-400">from uagents_stigmergy 400">"text-purple-400">import StigmergicMix400">"text-purple-400">in

400">"text-purple-400">class MyAgent(Agent, StigmergicMix400">"text-purple-400">in):
    pass

Quick Examples

Get started in minutes with these code snippets

Basic Stigmergic Agent

Create an agent with pheromone capabilities

Python

from uagents import Agent
from uagents_stigmergy import StigmergicMixin

class ForagerAgent(Agent, StigmergicMixin):
    """A simple stigmergic foraging agent"""

    def __init__(self, name: str):
        Agent.__init__(self, name=name)
        StigmergicMixin.__init__(self, mode="hybrid")

    @on_pheromone("food")
    async def follow_food_trail(self, concentration: float, gradient: tuple):
        """React when food pheromone is detected"""
        if concentration > 0.5:
            await self.move_along_gradient(gradient)

    @on_interval(seconds=1.0)
    async def forage(self):
        if self.found_food():
            await self.deposit_trail("food", strength=1.0)
        else:
            await self.follow_or_explore("food")

Pheromone Field Management

Work with pheromone concentrations and trails

Python

from uagents_stigmergy import PheromoneField, TrailManager

# Create a pheromone field
field = PheromoneField(
    width=100,
    height=100,
    decay_rate=0.95,
    diffusion_rate=0.1
)

# Higher-level trail management
trail_manager = TrailManager(field)

# Create a trail
trail_id = trail_manager.create_trail(
    path=[(0, 0), (50, 25), (100, 50)],
    pheromone_type="exploration",
    initial_strength=0.8
)

# Find strongest path
best = trail_manager.find_strongest_trail(
    start=(0, 0),
    end=(100, 50)
)

Deploy to Agentverse

One-click deployment to Fetch.ai's hosted environment

YAML / Python

# agentverse_config.yaml
agent:
  name: "colony_worker_1"
  description: "Stigmergic worker agent"

stigmergy:
  mode: "hybrid"
  field_server: "agent1q..."
  fallback: true

protocols:
  - pheromone_v1
  - trail_sharing_v1

# Deploy from CLI
$ uagents deploy --config agentverse_config.yaml

# Or programmatically
from uagents_stigmergy import deploy_to_agentverse

await deploy_to_agentverse(
    agent=my_agent,
    wallet=my_wallet,
    mailbox=True
)

Why Stigmergy?

How stigmergic coordination compares to traditional approaches

Aspect	Stigmergy	Central Coordinator	Direct Messaging
Single Point of Failure	None	Coordinator	Low
Scalability	Linear	Limited	O(n^2)
Communication	Indirect	Hub-spoke	Point-to-point
Global Knowledge	Not required	Required	Distributed
Adaptability	Self-organizing	Reconfigurable	Manual
Agent Complexity	Simple rules	Protocol-aware	State-heavy

Ready to Build?

Start building stigmergic agents today. The SDK is open source and free to use.

Fetch.ai Docs | Agentverse | Our Vision

The Book

Lessons from Ants at Work