| name | a2a-messaging |
| description | Agent-to-Agent (A2A) messaging system for direct communication between Cloud and Local agents. Replaces file-based handoffs with real-time messaging while maintaining vault as audit record. Supports task delegation, status updates, approval requests, and result delivery between distributed AI Employee instances. Use when coordinating multiple Claude Code agents across cloud and local environments. |
A2A Messaging System
Overview
The A2A (Agent-to-Agent) Messaging skill provides a direct communication layer between Cloud and Local Claude Code agents. It replaces file-based handoffs with structured messages while preserving the Obsidian vault as the authoritative audit record. This is the Platinum Phase 2 requirement for the Personal AI Employee project.
Architecture
Agents
- Cloud Agent: Runs on cloud infrastructure. Owns email triage, social media draft generation, calendar analysis, and research tasks. Produces drafts and recommendations but never performs sensitive actions directly.
- Local Agent: Runs on the user's local machine. Owns WhatsApp sessions, payment approvals, bank interactions, final email sends, social media posting, and Dashboard.md updates. Has access to local credentials and sensitive sessions.
Message Broker
The A2AMessageBroker sits between agents and handles:
- Message queue management (per-agent inboxes)
- Transport abstraction (file-based or Redis)
- Message deduplication and TTL enforcement
- Dead letter queue for undeliverable messages
- Vault audit trail writing
Transport Layers
- File-based transport (default): Messages written as JSON files to shared vault directories under
/Messages/outbox/ and /Messages/inbox/. Compatible with git-based vault sync.
- Redis transport (optional): Pub/sub channels for real-time delivery. Requires Redis server. Falls back to file-based if Redis is unavailable.
Message Types
| Type | Direction | Description |
|---|
task_delegation | Cloud -> Local or Local -> Cloud | Delegate a task to the other agent |
approval_request | Cloud -> Local | Request human approval for a sensitive action |
approval_response | Local -> Cloud | Respond to an approval request |
status_update | Either direction | Report progress on an ongoing task |
result_delivery | Either direction | Deliver completed task results |
heartbeat | Either direction | Health check signal |
error | Either direction | Report an error condition |
Message Priority
- CRITICAL: Requires immediate processing (e.g., security alerts)
- HIGH: Process within minutes (e.g., approval requests)
- NORMAL: Standard processing queue
- LOW: Background tasks, can be deferred
Security Rules
- No secrets in messages: Messages are scanned for API keys, tokens, passwords, and credential patterns before sending. Any message containing detected secrets is rejected.
- Vault as audit trail: Every message is written to the vault as a markdown file under
/Updates/ or /Signals/ for full auditability.
- Claim-by-move: The first agent to move a file from
/Needs_Action/ to /In_Progress/<agent>/ owns that task. No concurrent claims.
- Single-writer for Dashboard.md: Only the Local agent may write to
Dashboard.md to prevent merge conflicts.
- Security filter on sync:
.env files, token stores, WhatsApp session data, and banking credentials are never synced between agents.
Vault Audit Trail
Every A2A message generates a vault entry:
/Updates/a2a-messages/YYYY-MM-DD/
{timestamp}-{message_type}-{sender}-{message_id_short}.md
The markdown file contains:
- YAML frontmatter with message metadata
- Human-readable summary of the message content
- Correlation chain (links to related messages)
Configuration
Environment variables:
A2A_AGENT_ROLE: "cloud" or "local" (required)A2A_VAULT_PATH: Path to the shared Obsidian vault (required)A2A_TRANSPORT: "file" or "redis" (default: "file")A2A_REDIS_URL: Redis connection URL (required if transport is "redis")A2A_HEARTBEAT_INTERVAL: Seconds between heartbeats (default: 60)A2A_MESSAGE_TTL: Default message TTL in seconds (default: 3600)A2A_DRY_RUN: If "true", messages are logged but not sent (default: "false")
CLI Usage
python cli.py send --type task_delegation --to local --payload '{"task": "approve_payment", "amount": 150.00}'
python cli.py receive --limit 10
python cli.py status
python cli.py sync
python cli.py heartbeat
File Structure
.claude/skills/a2a-messaging/
SKILL.md # This file
scripts/
a2a_messaging.py # Core messaging system
message_router.py # Message routing and transport
vault_sync.py # Vault synchronization
cli.py # Command-line interface
assets/
requirements.txt # Python dependencies
references/ # Reference materials
Integration Points
- Orchestrator Engine: The orchestrator can use A2A messaging to coordinate cross-agent workflows.
- Watchdog Process Manager: Monitors agent health via heartbeat messages.
- Audit Logging System: All messages are logged through the audit system.
- Finance Watcher: Payment approvals flow through A2A approval_request/response.
- Gmail Watcher: Email triage results sent as task_delegation from Cloud to Local.
When NOT to Use This Skill
- Single-agent workflows — if only one Claude Code instance is running, A2A messaging adds unnecessary infrastructure; use direct tool calls instead
- Synchronous request-response patterns — A2A is designed for async task delegation; for immediate responses, use direct API calls
- Simple file handoffs between agents — if the shared vault already satisfies your coordination needs, adding the message broker is over-engineering
Common Mistakes
- Sending secrets (API keys, tokens) inside message payloads — the security filter will reject the message; pass only references or task identifiers
- Not setting a TTL on messages — stale messages accumulate in the dead letter queue and can confuse the receiving agent
- Using CRITICAL priority for non-urgent tasks — it starves genuinely critical messages and slows overall throughput
Related Skills
