Hyperfold AI

Actions SDK Overview

Build custom agents with TypeScript decorators and built-in tools.

Introduction

The Hyperfold Actions SDK provides a declarative way to build commerce agents using TypeScript. Define agent behavior with decorators, leverage built-in tools for common operations, and let the SDK handle the infrastructure complexity.

Installation

# 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

Architecture

The SDK sits between your agent code and GCP infrastructure:

┌───────────────────────────────────────────────────────────┐
│                     Your Agent Code                       │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  @HyperfoldAgent({ ... })                           │  │
│  │  class MyAgent {                                    │  │
│  │    @OnACPEvent('search')  → handles ACP search      │  │
│  │    @OnACPEvent('quote')   → handles price quotes    │  │
│  │    @OnSchedule('...')     → scheduled tasks         │  │
│  │    @OnEndpoint('/...')    → custom HTTP endpoints   │  │
│  │  }                                                  │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────────┐
│                   Actions SDK Runtime                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │ ACP Router  │  │ LLM Client  │  │ Tool Registry   │   │
│  │  (events)   │  │  (OpenAI,   │  │ (getProduct,    │   │
│  │             │  │   Gemini)   │  │ calculatePrice) │   │
│  └─────────────┘  └─────────────┘  └─────────────────┘   │
└───────────────────────────────────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────────┐
│                   GCP Infrastructure                      │
│  ┌───────────┐  ┌───────────┐  ┌─────────┐  ┌─────────┐  │
│  │ Firestore │  │  Pub/Sub  │  │ Vertex  │  │ Cloud   │  │
│  │  (state)  │  │ (events)  │  │   AI    │  │  Run    │  │
│  └───────────┘  └───────────┘  └─────────┘  └─────────┘  │
└───────────────────────────────────────────────────────────┘

Complete Example

Here's a complete negotiator agent using the SDK:

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) {
    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) {
      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 * * *')
  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() };
  }
}

Decorators Overview

Decorators define how your agent responds to events:

// @HyperfoldAgent - Define an agent class
@HyperfoldAgent({
  name: 'my-agent',
  type: 'negotiator',
  model: { ... },
  systemPrompt: '...',
})
class MyAgent { }
// @OnACPEvent - Handle ACP protocol events
@OnACPEvent('search')
@OnACPEvent('quote')
@OnACPEvent('checkout')
@OnACPEvent('finalize')
// @OnSchedule - Scheduled tasks (cron syntax)
@OnSchedule('0 * * * *')
@OnSchedule('0 9 * * 1')
// @OnEndpoint - Custom HTTP endpoints
@OnEndpoint('/webhook')
@OnEndpoint('/health')
DecoratorPurpose
@HyperfoldAgentDefine agent class with configuration
@OnACPEventHandle ACP protocol events
@OnScheduleRun tasks on a schedule
@OnEndpointExpose custom HTTP endpoints

Built-in Tools

The SDK includes tools for common commerce operations:

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