Problem

Complex workflows require multiple specialized agents (PM, Architect, Engineer, QA) to collaborate. Currently, inter-agent communication requires workarounds:

1. Orchestrator as bottleneck: All messages routed through main session
2. Shared files: Agents write to /tmp/agent-comms/messages.jsonl (race conditions, polling overhead)
3. sessions_send: Direct but requires knowing session labels, no pub/sub

These patterns don't scale for parallel agent workflows.

Proposed Solution

Native agent-to-agent messaging with pub/sub semantics, inspired by Google's A2A protocol.

API Surface

// Agent subscribes to topics
agent.subscribe('spec-approved', async (event) => {
  if (event.spec_id === 'dark-mode') {
    await startImplementation(event);
  }
});

// Another agent publishes
agent.publish('spec-approved', { 
  spec_id: 'dark-mode', 
  version: '1.0',
  approved_by: 'pm-agent'
});

CLI/Tool Equivalents

# Subscribe (blocking, streams events)
openclaw agent subscribe spec-approved --format json

# Publish
openclaw agent publish spec-approved --data '{"spec_id": "dark-mode"}'

# List active subscriptions
openclaw agent subscriptions

Tool Call (from agent session)

{
  "tool": "agent.publish",
  "params": {
    "topic": "spec-approved",
    "data": { "spec_id": "dark-mode" }
  }
}

{
  "tool": "agent.subscribe",
  "params": {
    "topics": ["code-review-needed", "deployment-ready"]
  }
}

Use Cases

1. Parallel Feature Development

• Orchestrator spawns 3 Engineer agents for 3 features
• Each publishes implementation-complete when done
• QA agent subscribed to implementation-complete, starts testing automatically

2. Incident Response Pipeline

• Ops agent detects anomaly, publishes incident-detected
• Engineer agent auto-spawns on incident-detected, starts investigation
• No human intervention needed for initial triage

3. Spec Approval Workflow

• PM agent publishes spec-draft-ready
• Architect agent reviews, publishes spec-approved or spec-needs-revision
• Engineer agent only starts on spec-approved

Benefits

• Decoupled agents: Don't need to know each other's session IDs
• Event-driven: Reactive, not polling
• Parallelism: Multiple agents can work simultaneously
• Audit trail: All messages logged for debugging

Implementation Considerations

• Message persistence: Store in Redis pub/sub or PostgreSQL for durability?
• Tenant isolation: Topics scoped to agent/tenant
• Rate limiting: Prevent agent message storms
• Dead letter queue: Handle messages when subscriber is offline

Prior Art

• Google A2A Protocol
• Redis Pub/Sub
• Apache Kafka topics
• NATS messaging

Context

Building a multi-agent system for product management where PM, Architect, Engineer, QA, and Ops agents need to coordinate. Current workarounds are fragile and don't scale.

See: Full multi-agent architecture in AGENTS.md pattern at #12333 (comment)...