Agentic Discovery

1// Optimizing for Agentic Discovery
2 
3// 1. Structured product data optimized for agent comparison
4interface AgentOptimizedProduct {
5  "@type": "Product";
6  "@id": string;
7  
8  // Core identification
9  name: string;
10  brand: { "@type": "Brand"; name: string; "@id": string };
11  category: string[];
12  
13  // Agent comparison attributes (standardized)
14  comparableAttributes: {
15    priceUSD: number;
16    qualityScore: number;        // 0-100 normalized
17    customerRating: number;      // 0-5 stars
18    reviewCount: number;
19    warrantyMonths: number;
20    returnDays: number;
21    sustainabilityScore?: number;
22    deliveryDays: number;
23  };
24  
25  // Availability for agent decision-making
26  availability: {
27    inStock: boolean;
28    quantity: number;
29    restockDate?: string;
30    shippingOptions: ShippingOption[];
31  };
32  
33  // Trust signals agents use for filtering
34  trustSignals: {
35    certifications: string[];
36    verifiedSeller: boolean;
37    moneyBackGuarantee: boolean;
38    securePayment: boolean;
39    authenticityGuarantee: boolean;
40  };
41  
42  // Capability declarations
43  capabilities: {
44    bestFor: string[];           // ["outdoor use", "beginners", "professionals"]
45    notRecommendedFor: string[]; // ["extreme cold", "heavy loads"]
46    compatibleWith: string[];    // ["Model X", "Model Y"]
47  };
48  
49  // Agent action endpoints
50  agentActions: {
51    addToCart: { url: string; method: "POST" };
52    checkLiveAvailability: { url: string; method: "GET" };
53    getDetailedSpecs: { url: string; method: "GET" };
54    requestQuote?: { url: string; method: "POST" };
55  };
56}
57 
58// 2. Agent-friendly comparison endpoint
59export async function GET(request: NextRequest) {
60  const searchParams = request.nextUrl.searchParams;
61  const category = searchParams.get('category');
62  const preferences = JSON.parse(searchParams.get('preferences') || '{}');
63  
64  // Return data optimized for agent comparison
65  const products = await getProductsForAgentComparison(category);
66  
67  return NextResponse.json({
68    "@type": "ProductComparison",
69    "category": category,
70    "comparisonDate": new Date().toISOString(),
71    
72    // Comparison dimensions available
73    "comparisonDimensions": [
74      "priceUSD", "qualityScore", "customerRating", 
75      "warrantyMonths", "deliveryDays", "sustainabilityScore"
76    ],
77    
78    // Statistical context for agent understanding
79    "categoryStatistics": {
80      "priceRange": { "min": 29.99, "max": 299.99, "median": 89.99 },
81      "averageRating": 4.2,
82      "totalProducts": products.length
83    },
84    
85    // Products with normalized comparable attributes
86    "products": products.map(p => ({
87      ...p,
88      // Percentile rankings help agents contextualize
89      "percentileRankings": {
90        "price": calculatePercentile(p.comparableAttributes.priceUSD, products, 'price'),
91        "quality": calculatePercentile(p.comparableAttributes.qualityScore, products, 'quality'),
92        "rating": calculatePercentile(p.comparableAttributes.customerRating, products, 'rating')
93      }
94    })),
95    
96    // Help agents understand selection criteria
97    "recommendationHints": {
98      "bestValue": products.find(p => p.valueScore === Math.max(...products.map(x => x.valueScore)))?.["@id"],
99      "highestRated": products.find(p => p.comparableAttributes.customerRating === Math.max(...products.map(x => x.comparableAttributes.customerRating)))?.["@id"],
100      "fastestDelivery": products.find(p => p.comparableAttributes.deliveryDays === Math.min(...products.map(x => x.comparableAttributes.deliveryDays)))?.["@id"]
101    }
102  });
103}
104 
105// 3. Preference-based recommendation endpoint
106export async function POST(request: NextRequest) {
107  const { userPreferences, constraints, context } = await request.json();
108  
109  /*
110    Example input:
111    {
112      "userPreferences": {
113        "prioritize": ["durability", "value"],
114        "avoid": ["heavy", "complex setup"],
115        "budget": { "max": 150, "flexibility": "somewhat" },
116        "timeline": "within 1 week"
117      },
118      "constraints": {
119        "mustHave": ["waterproof", "warranty > 12 months"],
120        "niceToHave": ["eco-friendly", "compact"]
121      },
122      "context": {
123        "useCase": "outdoor camping",
124        "experienceLevel": "intermediate",
125        "previousPurchases": ["tent-model-x"]
126      }
127    }
128  */
129  
130  const recommendations = await generateAgentRecommendations(
131    userPreferences, 
132    constraints, 
133    context
134  );
135  
136  return NextResponse.json({
137    "@type": "AgentRecommendation",
138    "generatedAt": new Date().toISOString(),
139    "basedOn": {
140      "preferences": userPreferences,
141      "constraints": constraints,
142      "context": context
143    },
144    
145    "recommendations": recommendations.map((rec, index) => ({
146      "rank": index + 1,
147      "product": rec.product,
148      "matchScore": rec.matchScore,
149      "matchExplanation": rec.explanation,
150      "tradeoffs": rec.tradeoffs,
151      "alternativeIf": rec.alternativeConditions
152    })),
153    
154    // Help agent explain to user
155    "summaryForUser": generateUserFacingSummary(recommendations),
156    
157    // Flag if agent should gather more info
158    "clarificationNeeded": recommendations.some(r => r.confidenceLow) ? {
159      "questions": generateClarifyingQuestions(userPreferences, constraints),
160      "wouldImprove": ["recommendation accuracy", "tradeoff visibility"]
161    } : null
162  });
163}
164 
165// 4. llms.txt optimized for discovery agents
166const llmsTxtForDiscovery = `
167# [Brand Name] - [Category] Products
168 
169> [Brand] offers [value proposition] for [target audience].
170 
171## Quick Facts for Comparison
172- Price Range: $X - $Y
173- Average Rating: X.X stars (N reviews)
174- Shipping: Free over $Z, 2-5 day delivery
175- Returns: 30-day hassle-free returns
176- Warranty: X years standard
177 
178## Best For
179- [Use case 1]
180- [Use case 2]
181- [Use case 3]
182 
183## Not Recommended For
184- [Anti-use case 1]
185- [Anti-use case 2]
186 
187## Product Comparison API
188For detailed product comparison data, agents can access:
189GET /api/agent/products/compare?category={category}
190 
191## How to Purchase
192Agents can add products to cart via:
193POST /api/agent/cart/add
194Body: { "productId": "...", "quantity": 1 }
195 
196---
197Last Updated: [Date]
198Source: Official [Brand] Product Catalog
199`;