ASP Domain Samples

Reference implementations of the Agentic Services Protocol (ASP) across three independent domain verticals, each with an AI-powered client agent and real-time protocol inspector.

Domains

Domain	Directory	Server Port	Client Port	Description
Food Delivery	food_delivery/	8000	8001	Restaurant discovery, menu browsing, ordering with modifiers, live delivery tracking
Ride Hailing	ride_hailing/	8002	8003	Ride provider search, vehicle selection, ride booking, live driver tracking
Travel Booking	travel/	8004	8005	Accommodation search, room comparison, reservation with meal plans, booking status

Each domain is fully independent — its own models, database, seed data, agent, and UI. No shared code between domains. You can run any domain individually or multiple simultaneously.

Architecture

All three domains share the same two-process architecture:

Browser (client port)  ──▶  Client Agent  ──HTTP──▶  ASP Server (server port)
  Chat UI                     OpenAI GPT-4o            /.well-known/asp
  POST /chat                  + ASP tool calling        /discovery/search
  WS /ws/inspector            agentic loop              /catalog/{id}/catalog
                                                        /checkouts
                                                        /orders/{id}/tracking
                                                        /orders/{id}/tracking/stream (WS)
                                                        /personalization/*
                                                        /reviews/*
                                                        /catalog/reorder

• ASP Server — The merchant platform. A pure ASP API with no chat logic or AI.
• Client Agent — The consumer's AI assistant. Discovers the ASP server's capabilities, then uses OpenAI function calling to interact with ASP endpoints.

Quick Start

# Install
pip install -e .

# Add your OpenAI API key to .env
echo "OPENAI_API_KEY=your-key-here" > .env

# Run a domain (default: food_delivery)
./run.sh food_delivery   # http://localhost:8001
./run.sh ride_hailing    # http://localhost:8003
./run.sh travel          # http://localhost:8005

Or run directly from a domain directory:

./food_delivery/run.sh
./ride_hailing/run.sh
./travel/run.sh

Press Ctrl+C to stop.

Environment Variables

Configure via .env in the project root:

Variable	Required	Default	Description
OPENAI_API_KEY	Yes	—	Your OpenAI API key
OPENAI_MODEL	No	gpt-4o	Model to use for the agent
ASP_SERVER	No	varies per domain	ASP server URL

Project Structure

asp-samples/
├── .env                          # Shared environment variables
├── pyproject.toml                # Dependencies
├── run.sh                        # Top-level launcher
│
├── food_delivery/                # Food Delivery
│   ├── server/                   # ASP Server (4 restaurants, menus, modifiers)
│   │   ├── routers/              # well_known, discovery, catalog, checkout,
│   │   │                         #   tracking, personalization, reviews, streaming
│   │   ├── models.py             # Pydantic models (incl. granular food statuses)
│   │   ├── seed.py               # 4 providers, reviews, time slots
│   │   └── database.py           # SQLite (checkouts, orders, reviews)
│   ├── client/                   # AI Agent (restaurant search, ordering)
│   ├── static/                   # Chat UI
│   ├── happy_path.py             # 12-step headless test
│   └── run.sh                    # Ports 8000/8001
│
├── ride_hailing/                 # Ride Hailing
│   ├── server/                   # ASP Server (4 providers, vehicles, ride extras)
│   │   ├── routers/              # Same router structure as food_delivery
│   │   ├── models.py             # Pydantic models (surge pricing, vehicle features)
│   │   ├── seed.py               # 4 providers, reviews, time slots
│   │   └── database.py           # SQLite (checkouts, orders, reviews)
│   ├── client/                   # AI Agent (ride search, booking)
│   ├── static/                   # Chat UI
│   ├── happy_path.py             # 12-step headless test
│   └── run.sh                    # Ports 8002/8003
│
└── travel/                       # Travel Booking
    ├── server/                   # ASP Server (6 accommodations, rooms, meal plans)
    │   ├── routers/              # Same router structure as food_delivery
    │   ├── models.py             # Pydantic models (room types, amenities)
    │   ├── seed.py               # 6 providers, reviews, check-in slots
    │   └── database.py           # SQLite (checkouts, orders, reviews)
    ├── client/                   # AI Agent (hotel search, reservation)
    ├── static/                   # Chat UI
    ├── happy_path.py             # 12-step headless test
    └── run.sh                    # Ports 8004/8005

ASP Capabilities

All three domains implement the same ASP capabilities:

Capability	Endpoints
dev.asp.services.discovery	POST /discovery/search (paginated)
dev.asp.services.catalog	GET /catalog/{id}/catalog, POST /catalog/reorder
dev.asp.services.fulfillment	POST /checkouts, PATCH /checkouts/{id}, POST /checkouts/{id}/complete
dev.asp.services.order_tracking	GET /orders/{id}/tracking, POST /orders/{id}/tracking/_advance
dev.asp.services.personalization	GET /personalization/profile, GET /personalization/promotions
dev.asp.services.reviews	POST /reviews, GET /reviews/{provider_id} (paginated)
dev.asp.services.streaming	WS /orders/{id}/tracking/stream

New in v0.2.0

• Itemized fees — Delivery, service, small order, surge, and booking fees broken out in fulfillment.fees[]
• Tipping — Default tip with percentage and fixed amount support
• Operating hours — 7-day schedule on all providers with next_opens_at
• Image types — Thumbnail and banner images on providers and catalog items
• Rating count — rating_count alongside rating for confidence context
• Pagination — Discovery search and reviews return pagination objects
• Status history — Full timeline in history[] on tracking responses
• Delay detection — is_delayed and delay_minutes on tracking
• Granular statuses — Food delivery maps 10 granular statuses to 5 base statuses
• Scheduled fulfillment — available_time_slots and scheduled_for support
• Reviews — Submit and retrieve paginated reviews with category scores
• Reorder — Re-order from previous orders with availability checking
• WebSocket streaming — Real-time tracking with status changes, location updates, and heartbeats

Headless Tests

Each domain has a happy_path.py that runs a 12-step end-to-end test against the ASP server:

# Start the server first, then in another terminal:
python food_delivery/happy_path.py    # Tests against localhost:8000
python ride_hailing/happy_path.py     # Tests against localhost:8002
python travel/happy_path.py           # Tests against localhost:8004

The 12 steps cover: protocol discovery, user profile, promotions, paginated provider search, catalog browsing, checkout with fees/tips, fulfillment update, order completion, tracking with history, reorder, review submission, and review retrieval.

Seed Data

Food Delivery

Restaurant	Cuisine	Rating	Reviews	Price
Bella Napoli	Italian, Pizza	4.7	3,150	Moderate
Sakura Garden	Japanese, Sushi	4.5	2,100	Moderate
Pizza Palace	Pizza, American	4.2	890	Budget
Tokyo Ramen	Japanese	4.8	1,750	Moderate

User: Alex Nguyen, Gold tier, 3,240 points

Ride Hailing

Provider	Categories	Rating	Reviews	Price
CityRide	Economy, Sedan	4.3	8,420	Budget
LuxDrive	Sedan, SUV, Luxury	4.8	3,150	Premium
QuickPool	Pool, Economy	4.1	12,300	Budget
GreenWheels	Electric, Economy, Sedan	4.6	5,680	Moderate

User: Jordan Chen, Silver tier, 1,580 points

Travel Booking

Accommodation	Type	Rating	Reviews	Price
The Grand Marina Hotel	Hotel, 4-star	4.7	2,840	Premium
Coastal Villa Retreat	Villa	4.9	420	Luxury
Urban Hostel Hub	Hostel	4.2	6,350	Budget
Mountain Lodge & Spa	Resort, 5-star	4.8	1,560	Premium
Skyline Boutique Hotel	Boutique, 3-star	4.4	1,890	Moderate
Riverside Inn & Suites	Inn	4.5	980	Moderate

User: Mia Rodriguez, Gold tier, 5,120 points