myAI BDC DEVELOPER PORTAL
AI-powered product search, Agent-to-Agent protocol, and Parlay negotiation system
SYSTEM INITIALIZATION
$ # Quick Start Guide
$ curl -X POST /api/v1/products/search \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"buyerAgentId": "test-agent", "query": "summer shirts"}'
# Response: 200 OK - 6x more visible products found
$ # NEW: Parlay Negotiation
$ curl -X POST /api/v1/parlay/initiate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"productId": "prod_123", "initialOffer": 45.00}'
Available Protocols
- ▶ REST API - Traditional HTTP endpoints
- ▶ A2A Protocol - Agent-to-Agent communication
- ▶ Parlay Negotiation - AI-powered price negotiation NEW
- ▶ WebSocket - Real-time updates (coming soon)
AUTHENTICATION PROTOCOLS
The API supports two authentication methods:
Bearer Token
Authorization: Bearer YOUR_API_KEY
API Key Header
X-API-Key: YOUR_API_KEY
To obtain an API key, Contact Us
API ENDPOINTS
POST /products/search
AI-powered product search with natural language understanding
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
buyerAgentId |
string | Required | Unique identifier for the buyer agent |
query |
string | Optional | Natural language search query |
buyerAgentName |
string | Optional | Display name for the buyer agent |
filters |
object | Optional | Structured filters (category, price range, tags) |
context |
object | Optional | Additional buyer context and preferences |
enableParlay |
boolean | Optional | Enable Parlay negotiation for results |
GET /products/{productId}
Retrieve detailed product information
PUT /products/{productId}/view
Register product view for analytics
Response Schema
{
"products": [
{
"id": "prod_123",
"title": "Premium Summer Cotton Shirt - Breathable & Lightweight",
"description": "Experience ultimate comfort with our premium cotton shirt...",
"price": 49.99,
"currency": "USD",
"image": "{CDN_PATH}/products/shirt-123.jpg",
"url": "{STORE_PATH}/products/summer-cotton-shirt",
"merchant": {
"name": "Fashion Store",
"id": "merchant_456",
"verified": true
},
"relevanceScore": 0.95,
"tags": [
"summer",
"cotton",
"breathable"
],
"parlayEnabled": true,
"minParlayPrice": 42.49,
"variants": [
{
"id": "var_001",
"size": "M",
"color": "Ocean Blue",
"inventory": 15
}
]
}
],
"metadata": {
"totalResults": 42,
"aiMessage": "Found 42 products matching your summer shirt criteria",
"searchId": "search_789",
"processingTime": 127,
"confidence": 0.92,
"parlayAvailable": 28
}
}
PARLAY NEGOTIATION SYSTEM
Intelligent Price Negotiation
The Parlay system enables AI-powered price negotiations between buyer agents and merchants, creating win-win scenarios through intelligent bargaining.
POST /parlay/initiate
Start a new price negotiation session
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
productId |
string | Required | ID of the product to negotiate |
buyerAgentId |
string | Required | Buyer agent identifier |
initialOffer |
number | Required | Initial price offer |
context |
object | Optional | Negotiation context (bulk order, repeat customer, etc.) |
POST /parlay/{sessionId}/counter
Submit a counter-offer in an active negotiation
GET /parlay/{sessionId}/status
Check negotiation status and history
POST /parlay/{sessionId}/accept
Accept the current offer and finalize the deal
Parlay Response Example
{
"sessionId": "parlay_session_xyz",
"status": "negotiating",
"currentOffer": {
"price": 47.50,
"offerBy": "merchant",
"timestamp": "2024-01-15T14:30:00Z"
},
"negotiationHistory": [
{
"price": 45.00,
"by": "buyer",
"timestamp": "2024-01-15T14:28:00Z"
},
{
"price": 47.50,
"by": "merchant",
"timestamp": "2024-01-15T14:30:00Z",
"reasoning": "15% discount for bulk order of 10+ units"
}
],
"merchantLimits": {
"minPrice": 42.49,
"maxDiscount": 0.15
},
"aiAdvice": "Merchant seems willing to negotiate. Consider accepting or counter with $46.50",
"expiresAt": "2024-01-15T14:35:00Z"
}
AGENT-TO-AGENT PROTOCOL
myAI BDC implements the A2A v1.0 protocol for seamless agent communication
Supported Methods
- ▶ product.search - Natural language product discovery
- ▶ parlay.negotiate - Automated price negotiations NEW
- ▶ notification.subscribe - Subscribe to product updates
- ▶ merchant.info - Get merchant capabilities
A2A Request Format
{
"jsonrpc": "2.0",
"method": "parlay.negotiate",
"params": {
"productId": "prod_123",
"buyerAgentId": "agent_123",
"targetPrice": 45.00,
"strategy": "aggressive",
"context": {
"orderQuantity": 10,
"customerType": "repeat"
}
},
"id": 1
}
CODE EXAMPLES
// Initialize API client const API_ENDPOINT = '{YOUR_API_ENDPOINT}/api/v1'; const API_KEY = 'YOUR_API_KEY'; // Search for products with Parlay enabled const searchProducts = async (query, options = {}) => { try { const response = await fetch(`${API_ENDPOINT}/products/search`, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ buyerAgentId: 'my-agent-123', query: query, enableParlay: true, ...options }) }); if (!response.ok) { throw new Error(`API Error: ${response.status}`); } return await response.json(); } catch (error) { console.error('Search failed:', error); throw error; } }; // Initiate Parlay negotiation const startParlay = async (productId, initialOffer) => { const response = await fetch(`${API_ENDPOINT}/parlay/initiate`, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ productId: productId, buyerAgentId: 'my-agent-123', initialOffer: initialOffer, context: { orderQuantity: 10, customerType: 'new' } }) }); return await response.json(); }; // Example usage searchProducts('summer shirts') .then(async (results) => { const parlayProduct = results.products.find(p => p.parlayEnabled); if (parlayProduct) { const parlay = await startParlay(parlayProduct.id, parlayProduct.price * 0.85); console.log('Negotiation started:', parlay.sessionId); } });
import requests import json import asyncio from typing import Optional, Dict, Any # Configuration API_ENDPOINT = '{YOUR_API_ENDPOINT}/api/v1' API_KEY = 'YOUR_API_KEY' class BDCClient: def __init__(self, api_key: str): self.api_key = api_key self.headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } def search_products(self, query: str, enable_parlay: bool = True, filters: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: """Search for products with optional Parlay negotiation""" payload = { 'buyerAgentId': 'my-agent-123', 'query': query, 'enableParlay': enable_parlay } if filters: payload['filters'] = filters response = requests.post( f'{API_ENDPOINT}/products/search', headers=self.headers, json=payload ) response.raise_for_status() return response.json() def initiate_parlay(self, product_id: str, initial_offer: float, context: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: """Start a Parlay negotiation for a product""" payload = { 'productId': product_id, 'buyerAgentId': 'my-agent-123', 'initialOffer': initial_offer } if context: payload['context'] = context response = requests.post( f'{API_ENDPOINT}/parlay/initiate', headers=self.headers, json=payload ) response.raise_for_status() return response.json() def counter_offer(self, session_id: str, new_offer: float) -> Dict[str, Any]: """Submit a counter offer in an active Parlay session""" response = requests.post( f'{API_ENDPOINT}/parlay/{session_id}/counter', headers=self.headers, json={'offer': new_offer} ) response.raise_for_status() return response.json() # Example: Automated negotiation bot async def negotiate_best_price(client: BDCClient, product_id: str, target_price: float, max_rounds: int = 5): """Automatically negotiate to reach target price""" # Start negotiation at 80% of listing price initial_offer = target_price * 0.8 parlay = client.initiate_parlay( product_id=product_id, initial_offer=initial_offer, context={ 'orderQuantity': 10, 'customerType': 'business' } ) session_id = parlay['sessionId'] rounds = 0 while rounds < max_rounds and parlay['status'] == 'negotiating': current_price = parlay['currentOffer']['price'] if current_price <= target_price: # Accept the offer response = requests.post( f'{API_ENDPOINT}/parlay/{session_id}/accept', headers=client.headers ) print(f"Deal accepted at ${current_price}!") break # Counter with gradual increase new_offer = initial_offer + ( (target_price - initial_offer) * (rounds + 1) / max_rounds ) parlay = client.counter_offer(session_id, new_offer) rounds += 1 await asyncio.sleep(2) # Wait between rounds return parlay # Usage example if __name__ == '__main__': client = BDCClient(API_KEY) # Search for negotiable products results = client.search_products( query='premium office chairs', enable_parlay=True ) parlay_products = [p for p in results['products'] if p['parlayEnabled']] print(f"Found {len(parlay_products)} negotiable products") if parlay_products: # Start negotiation on first product product = parlay_products[0] target = product['price'] * 0.85 # Target 15% discount asyncio.run(negotiate_best_price( client, product['id'], target ))
#!/bin/bash # Set your API credentials API_ENDPOINT="{YOUR_API_ENDPOINT}/api/v1" API_KEY="YOUR_API_KEY" # Search for products with Parlay enabled curl -X POST "${API_ENDPOINT}/products/search" \ -H "Authorization: Bearer ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "buyerAgentId": "my-agent-123", "query": "office chairs", "enableParlay": true }' # Initiate a Parlay negotiation PRODUCT_ID="prod_123" INITIAL_OFFER="150.00" PARLAY_RESPONSE=$(curl -s -X POST "${API_ENDPOINT}/parlay/initiate" \ -H "Authorization: Bearer ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "productId": "'${PRODUCT_ID}'", "buyerAgentId": "my-agent-123", "initialOffer": '${INITIAL_OFFER}', "context": { "orderQuantity": 5, "customerType": "business" } }') # Extract session ID using jq SESSION_ID=$(echo "$PARLAY_RESPONSE" | jq -r '.sessionId') echo "Negotiation started. Session ID: $SESSION_ID" # Check negotiation status curl -X GET "${API_ENDPOINT}/parlay/${SESSION_ID}/status" \ -H "Authorization: Bearer ${API_KEY}" | jq '.' # Submit counter offer curl -X POST "${API_ENDPOINT}/parlay/${SESSION_ID}/counter" \ -H "Authorization: Bearer ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "offer": 165.00 }' # Accept current offer curl -X POST "${API_ENDPOINT}/parlay/${SESSION_ID}/accept" \ -H "Authorization: Bearer ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{}' # Full negotiation workflow example negotiate_product() { local product_id="$1" local target_price="$2" # Start negotiation at 80% of target local initial_offer=$(echo "$target_price * 0.8" | bc) echo "Starting negotiation for product $product_id" echo "Target price: $target_price, Initial offer: $initial_offer" # Initiate parlay and get session ID local session_response=$(curl -s -X POST "${API_ENDPOINT}/parlay/initiate" \ -H "Authorization: Bearer ${API_KEY}" \ -H "Content-Type: application/json" \ -d "{ \"productId\": \"$product_id\", \"buyerAgentId\": \"my-agent-123\", \"initialOffer\": $initial_offer }") local session_id=$(echo "$session_response" | jq -r '.sessionId') # Negotiation loop for i in {1..5}; do sleep 2 # Check current status local status_response=$(curl -s -X GET \ "${API_ENDPOINT}/parlay/${session_id}/status" \ -H "Authorization: Bearer ${API_KEY}") local current_price=$(echo "$status_response" | \ jq -r '.currentOffer.price') echo "Round $i: Current offer is $current_price" # Accept if price is good if (( $(echo "$current_price <= $target_price" | bc -l) )); then echo "Accepting offer at $current_price!" curl -s -X POST "${API_ENDPOINT}/parlay/${session_id}/accept" \ -H "Authorization: Bearer ${API_KEY}" \ -d '{}' break fi # Counter offer local new_offer=$(echo "$initial_offer + ($target_price - $initial_offer) * $i / 5" | bc) echo "Countering with $new_offer" curl -s -X POST "${API_ENDPOINT}/parlay/${session_id}/counter" \ -H "Authorization: Bearer ${API_KEY}" \ -H "Content-Type: application/json" \ -d "{\"offer\": $new_offer}" done } # Example usage negotiate_product "prod_456" "175.00"