Recommender Agent

Intelligent product recommendations powered by vector search and ML.

Overview

The Recommender Agent generates product recommendations using vector similarity, co-purchase analysis, and customer personalization. It powers cross-sell and upsell capabilities for other agents.

The Recommender Agent is often used as a service by the Negotiator Agent to suggest bundles during price negotiations.

Capabilities

RECOMMENDER AGENT CAPABILITIES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ENDPOINTS:
  GET /recommendations/similar       Similar products
  GET /recommendations/complementary Frequently bought together
  GET /recommendations/personalized  Based on customer history
  POST /recommendations/context      Context-aware suggestions

FEATURES:
  ✓ Similar products      Vector similarity matching
  ✓ Cross-sell            Co-purchase analysis
  ✓ Upsell                Higher-value alternatives
  ✓ Personalization       Customer history-based
  ✓ Contextual            Session and cart-aware
  ✓ Real-time             Sub-100ms response time

ALGORITHMS:
  • Vector similarity (Vertex AI)
  • Collaborative filtering
  • Content-based filtering
  • Session-based recommendations

Recommendation Types

Different recommendation algorithms for different use cases:

// Similar Products - Vector Similarity
const similar = await recommender.getSimilar('prod_aero_x2', {
  limit: 5,
  min_similarity: 0.8,
});
// Returns products with similar attributes, style, category

// Complementary Products - Co-purchase Analysis
const complements = await recommender.getComplementary('prod_aero_x2', {
  limit: 3,
});
// Returns: socks, insoles, running vest (frequently bought together)

// Personalized - Customer History
const personalized = await recommender.getPersonalized('cust_xyz', {
  limit: 10,
  categories: ['footwear', 'apparel'],
});
// Returns products based on purchase history and preferences

// Contextual - Cart-Aware
const contextual = await recommender.getContextual({
  cart: ['prod_aero_x2', 'prod_socks_wp'],
  customer_id: 'cust_xyz',
  budget_remaining: 50,
});
// Returns products that complement cart within budget

// Upsell - Higher Value Alternatives
const upsell = await recommender.getUpsell('prod_aero_x2', {
  price_ceiling: 250,
});
// Returns premium alternatives: AeroRun X2 Pro, etc.

Algorithm Comparison

Type	Best For	Data Needed
Similar	Alternative products, comparisons	Product embeddings
Complementary	Bundles, add-ons	Purchase history
Personalized	Homepage, emails	Customer history
Contextual	Cart page, checkout	Session data

Deployment

# Deploy reference recommender agent
$ hyperfold agent deploy --type=recommender --name="recommender-01"

> [Build] Using reference implementation...
> [Index] Verifying vector search index...
> [Deploy] Creating Cloud Run service...

✓ Recommender agent deployed!

  Name:      recommender-01
  Endpoints: /recommendations/*
  Index:     vertex_ai_vector_search (1,489 products)

# Deploy with custom model
$ hyperfold agent deploy --type=recommender \
  --name="smart-recommender" \
  --config=./agents/recommender-config.yaml

Configuration

# recommender-config.yaml
name: recommender-agent
type: recommender
version: "1.0"

# Recommendation algorithms
algorithms:
  similar:
    enabled: true
    model: vertex_ai_vector_search
    min_similarity: 0.7
    exclude_same_category: false

  complementary:
    enabled: true
    source: co_purchase_data
    min_co_purchase_rate: 0.1
    lookback_days: 90

  personalized:
    enabled: true
    use_purchase_history: true
    use_browse_history: false  # Privacy setting
    history_window_days: 180
    weight_recent: 1.5

  contextual:
    enabled: true
    consider_cart: true
    consider_budget: true
    consider_session: true

# Filtering rules
filters:
  exclude_out_of_stock: true
  exclude_recently_purchased: true
  recently_purchased_days: 30
  min_inventory: 5

# Diversity settings
diversity:
  enabled: true
  max_same_category: 2
  max_same_brand: 2

# Caching
cache:
  similar_ttl: 3600        # 1 hour
  complementary_ttl: 86400 # 24 hours
  personalized_ttl: 300    # 5 minutes

# A/B testing
experiments:
  - name: algorithm_comparison
    variants:
      - name: vector_only
        weight: 0.5
        config:
          algorithms: [similar]
      - name: hybrid
        weight: 0.5
        config:
          algorithms: [similar, complementary, personalized]

Usage with Negotiator

Using recommendations during negotiations:

// Using Recommender Agent in Negotiator

@HyperfoldAgent({ name: 'sales-bot', type: 'negotiator' })
export class SalesBot {

  @OnACPEvent('quote')
  async handleQuote(productId: string, offer: number, context: BuyerContext) {
    // Calculate quote as usual
    const quote = await this.calculateQuote(productId, offer, context);

    // Enhance with recommendations
    if (quote.status === 'counter_offer') {
      // Suggest bundle to increase value
      const complements = await this.recommender.getComplementary(productId, {
        limit: 2,
        max_price: 50,
      });

      if (complements.length > 0) {
        const bundlePrice = await this.calculateBundlePrice([
          { product_id: productId, price: quote.counter_price },
          ...complements,
        ]);
        quote.bundle_suggestion = {
          items: complements,
          bundle_price: bundlePrice.total,
          you_save: bundlePrice.savings,
        };
      }
    }

    return quote;
  }

  @OnACPEvent('search')
  async handleSearch(query: string, filters: SearchFilters) {
    const results = await this.catalog.search(query, filters);

    // Add personalized recommendations if customer known
    if (filters.customer_id) {
      const personalized = await this.recommender.getPersonalized(
        filters.customer_id,
        { limit: 3 }
      );

      results.personalized_picks = personalized;
    }

    return results;
  }
}

See Order Agent for order status and management.

Search Documentation