Actions SDK Overview

# Install the Actions SDK
$ pnpm add @hyperfold/actions-sdk
 
# Or with npm
$ npm install @hyperfold/actions-sdk
 
# Peer dependencies (if not already installed)
$ pnpm add @google-cloud/firestore @google-cloud/pubsub

import {
  HyperfoldAgent,
  OnACPEvent,
  OnSchedule,
  OnEndpoint,
  getProduct,
  calculateDynamicPrice,
  checkInventory,
} from '@hyperfold/actions-sdk';
 
@HyperfoldAgent({
  name: 'sales-negotiator',
  type: 'negotiator',
  model: {
    provider: 'openai',
    model: 'gpt-4o',
    temperature: 0.7,
  },
  systemPrompt: `
    You are a sales agent for Acme Sports.
    Help customers find products and negotiate fair prices.
    Never go below the floor price.
  `,
})
export class SalesNegotiator {
 
  @OnACPEvent('search')
  async handleSearch(query: string, filters: SearchFilters) {
    // Semantic search across product catalog
    const products = await this.catalog.search(query, filters);
    return {
      results: products,
      semantic_confidence: products[0]?.confidence || 0,
    };
  }
 
  @OnACPEvent('quote')
  async handleQuote(productId: string, offer: number, context: BuyerContext) {
    const product = await getProduct(productId);
    const dynamicPrice = await calculateDynamicPrice(product, context);
 
    if (offer >= dynamicPrice.floor) {
      // Acceptable offer - decide whether to accept or counter
      if (offer >= dynamicPrice.target) {
        return { status: 'accept', price: offer };
      } else {
        return {
          status: 'counter_offer',
          price: dynamicPrice.suggested,
          reasoning: dynamicPrice.explanation,
        };
      }
    } else {
      return {
        status: 'reject',
        reason: 'Below minimum acceptable price',
        counter: dynamicPrice.floor,
      };
    }
  }
 
  @OnSchedule('0 9 * * *')  // Daily at 9 AM
  async dailyReport() {
    const stats = await this.analytics.getDailyStats();
    await this.notifications.sendSlack({
      channel: '#sales',
      message: `Daily Report: ${stats.conversions} conversions, $${stats.revenue}`,
    });
  }
 
  @OnEndpoint('/health')
  async healthCheck() {
    return { status: 'healthy', timestamp: new Date().toISOString() };
  }
}

// @HyperfoldAgent - Define an agent class
@HyperfoldAgent({
  name: 'my-agent',
  type: 'negotiator',        // negotiator, fulfillment, recommender, etc.
  model: { ... },            // LLM configuration
  systemPrompt: '...',       // Agent instructions
})
class MyAgent { }
 
// @OnACPEvent - Handle ACP protocol events
@OnACPEvent('search')        // Product search
@OnACPEvent('quote')         // Price quote request
@OnACPEvent('checkout')      // Checkout initiation
@OnACPEvent('finalize')      // Payment finalization
 
// @OnSchedule - Scheduled tasks (cron syntax)
@OnSchedule('0 * * * *')     // Every hour
@OnSchedule('0 9 * * 1')     // Monday at 9 AM
 
// @OnEndpoint - Custom HTTP endpoints
@OnEndpoint('/webhook')      // Handle webhooks
@OnEndpoint('/health')       // Health checks

import {
  // Product tools
  getProduct,
  searchProducts,
  checkInventory,
 
  // Pricing tools
  calculateDynamicPrice,
  getCompetitorPrice,
  applyDiscount,
 
  // Customer tools
  getCustomerProfile,
  updateLoyaltyTier,
  getOrderHistory,
 
  // Order tools
  createOrder,
  updateOrderStatus,
  processRefund,
 
  // Notification tools
  sendEmail,
  sendSMS,
  postToSlack,
 
  // Integration tools
  syncToShopify,
  updateSalesforce,
} from '@hyperfold/actions-sdk';