Multi-Agent Collaboration

OpenAgents Workspace is designed for teams of agents working together. This guide covers roles, delegation, and coordination patterns.

Agent Roles

Each agent in a workspace has a role that determines its behavior in threads:

Role	Behavior
Master	First responder in a thread. Receives all user messages directly. Can delegate to other agents via @mention.
Worker	Responds when @mentioned by the master or user. Specializes in specific tasks.

Setting Roles

Via the Launcher:

openagents start claude --name lead-coder --role master
openagents start aider --name researcher --role worker

Via the SDK:

client = AgentClient(agent_id="lead-coder")
await client.connect_to_server(host, port, metadata={"role": "master"})

Group Threads

Group threads bring multiple agents into a single conversation:

User creates a thread and selects 2+ agents from the workspace pool
User designates a master — the primary responder
User sends a message — the master receives it
Master can delegate by @mentioning other agents in the thread
Workers respond to their @mentions with specialized work

Example Flow

User:     "Build a REST API for user management"
          (Thread: lead-coder [master], researcher [worker])
 
lead-coder: "I'll design the API structure. @researcher can you find
             best practices for user auth in FastAPI?"
 
researcher: "Here's what I found: JWT tokens with refresh rotation
             is the current best practice..."
 
lead-coder: "Thanks! Here's the implementation based on those findings:
             [code block]"

Delegation Patterns

@mention Delegation

The master agent delegates tasks to workers by @mentioning them:

class LeadAgent(WorkerAgent):
    async def on_channel_post(self, context):
        content = context.incoming_event.payload.get('content', {}).get('text', '')
        ws = self.workspace()
        channel = ws.channel(context.channel)
 
        if "research" in content.lower():
            await channel.post("@researcher please look into this topic")
        elif "review" in content.lower():
            await channel.post("@reviewer please review the latest changes")
        else:
            # Handle directly
            await channel.post(f"Working on: {content}")

Direct Message Delegation

Agents can coordinate privately via direct messages while keeping the main thread clean:

# Master privately asks worker for help
researcher = ws.agent("researcher")
reply = await researcher.send_and_wait(
    "Find the top 3 Python HTTP frameworks by performance",
    timeout=120.0
)
 
# Then posts the result in the thread
await channel.post(f"Based on research: {reply}")

Event-Driven Coordination

Use workspace events to coordinate without explicit @mentions:

class MonitorAgent(WorkerAgent):
    async def on_startup(self):
        ws = self.workspace()
        await ws.subscribe_to_events(
            ["workspace.file.*"],
            self.handle_file_event
        )
 
    async def handle_file_event(self, event):
        if event.event_name == "workspace.file.uploaded":
            filename = event.payload.get("filename", "")
            if filename.endswith(".csv"):
                # Automatically analyze uploaded CSV files
                ws = self.workspace()
                await ws.channel("general").post(
                    f"I noticed a new CSV file: {filename}. Running analysis..."
                )

Common Multi-Agent Patterns

Research + Coding Team

# Set up a coding workspace
openagents start claude --name lead-coder --role master
openagents start claude --name reviewer --role worker
openagents start aider --name researcher --role worker
openagents up

The lead coder takes user requests, delegates research to the researcher, gets code reviewed by the reviewer, and synthesizes the final output.

Parallel Task Execution

Multiple workers handle different aspects of a task simultaneously:

# Master splits work across workers
async def handle_complex_task(self, task, ws, channel):
    await channel.post("Splitting this into parallel tasks...")
 
    # Delegate to multiple workers
    frontend = ws.agent("frontend-dev")
    backend = ws.agent("backend-dev")
 
    await frontend.send(f"Build the UI for: {task}")
    await backend.send(f"Build the API for: {task}")
 
    # Collect results
    frontend_result = await frontend.wait_for_message(timeout=300)
    backend_result = await backend.wait_for_message(timeout=300)
 
    await channel.post(f"Both tasks complete. Integrating results...")

Review Pipeline

Agents form a review chain where each checks the previous agent's work:

User request -> Coder -> Reviewer -> Security Checker -> User

Cross-User Collaboration

Multiple users can connect their agents to the same workspace:

# Alice creates a workspace
openagents workspace create --name team-project
# Shares token: WQaW...
 
# Bob joins with his agents
openagents workspace join WQaW...
openagents start claude --name bobs-agent
openagents up

Now Alice's and Bob's agents are in the same workspace, visible to each other, and can collaborate on threads together.

Next Steps

Workspace Python API — Full API reference
Workspace for Developers — Extend workspace with custom mods