Implement mailbox-based multi-agent coordination system in societies

[Copilot]

Implements a mailbox-based multi-agent system where agents coordinate through asynchronous message passing. Agents discover collaborators, send/receive messages, and process tasks autonomously without direct state access.

Core Components

MailboxSociety - Central coordinator managing agent registry, message routing, and processing loop

• Message router with per-agent queues (deque-based mailboxes)
• Agent discovery registry with capability-based search
• Async processing loop with run()/run_async() entry points supporting initial messages
• Lifecycle controls: stop, pause, resume, reset
• Defaults: infinite iterations, 0.1s process interval

MailboxToolkit - Message operations as FunctionTools

• send_message(), receive_messages(), check_messages(), peek_messages(), get_available_agents()
• Shared message_router reference for society-wide coordination

AgentDiscoveryToolkit - Agent discovery as FunctionTools

• list_all_agents(), search_agents_by_capability/tag/description(), get_agent_details(), get_my_info()
• Shared agent_cards registry for discovery

AgentCard - Agent metadata describing capabilities, tags, description

MailboxMessage - Message envelope with sender/recipient IDs, content, subject, timestamp

Architecture

# Setup
society = MailboxSociety("Team")
agent = ChatAgent(
    system_message=...,
    model=...,
    tools=[
        *MailboxToolkit(agent_id, society.message_router).get_tools(),
        *AgentDiscoveryToolkit(agent_id, society.agent_cards).get_tools()
    ]
)
society.register_agent(agent, AgentCard(...))  # Validates unique ID, creates mailbox

# Autonomous coordination
await society.run_async(
    initial_messages={"manager": "Research AI safety in healthcare"}
)
# Agents discover collaborators, exchange messages, coordinate autonomously

Key Design Decisions

• Message-based isolation: Agents never directly access each other's state
• FunctionTool integration: Toolkits return standard FunctionTools for ChatAgent compatibility
• Default handler: Uses ChatAgent.step() when no custom handler specified
• Atomic registration: Agent, card, and mailbox created together with uniqueness validation
• Async-first: Built on asyncio with ThreadPoolExecutor fallback for sync interface

Examples

• mailbox_society_example.py - Basic toolkit API usage
• mailbox_coordination_async_example.py - Autonomous multi-agent workflow (recommended)
• default_handler_example.py - ChatAgent.step() integration
• mailbox_society_processing_example.py - Custom message handlers

Testing

Comprehensive test coverage (1000+ lines):

• Message/card/society creation and operations
• Toolkit FunctionTool generation
• Discovery and search functionality
• Async processing loop and lifecycle controls
• Default handler behavior
• Initial messages support
• Registration validation (uniqueness, mailbox creation)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature Request] Research and implement a mailbox based multi-agent system in societies based on ChatAgent</issue_title>
<issue_description>### Required prerequisites

• I have searched the Issue Tracker and Discussions that this hasn't already been reported. (+1 or comment there if it has.)
• Consider asking first in a Discussion.

Motivation

Research and implement a mailbox based multi-agent system in societies based on ChatAgent.

Core idea is each agent can receive and send messages to arbitrary agents. The mailbox can be implemented as a toolkit. Need to consider how to entry and terminate. Each agent should something like an agent card to describe what are their capability and how to send messages to them and each agent should how a skill to discove other agents use SkillToolkit.

Each agent has:

A mailbox (message queue)

An internal state

A behavior loop: receive → step → send messages

Agents never directly touch each other’s state. All coordination happens through messages.

Solution

No response

Alternatives

No response

Additional context

No response</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Feature Request] Research and implement a mailbox based multi-agent system in societies based on ChatAgent #3806

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.