World Agent Web (WAW)

A standardized ecosystem for AI agents to discover and interact with web services

Overview

World Agent Web (WAW) is an ecosystem of protocols enabling AI agents to discover and interact with web services through standardized manifests.

Think of it as: HTTP is to the World Wide Web what WAW is to the Agent Web.

WAW consists of three core protocols:

• HADP (HTTP Agent Discovery Protocol) - How agents find services
• ACDL (Agent Capability Description Language) - How services describe themselves
• AWCP (Agent-Web Communication Protocol) - How agents invoke services

Status: Proof of Concept (Community Validation Phase)

Key Features

• Automatic Discovery: Services expose capabilities via standard manifest files
• Type Safety: JSON Schema validation for inputs and outputs
• Protocol Agnostic: Works over standard HTTP/HTTPS
• Error Handling: Consistent error response format
• Self-Describing: Services document their own capabilities

Architecture Overview

Use Cases

• AI agents booking restaurants, flights, or services
• Multi-agent orchestration across web services
• Automated service integration and composition
• Agent-to-web communication standardization

The Problem Today

Currently, AI agents access web services through:

• Web search → Generic search results, unstructured
• HTML scraping → Fragile, breaks when sites change
• Hardcoded integrations → Custom code for each service

This doesn't scale. Every new service requires custom integration.

The WAW Solution

Services expose self-describing manifests with:

• Available capabilities (what they can do)
• Type-safe schemas (inputs/outputs)
• Standard invocation format (how to call them)

Agents discover and use services without hardcoded integrations.

Before WAW: Agent → Web Search → Parse HTML → Hope it works With WAW: Agent → Fetch Manifest → Validate → Invoke (guaranteed to work)

Quick Start

Installation

# Clone repository
git clone https://github.com/Fredbcx/waw.git
cd waw

# Install dependencies
pip install -r requirements.txt

See It In Action

Autonomous Agent Demo:

cd demo
pip install -r requirements.txt
cp .env.example .env
# Add your ANTHROPIC_API_KEY
python run_demo.py

→ See example output - Complete autonomous workflow

Live Dashboard: https://web-production-73c2.up.railway.app/demo

Testing & Demo

Option 1: Autonomous Agent Demo (Recommended)

Watch Claude autonomously discover and use services:

Prerequisites:

• Anthropic API key (get one here)
• Python 3.8+

Setup:

# 1. Install dependencies
cd demo
pip install -r requirements.txt

# 2. Configure
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

# 3. Run demo
python run_demo.py

The agent will:

1. Discover services from the live server
2. Check weather in Milan
3. Search for Italian restaurants
4. Make a dinner reservation

Live Server: https://web-production-73c2.up.railway.app

---

Option 2: Test with Production Server (curl)

Test live services directly:

# Discover manifest
curl https://web-production-73c2.up.railway.app/agent-manifest.json | jq

# Get weather
curl -X POST https://web-production-73c2.up.railway.app/api/agent/weather-service/current-weather \
  -H "Content-Type: application/json" \
  -d '{"params": {"city": "Milan"}}' | jq

# Search restaurants
curl -X POST https://web-production-73c2.up.railway.app/api/agent/booking-service/search-restaurants \
  -H "Content-Type: application/json" \
  -d '{"params": {"cuisine": "Italian"}}' | jq

See API_REFERENCE.md for complete examples.

---

Option 3: Local Development Server

Run services locally for development:

# 1. Start server
cd src/server
python server.py
# Server runs at http://localhost:5000

# 2. In another terminal, run client demo
cd src/examples
python enhanced_demo.py

---

Option 4: PowerShell Testing Scripts (Windows)

Automated test suites for Windows:

# Test all services
.\scripts\test_all_services.ps1

Example: Weather Service

from src.client.client import WAWClient

client = WAWClient()

# Discover service capabilities
manifest = client.discover_manifest('http://localhost:5000')

# Find weather agent
weather_agent = client.find_agent_by_id(manifest, 'weather-service')

# Invoke capability
response = client.invoke_capability(
    agent=weather_agent,
    capability_id='current-weather',
    params={'city': 'London', 'units': 'metric'}
)

print(response['result'])
# Output: {'city': 'London', 'temperature': 15.5, 'description': 'partly cloudy', ...}

Architecture

┌─────────────────┐         ┌──────────────────┐
│   AI Agent      │         │   Web Service    │
│   (Client)      │         │   (Server)       │
│                 │         │                  │
│  1. Discovery   │────────>│  Manifest        │
│                 │  GET    │  /agent-manifest │
│                 │         │                  │
│  2. Validation  │         │                  │
│     (Schema)    │         │                  │
│                 │         │                  │
│  3. Invocation  │────────>│  Service         │
│                 │  POST   │  Endpoint        │
│                 │         │                  │
│  4. Response    │<────────│  Result/Error    │
└─────────────────┘         └──────────────────┘

Components

1. Agent Manifest

Services expose a JSON manifest describing their capabilities:

{
  "version": "1.0",
  "metadata": {
    "name": "Weather Service",
    "description": "Provides weather information"
  },
  "agents": [
    {
      "id": "weather-service",
      "type": "query",
      "capabilities": [
        {
          "id": "current-weather",
          "input_schema": {...},
          "output_schema": {...}
        }
      ]
    }
  ]
}

2. Discovery Protocol

Agents discover services by requesting manifests from standard locations:

1. https://example.com/agent-manifest.json
2. https://example.com/.well-known/agent-manifest.json

3. Invocation Protocol

Agents invoke capabilities via HTTP POST with standardized request format:

POST /api/agent/{agent-id}/{capability-id}
Content-Type: application/json
X-WAW-Version: 1.0

{
  "params": {
    "city": "London"
  }
}

Example Services

This repository includes working examples:

• Echo Service: Simple demonstration of protocol basics
• Calculator Service: Mathematical operations
• Weather Service: Real-world API integration (OpenWeatherMap)
• Booking Service: Stateful operations (restaurant reservations)

See docs/EXAMPLES.md for detailed documentation.

WAW vs Alternatives

vs Model Context Protocol (MCP)

• MCP: Local desktop application integration, direct tool access
• WAW: Web service integration, HTTP-based discovery
• Relationship: Complementary. MCP tools can wrap WAW services.

vs A2A (Agent-to-Agent)

• A2A: Agent-to-agent collaboration (peer-to-peer)
• WAW: Agent-to-service invocation (client-server)
• Relationship: Complementary. A2A agents can use WAW services.

vs Custom APIs

• Custom APIs: Each service has unique format
• WAW: Standardized discovery and invocation format
• Benefit: Agents work with any WAW service without custom integration

vs Function Calling (OpenAI/Claude)

• Function Calling: Client-side function definitions
• WAW: Server-side capability discovery
• Benefit: Services self-describe, agents discover dynamically

See docs/COMPARISON.md for detailed analysis.

Future: Service Discovery at Scale

As WAW adoption grows, the ecosystem will naturally evolve:

Registry Services (Inevitable)

Just as the web needed search engines after HTTP, WAW will need registries:

• Index of available WAW services
• Search by capability type
• Quality rankings and reviews
• Standardized discovery endpoint

Note: WAW is registry-agnostic. Any organization can operate a registry. The protocols enables the ecosystem; registries make it discoverable at scale.

Advanced Use Cases

• Micropayments (x402): Services charge per invocation automatically
• Multi-agent orchestration: Agents compose multiple services into workflows
• Cross-platform integration: Desktop (MCP) + Web (WAW) unified experience

Documentation

• Technical Specification - Formal definition
• Architecture Guide - System design and components
• Examples Documentation - Realistic service examples
• API Reference - Testing guide with curl examples
• FAQ - Frequently asked questions

Project Status

Current Phase: Community Validation

We are seeking feedback on:

• Design and specification
• Implementation patterns
• Use cases and applications
• Integration with existing systems

Roadmap

• Core specification
• Reference implementation (Python)
• Realistic examples (Weather, Booking)
• Community feedback and iteration
• Additional language implementations
• Production deployment patterns
• Registry/directory service

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Areas for Contribution

• Additional service examples
• Client library implementations (JavaScript, Go, Rust)
• Documentation improvements
• Testing and validation
• Security analysis

Use Cases

For AI Agent Developers

Build agents that can:

• Discover and use any WAW-compliant service
• Compose multiple services into workflows
• Operate without hardcoded integrations

For Service Providers

Enable AI agent integration by:

• Publishing a standard manifest
• Implementing WAW-compliant endpoints
• Joining the WAW ecosystem

For Platform Builders

Create agent platforms that:

• Support automatic service discovery
• Provide type-safe service invocation
• Enable multi-service orchestration

Technical Details

Version: 1.0
Transport: HTTP/HTTPS
Format: JSON
Validation: JSON Schema
Authentication: Pluggable (None, API Key, OAuth2, JWT)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [chiaradiafederico0@gmail.com]

Acknowledgments

Inspired by the need for standardized agent-to-web communication in the era of AI agents.

---

Note: This is a proof of concept seeking community validation. The ecosystem may evolve based on feedback.