Tools Reference

Built-in tools for common commerce operations in your agents.

Overview

The Actions SDK includes a comprehensive set of tools for product management, pricing, customer data, orders, and notifications. These tools integrate with your configured data sources and external services.

import {
  // Product tools
  getProduct,
  searchProducts,
  checkInventory,
  recommendSimilar,
  recommendComplementary,
  // Pricing tools
  calculateDynamicPrice,
  getCompetitorPrice,
  applyDiscount,
  validatePricing,
  // Customer tools
  getCustomerContext,
  getOrderHistory,
  updateLoyaltyTier,
  getCustomerPreferences,
  // Order tools
  createOrder,
  updateOrderStatus,
  processRefund,
  cancelOrder,
  // Notification tools
  sendEmail,
  sendSMS,
  postToSlack,
  sendWebhook,
} from '@hyperfold/actions-sdk';

All tools are async and return promises. They handle caching, retries, and error handling automatically.

Product Tools

Tools for accessing and searching the product catalog:

// Get product by ID
const product = await getProduct('prod_aero_x2');
console.log(product);
// {
//   product_id: 'prod_aero_x2',
//   name: 'AeroRun X2 Marathon Shoe',
//   description: 'Professional marathon shoe...',
//   pricing: {
//     list_price: 180.00,
//     cost: 72.00,
//     currency: 'USD',
//     min_margin: 0.15,
//   },
//   inventory: {
//     quantity: 847,
//     status: 'in_stock',
//   },
//   semantics: {
//     category: 'footwear/running',
//     usage_context: ['marathon', 'road_running'],
//     visual_tags: ['blue', 'lightweight'],
//   },
//   attributes: {
//     brand: 'AeroRun',
//     sizes: ['7', '8', '9', '10', '11', '12'],
//     colors: ['blue', 'black', 'white'],
//   },
// }
// Semantic product search
const results = await searchProducts('waterproof running shoes', {
  limit: 10,
  filters: {
    price_max: 200,
    in_stock: true,
  },
});
console.log(results);
// {
//   results: [...],
//   total_count: 15,
//   semantic_confidence: 0.92,
// }
// Check inventory
const inventory = await checkInventory('prod_aero_x2');
console.log(inventory);
// {
//   product_id: 'prod_aero_x2',
//   quantity: 847,
//   status: 'in_stock',
//   warehouses: [
//     { id: 'warehouse_west', quantity: 500 },
//     { id: 'warehouse_east', quantity: 347 },
//   ],
// }
// Get similar products (vector-based)
const similar = await recommendSimilar('prod_aero_x2', { limit: 5 });
// Get complementary products (co-purchase data)
const complementary = await recommendComplementary('prod_aero_x2', { limit: 3 });

Product Tool Reference

Tool	Description
`getProduct(id)`	Get product by ID with full details
`searchProducts(query, options)`	Semantic product search with filters
`checkInventory(productId)`	Get real-time inventory levels
`recommendSimilar(productId)`	Vector-based similar products
`recommendComplementary(productId)`	Co-purchase based recommendations

Pricing Tools

Tools for dynamic pricing and margin management:

// Calculate dynamic price with context
const pricing = await calculateDynamicPrice(product, {
  customerTier: 'gold',
  quantity: 2,
  competitorPrice: 165.00,
  inventoryLevel: 'high',
});
console.log(pricing);
// {
//   list_price: 180.00,
//   suggested: 162.00,
//   floor: 84.71,
//   target: 170.00,
//   discounts: [
//     { type: 'tier', percent: 0.10, reason: 'Gold member discount' },
//   ],
//   margin: 0.45,
//   explanation: 'Gold member discount of 10% applied.',
// }
// Get competitor price (cached)
const competitorPrice = await getCompetitorPrice('prod_aero_x2');
console.log(competitorPrice);
// {
//   product_id: 'prod_aero_x2',
//   competitor_prices: [
//     { competitor: 'competitor_a', price: 175.00, url: '...' },
//     { competitor: 'competitor_b', price: 169.00, url: '...' },
//   ],
//   lowest: 169.00,
//   average: 172.00,
//   updated_at: '2025-12-19T10:00:00Z',
// }
// Apply discount with validation
const discounted = await applyDiscount(product, {
  type: 'percentage',
  value: 15,
  reason: 'Holiday sale',
  validateMargin: true,  // Ensures margin floor is respected
});
// Validate pricing decision
const validation = await validatePricing({
  product_id: 'prod_aero_x2',
  proposed_price: 145.00,
  context: { customerTier: 'gold' },
});
console.log(validation);
// {
//   valid: true,
//   margin: 0.50,
//   warnings: [],
// }

Always use validatePricing before accepting prices that differ significantly from the calculated suggestion.

Customer Tools

Tools for accessing customer data and preferences:

// Get customer context
const customer = await getCustomerContext('cust_xyz123');
console.log(customer);
// {
//   customer_id: 'cust_xyz123',
//   email: 'john@example.com',
//   loyalty_tier: 'gold',
//   lifetime_value: 2450.00,
//   order_count: 12,
//   average_order_value: 204.17,
//   first_order_date: '2024-03-15',
//   last_order_date: '2025-12-01',
//   preferences: {
//     preferred_categories: ['running', 'hiking'],
//     size_preferences: { shoes: '10', shirts: 'L' },
//   },
// }
// Get order history
const history = await getOrderHistory('cust_xyz123', {
  limit: 10,
  status: 'completed',
});
// Update loyalty tier
await updateLoyaltyTier('cust_xyz123', 'platinum', {
  reason: 'Lifetime value exceeded $5000',
});
// Get customer preferences
const preferences = await getCustomerPreferences('cust_xyz123');

Order Tools

Tools for order management and fulfillment:

// Create order
const order = await createOrder({
  customer_id: 'cust_xyz123',
  items: [
    { product_id: 'prod_aero_x2', quantity: 1, price: 162.00 },
  ],
  shipping_address: {
    name: 'John Doe',
    line1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postal_code: '94102',
    country: 'US',
  },
  payment: {
    method: 'stripe_spt',
    token: 'spt_live_abc123',
  },
  metadata: {
    agent_id: 'sales-bot-01',
    session_id: 'sess_abc123',
  },
});
// Update order status
await updateOrderStatus('order_new123', 'shipped', {
  tracking_number: '1Z999AA10123456784',
  carrier: 'UPS',
  estimated_delivery: '2025-12-24',
});
// Process refund
const refund = await processRefund('order_new123', {
  amount: 175.37,
  reason: 'customer_request',
  restock_items: true,
});
// Cancel order
await cancelOrder('order_new123', {
  reason: 'customer_request',
  notify_customer: true,
  restock_items: true,
});

Notification Tools

Tools for sending notifications across channels:

// Send email
await sendEmail({
  to: 'john@example.com',
  subject: 'Your order has shipped!',
  template: 'order-shipped',
  data: {
    order_id: 'order_new123',
    tracking_number: '1Z999AA10123456784',
    estimated_delivery: '2025-12-24',
  },
});
// Send SMS
await sendSMS({
  to: '+14155551234',
  message: 'Your order #HF-12345 has shipped! Track at: https://...',
});
// Post to Slack
await postToSlack({
  channel: '#sales-alerts',
  message: 'New high-value order: $500+ from Gold member',
  blocks: [
    {
      type: 'section',
      text: {
        type: 'mrkdwn',
        text: '*New High-Value Order*\\nCustomer: John Doe\\nTotal: $523.00',
      },
    },
  ],
});
// Send webhook
await sendWebhook({
  url: 'https://api.partner.com/orders',
  method: 'POST',
  headers: {
    'X-API-Key': process.env.PARTNER_API_KEY,
  },
  body: {
    order_id: 'order_new123',
    status: 'created',
    total: 175.37,
  },
  retries: 3,
  retryDelay: 1000,
});

Build your first agent with the Your First Agent guide.

Search Documentation