Skip to content

guanyang/open-agent-hub / skills/multi-agent-patterns

multi-agent-patterns

Verified

This skill should be used when designing multi-agent systems that need context isolation, supervisor or swarm coordination, explicit handoffs, parallel execution, or a decision on whether multiple agents are justified.

FileKindSize
SKILL.mdskill md18.2 KB
references/frameworks.mdmarkdown12.2 KB
scripts/coordination.pyscript20.5 KB

scripts/coordination.py

View on GitHub
"""
Multi-Agent Coordination Utilities

Provides reusable building blocks for multi-agent coordination patterns:
supervisor/orchestrator, peer-to-peer handoffs, consensus mechanisms,
and failure handling with circuit breakers.

Use when: building multi-agent systems that need structured communication,
task delegation, consensus voting, or fault-tolerant agent coordination.

Designed for composability — import individual classes or use the
``if __name__ == "__main__"`` demo to see all patterns in action.
"""

from typing import Dict, List, Any, Optional
from dataclasses import dataclass, field
from enum import Enum
import time
import uuid

__all__ = [
    "MessageType",
    "AgentMessage",
    "AgentCommunication",
    "SupervisorAgent",
    "HandoffProtocol",
    "ConsensusManager",
    "AgentFailureHandler",
]


class MessageType(Enum):
    """Types of messages exchanged between agents."""

    REQUEST = "request"
    RESPONSE = "response"
    HANDOVER = "handover"
    FEEDBACK = "feedback"
    ALERT = "alert"


@dataclass
class AgentMessage:
    """Message exchanged between agents.

    Use when: agents need a structured envelope for inter-agent communication
    that carries sender/receiver identity, type, priority, and payload.
    """

    sender: str
    receiver: str
    message_type: MessageType
    content: Dict[str, Any]
    timestamp: float = field(default_factory=time.time)
    message_id: str = field(default_factory=lambda: str(uuid.uuid4()))
    requires_response: bool = False
    priority: int = 0  # 0 = normal, higher = more urgent


class AgentCommunication:
    """Communication channel for multi-agent systems.

    Use when: multiple agents need an in-process message bus for sending,
    receiving, and broadcasting messages with history tracking.
    """

    def __init__(self) -> None:
        self.inbox: Dict[str, List[AgentMessage]] = {}
        self.outbox: List[AgentMessage] = []
        self.message_history: List[AgentMessage] = []

    def send(self, message: AgentMessage) -> None:
        """Send a message to an agent."""
        if message.receiver not in self.inbox:
            self.inbox[message.receiver] = []
        self.inbox[message.receiver].append(message)
        self.outbox.append(message)
        self.message_history.append(message)

    def receive(self, agent_id: str) -> List[AgentMessage]:
        """Receive all messages for an agent, clearing its inbox."""
        messages = self.inbox.get(agent_id, [])
        self.inbox[agent_id] = []
        return messages

    def broadcast(
        self,
        sender: str,
        message_type: MessageType,
        content: Dict[str, Any],
        receivers: List[str],
    ) -> None:
        """Broadcast a message to multiple agents."""
        for receiver in receivers:
            self.send(
                AgentMessage(
                    sender=sender,
                    receiver=receiver,
                    message_type=message_type,
                    content=content,
                )
            )


# ---------------------------------------------------------------------------
# Supervisor Pattern
# ---------------------------------------------------------------------------


class SupervisorAgent:
    """Central supervisor agent that coordinates worker agents.

    Use when: tasks have clear decomposition and a single coordinator should
    delegate subtasks, track worker status, and aggregate results.
    """

    def __init__(self, name: str, communication: AgentCommunication) -> None:
        self.name = name
        self.communication = communication
        self.workers: Dict[str, Dict[str, Any]] = {}
        self.task_queue: List[Dict[str, Any]] = []
        self.completed_tasks: List[Dict[str, Any]] = []
        self.current_state: Dict[str, Any] = {}

    def register_worker(self, worker_id: str, capabilities: List[str]) -> None:
        """Register a worker agent with the supervisor."""
        self.workers[worker_id] = {
            "capabilities": capabilities,
            "status": "available",
            "current_task": None,
            "metrics": {"tasks_completed": 0, "avg_response_time": 0.0},
        }

    def decompose_task(self, task: Dict[str, Any]) -> List[Dict[str, Any]]:
        """Decompose a task into subtasks.

        Use when: a high-level task needs to be broken into assignable units.
        In production, replace the rule-based logic with LLM-driven planning.
        """
        subtasks: List[Dict[str, Any]] = []
        task_type = task.get("type", "general")

        if task_type == "research":
            subtasks = [
                {"type": "search", "description": "Gather information"},
                {"type": "analyze", "description": "Analyze findings"},
                {"type": "synthesize", "description": "Synthesize results"},
            ]
        elif task_type == "create":
            subtasks = [
                {"type": "plan", "description": "Create plan"},
                {"type": "draft", "description": "Draft content"},
                {"type": "review", "description": "Review and refine"},
            ]
        else:
            subtasks = [
                {
                    "type": "execute",
                    "description": task.get("description", "Execute task"),
                }
            ]

        for subtask in subtasks:
            subtask["parent_task"] = task.get("id")
            subtask["priority"] = task.get("priority", 0)

        return subtasks

    def assign_task(self, subtask: Dict[str, Any], worker_id: str) -> None:
        """Assign a subtask to a worker agent."""
        if worker_id not in self.workers:
            raise ValueError(f"Unknown worker: {worker_id}")

        self.workers[worker_id]["status"] = "busy"
        self.workers[worker_id]["current_task"] = subtask.get("id")

        self._send(
            AgentMessage(
                sender=self.name,
                receiver=worker_id,
                message_type=MessageType.REQUEST,
                content={"action": "execute_task", "task": subtask},
                requires_response=True,
                priority=subtask.get("priority", 0),
            )
        )

    def select_worker(self, subtask: Dict[str, Any]) -> str:
        """Select the best available worker for a subtask.

        Use when: the supervisor needs capability-aware routing with
        load-balancing (fewest completed tasks chosen first).
        """
        required_capability = subtask.get("type", "general")

        candidates = [
            wid
            for wid, info in self.workers.items()
            if info["status"] == "available"
            and required_capability in info["capabilities"]
        ]

        if not candidates:
            candidates = [
                wid
                for wid, info in self.workers.items()
                if info["status"] == "available"
            ]

        if not candidates:
            raise ValueError("No available workers")

        return min(
            candidates,
            key=lambda w: self.workers[w]["metrics"]["tasks_completed"],
        )

    def aggregate_results(
        self, subtask_results: List[Dict[str, Any]]
    ) -> Dict[str, Any]:
        """Aggregate results from completed subtasks."""
        summaries = [
            r.get("summary", "")
            for r in subtask_results
            if r.get("success")
        ]
        successful = sum(
            1 for r in subtask_results if r.get("success", False)
        )
        quality = successful / len(subtask_results) if subtask_results else 0.0

        return {
            "results": subtask_results,
            "summary": " | ".join(summaries),
            "quality_score": quality,
        }

    def run_workflow(self, task: Dict[str, Any]) -> Dict[str, Any]:
        """Execute a complete workflow with supervision.

        Use when: running an end-to-end supervised pipeline that decomposes
        a task, assigns subtasks, collects results, and aggregates them.

        Note: This is a synchronous simulation. Workers do not execute
        asynchronously — each subtask is simulated inline. In production,
        replace ``_simulate_worker_response`` with actual async worker
        execution and message passing.
        """
        subtasks = self.decompose_task(task)

        results: List[Dict[str, Any]] = []
        for subtask in subtasks:
            worker = self.select_worker(subtask)
            self.assign_task(subtask, worker)

            # Simulate worker executing and responding
            response = self._simulate_worker_response(worker, subtask)
            self.communication.send(
                AgentMessage(
                    sender=worker,
                    receiver=self.name,
                    message_type=MessageType.RESPONSE,
                    content=response,
                )
            )
            self.workers[worker]["status"] = "available"
            self.workers[worker]["metrics"]["tasks_completed"] += 1

            messages = self.communication.receive(self.name)
            for msg in messages:
                if msg.message_type == MessageType.RESPONSE:
                    results.append(msg.content)

        final_result = self.aggregate_results(results)

        return {
            "task": task,
            "subtask_results": results,
            "final_result": final_result,
            "success": final_result["quality_score"] >= 0.8,
        }

    def _simulate_worker_response(
        self, worker_id: str, subtask: Dict[str, Any]
    ) -> Dict[str, Any]:
        """Simulate a worker completing a subtask.

        In production, replace with actual agent execution that sends
        the subtask to a worker process and awaits a real response.
        """
        return {
            "success": True,
            "summary": f"{worker_id} completed: {subtask.get('description', subtask.get('type', 'task'))}",
            "worker": worker_id,
            "subtask_type": subtask.get("type"),
        }

    def _send(self, message: AgentMessage) -> None:
        """Send message through the communication channel."""
        self.communication.send(message)


# ---------------------------------------------------------------------------
# Handoff Protocol
# ---------------------------------------------------------------------------


class HandoffProtocol:
    """Protocol for agent-to-agent handoffs.

    Use when: implementing peer-to-peer or swarm patterns where agents
    transfer control and task state to one another.
    """

    def __init__(self, communication: AgentCommunication) -> None:
        self.communication = communication

    def create_handoff(
        self,
        from_agent: str,
        to_agent: str,
        context: Dict[str, Any],
        reason: str,
    ) -> AgentMessage:
        """Create a handoff message with transferred context."""
        return AgentMessage(
            sender=from_agent,
            receiver=to_agent,
            message_type=MessageType.HANDOVER,
            content={
                "handoff_reason": reason,
                "transferred_context": context,
                "handoff_timestamp": time.time(),
            },
            priority=1,
        )

    def accept_handoff(self, agent_id: str) -> Optional[AgentMessage]:
        """Accept the first pending handoff for an agent, if any."""
        messages = self.communication.receive(agent_id)

        for msg in messages:
            if msg.message_type == MessageType.HANDOVER:
                return msg

        return None

    def transfer_with_state(
        self,
        from_agent: str,
        to_agent: str,
        state: Dict[str, Any],
        task: Dict[str, Any],
    ) -> bool:
        """Transfer task state from one agent to another.

        Use when: a handoff must carry full task state and progress so the
        receiving agent can resume without re-deriving context.

        Returns True if the receiving agent acknowledged the handoff.
        """
        handoff = self.create_handoff(
            from_agent=from_agent,
            to_agent=to_agent,
            context={
                "task_state": state,
                "task_details": task,
                "progress": state.get("progress", 0),
            },
            reason="task_transfer",
        )

        self.communication.send(handoff)

        # In production, replace sleep with async await + timeout
        time.sleep(0.1)
        ack = self.communication.receive(from_agent)

        return any(
            m.message_type == MessageType.RESPONSE
            and m.content.get("status") == "handoff_received"
            for m in ack
        )


# ---------------------------------------------------------------------------
# Consensus Mechanism
# ---------------------------------------------------------------------------


class ConsensusManager:
    """Manager for multi-agent consensus building.

    Use when: multiple agents must vote on a decision and the system needs
    weighted consensus that accounts for confidence and expertise rather
    than naive majority voting.
    """

    def __init__(self) -> None:
        self.votes: Dict[str, List[Dict[str, Any]]] = {}
        self.debates: Dict[str, List[Dict[str, Any]]] = {}

    def initiate_vote(
        self, topic_id: str, agents: List[str], options: List[str]
    ) -> None:
        """Initiate a voting round on a topic."""
        self.votes[topic_id] = [
            {
                "agent": agent,
                "topic": topic_id,
                "options": options,
                "status": "pending",
            }
            for agent in agents
        ]

    def submit_vote(
        self,
        topic_id: str,
        agent_id: str,
        selection: str,
        confidence: float,
    ) -> None:
        """Submit a vote for a topic with a confidence weight."""
        if topic_id not in self.votes:
            raise ValueError(f"Unknown topic: {topic_id}")

        for vote in self.votes[topic_id]:
            if vote["agent"] == agent_id:
                vote["status"] = "cast"
                vote["selection"] = selection
                vote["confidence"] = confidence
                break

    def calculate_weighted_consensus(self, topic_id: str) -> Dict[str, Any]:
        """Calculate weighted consensus from cast votes.

        Use when: votes are in and the system needs to determine a winner
        weighted by each agent's confidence rather than simple majority.
        Weight = confidence * expertise_factor.
        """
        if topic_id not in self.votes:
            raise ValueError(f"Unknown topic: {topic_id}")

        votes = [
            v for v in self.votes[topic_id] if v.get("status") == "cast"
        ]

        if not votes:
            return {"status": "no_votes", "result": None}

        # Group by selection
        selections: Dict[str, List[Dict[str, Any]]] = {}
        for vote in votes:
            selection = vote["selection"]
            if selection not in selections:
                selections[selection] = []
            selections[selection].append(vote)

        # Calculate weighted score for each selection
        results: Dict[str, Dict[str, Any]] = {}
        for selection, selection_votes in selections.items():
            weighted_sum = sum(v["confidence"] for v in selection_votes)
            avg_confidence = (
                weighted_sum / len(selection_votes) if selection_votes else 0.0
            )
            results[selection] = {
                "weighted_score": weighted_sum,
                "avg_confidence": avg_confidence,
                "vote_count": len(selection_votes),
            }

        winner = max(results.keys(), key=lambda s: results[s]["weighted_score"])

        return {
            "status": "complete",
            "result": winner,
            "details": results,
            "consensus_strength": (
                results[winner]["weighted_score"] / len(votes) if votes else 0.0
            ),
        }


# ---------------------------------------------------------------------------
# Failure Handling
# ---------------------------------------------------------------------------


class AgentFailureHandler:
    """Handler for agent failures in multi-agent systems.

    Use when: agents may fail and the system needs retry logic with
    exponential backoff, circuit breakers, and automatic rerouting to
    backup agents.
    """

    def __init__(
        self,
        communication: AgentCommunication,
        max_retries: int = 3,
    ) -> None:
        self.communication = communication
        self.max_retries = max_retries
        self.failure_counts: Dict[str, int] = {}
        self.circuit_breakers: Dict[str, float] = {}  # agent -> unlock time

    def handle_failure(
        self, agent_id: str, task_id: str, error: str
    ) -> Dict[str, Any]:
        """Handle a failure from an agent.

        Use when: an agent reports an error and the system must decide
        whether to retry (with backoff) or reroute to a backup agent.
        """
        self.failure_counts[agent_id] = (
            self.failure_counts.get(agent_id, 0) + 1
        )

        if self.failure_counts[agent_id] >= self.max_retries:
            self._activate_circuit_breaker(agent_id)
            return {
                "action": "reroute",
                "reason": "circuit_breaker_activated",
                "alternative": self._find_alternative_agent(agent_id),
            }

        return {
            "action": "retry",
            "reason": error,
            "retry_count": self.failure_counts[agent_id],
            "delay": min(2 ** self.failure_counts[agent_id], 60),
        }

    def _activate_circuit_breaker(self, agent_id: str) -> None:
        """Temporarily disable an agent (1-minute cooldown)."""
        self.circuit_breakers[agent_id] = time.time() + 60

    def _find_alternative_agent(self, failed_agent: str) -> str:
        """Find an alternative agent to handle the task.

        In production, check agent capabilities and availability.
        """
        return "default_backup_agent"

    def is_available(self, agent_id: str) -> bool:
        """Check if an agent is available (circuit breaker not active)."""
        if agent_id in self.circuit_breakers:
            if time.time() < self.circuit_breakers[agent_id]:
                return False
            del self.circuit_breakers[agent_id]
            self.failure_counts[agent_id] = 0
        return True

    def record_success(self, agent_id: str) -> None:
        """Record a successful task completion, resetting failure count."""
        self.failure_counts[agent_id] = 0


# ---------------------------------------------------------------------------
# Demo / CLI entry point
# ---------------------------------------------------------------------------


if __name__ == "__main__":
    print("=== Multi-Agent Coordination Demo ===\n")

    # 1. Communication channel
    comm = AgentCommunication()
    print("1. Created communication channel")

    # 2. Supervisor pattern
    supervisor = SupervisorAgent("supervisor", comm)
    supervisor.register_worker("researcher", ["search", "analyze"])
    supervisor.register_worker("writer", ["synthesize", "draft"])
    print("2. Registered supervisor with 2 workers: researcher, writer")

    # 3. Handoff protocol
    protocol = HandoffProtocol(comm)
    handoff_msg = protocol.create_handoff(
        from_agent="researcher",
        to_agent="writer",
        context={"findings": ["item1", "item2"]},
        reason="research_complete",
    )
    comm.send(handoff_msg)
    received = protocol.accept_handoff("writer")
    print(
        f"3. Handoff from researcher -> writer: "
        f"{'accepted' if received else 'none pending'}"
    )

    # 4. Consensus mechanism
    consensus = ConsensusManager()
    consensus.initiate_vote("best_approach", ["agent_a", "agent_b", "agent_c"], ["A", "B"])
    consensus.submit_vote("best_approach", "agent_a", "A", confidence=0.9)
    consensus.submit_vote("best_approach", "agent_b", "B", confidence=0.6)
    consensus.submit_vote("best_approach", "agent_c", "A", confidence=0.8)
    result = consensus.calculate_weighted_consensus("best_approach")
    print(
        f"4. Consensus result: {result['result']} "
        f"(strength: {result['consensus_strength']:.2f})"
    )

    # 5. Failure handling
    handler = AgentFailureHandler(comm, max_retries=3)
    action1 = handler.handle_failure("flaky_agent", "task_1", "timeout")
    action2 = handler.handle_failure("flaky_agent", "task_1", "timeout")
    action3 = handler.handle_failure("flaky_agent", "task_1", "timeout")
    print(f"5. After 3 failures: action={action3['action']}")
    print(f"   Agent available? {handler.is_available('flaky_agent')}")

    print("\n=== Demo Complete ===")
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall