World2Agent

World2Agent (W2A) is an open perception protocol designed specifically for AI Agents, built on the philosophy that "MCP gives hands — W2A gives ears." By defining a unified W2ASignal data envelope, the project standardizes events from various data sources (news, finance, GitHub, weather, etc.), enabling Agents to consume structured signals directly without adapting to underlying Sensor differences.

Protocol & Data Model#

• Unified Signal Contract: All Sensors follow the same W2ASignal Schema, allowing Agents to consume signals without adapting to different data source variations.
• High-Fidelity Envelope Structure: Includes signal_id (UUID for deduplication & tracing), dual timestamps (emitted_at / occurred_at, UTC ms), three-segment event naming (domain.entity.action, e.g., repo.issue.opened), natural language summary, self-describing raw data (source_event with schema + data), and flexible attachments (attachments, inline or reference-based).
• Decentralized Extension Mechanism: source_type, event.type, and mime_type are all OPEN sets requiring no central registry; the _meta field supports experimental extensions, and consumers must ignore unknown keys.
• Protocol Versioning: Current version is w2a/0.1; directory names correspond to PROTOCOL_VERSION; breaking changes bump the directory, incremental changes modify in place.

Architecture#

Core data flow: World → Sensor → Agent

• Protocol Layer: Core is schema/0.1/schema.ts, using self-contained TypeScript (no runtime dependencies) to define the wire format, with schema.json generated via typescript-json-schema.
• Transport Layer: The protocol is deliberately transport-agnostic, not defining specific transport frames — each runtime implementation wraps its own (stdio, HTTP POST, WebSocket, etc.).
• Sensor Layer: Standard npm packages that monitor data sources via polling or webhooks, outputting unified W2ASignal.
• Bridge Layer: Runtime adapters (e.g., hermes-sensor-bridge, openclaw-sensor-bridge) that bridge Sensor signals to specific Agent frameworks.
• Graph Layer (Roadmap): Planned support for composing and enriching multi-sensor signals before delivery to Agents.

Sensor Ecosystem & Distribution#

• Sensors as npm Packages: Each sensor is a standard npm package discoverable via npm search w2a-sensor, installable with a single command.
• Official SensorHub Directory: Organized across 9 categories (messaging / calendar / finance / research / social / dev / infra / data / custom), showcasing signal Schemas and one-click install commands.
• Meta-Sensor Support: Supports meta-sensors that monitor new W2A Sensor releases on npm (e.g., @quill-io/sensor-w2a-registry).
• AI-Assisted Toolchain: The build-w2a-sensor skill guides AI coding Agents through discovery → signal design → scaffolding → install recipe, publishing a new Sensor in ~50 lines of code.

Runtime Compatibility#

• Claude Code: Installed via Plugin mechanism (/plugin marketplace add + /world2agent:sensor-add).
• Hermes: Via @world2agent/hermes-sensor-bridge npm package + Skill mechanism.
• OpenClaw: Via @world2agent/openclaw-sensor-bridge npm package + Skill mechanism.
• Custom Agents: SDK developer quick-start path provided.

Typical Use Cases#

• Information Monitoring: Hacker News trending posts, frontier AI lab blog auto-push (@world2agent/sensor-hackernews, @quill-io/sensor-frontier-ai-news).
• Financial Alerting: Polymarket prediction market odds threshold triggers (@quill-io/sensor-polymarket), FX pair target price alerts (@juliapupu/sensor-fx-frankfurter).
• Developer Tools: GitHub repo Star growth monitoring, milestone tracking (@quill-io/sensor-github-stars).
• Lifestyle Info: Global city weather forecasts + astronomical moments (@juliapupu/sensor-weather-everywhere).
• Perception-Driven Automation: Bug detection → Agent auto-creates fix PRs; Steam free games/sales → Agent auto-claims.

Security Model#

Sensor signals directly drive Agent perception and action, so the security model relies on "only install trusted Sensors" — untrusted Sensors are equivalent to untrusted instruction sources. Hermes / OpenClaw require enabling the webhook platform and restarting the gateway on first Sensor Bridge installation. OpenClaw supports auto-pushing Agent responses to Feishu / iMessage / Telegram and other chat platforms.