Hyperfold AI

SDK Installation

Install and configure the Actions SDK for building custom agents.

Requirements

Before installing the SDK, ensure you have:

  • Node.js 18+ - Required for ES2022 features
  • TypeScript 5.0+ - For decorator support
  • GCP Project - Firestore, Pub/Sub, Cloud Run access
  • LLM API Key - OpenAI, Google AI, or Anthropic

Installation

Install the Actions SDK package:

# Install the Actions SDK
$ pnpm add @hyperfold/actions-sdk
# Or with npm
$ npm install @hyperfold/actions-sdk
# Or with yarn
$ yarn add @hyperfold/actions-sdk

Peer Dependencies

Install required peer dependencies for GCP services:

# Required peer dependencies
$ pnpm add @google-cloud/firestore @google-cloud/pubsub @google-cloud/vertexai
# Optional: For specific integrations
$ pnpm add stripe                    # Stripe payments
$ pnpm add @shopify/shopify-api      # Shopify integration
$ pnpm add openai                    # OpenAI models

Project Setup

Create a new agent project using the CLI template:

# Create a new agent project from template
$ hyperfold agents init my-agent --template=negotiator
# Project structure:
my-agent/
├── src/
│   ├── agent.ts              # Main agent class
│   ├── handlers/
│   │   ├── search.ts         # Search handler
│   │   ├── quote.ts          # Quote handler
│   │   └── checkout.ts       # Checkout handler
│   └── tools/
│       └── pricing.ts        # Custom pricing logic
├── config/
│   ├── agent.yaml            # Agent configuration
│   └── pricing-policy.yaml   # Pricing rules
├── prompts/
│   └── system.txt            # System prompt
├── tests/
│   └── agent.test.ts         # Unit tests
├── package.json
├── tsconfig.json
└── .env.example

TypeScript Configuration

Ensure your tsconfig.json enables decorators:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Configuration

Configure environment variables for your agent:

# .env
# Required: GCP project for Firestore, Pub/Sub, etc.
GOOGLE_CLOUD_PROJECT=my-project-id
GOOGLE_APPLICATION_CREDENTIALS=./service-account.json
# Required: LLM provider (choose one)
OPENAI_API_KEY=sk-...
# GOOGLE_AI_API_KEY=...
# ANTHROPIC_API_KEY=...
# Required: Payment provider (if processing payments)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
# Optional: Integrations
SHOPIFY_API_KEY=shpat_...
SALESFORCE_CLIENT_ID=...

GCP Service Account

Create a service account with the following roles:

  • roles/datastore.user - Firestore access
  • roles/pubsub.publisher - Pub/Sub publishing
  • roles/pubsub.subscriber - Pub/Sub subscriptions
  • roles/aiplatform.user - Vertex AI embeddings
# Create service account
$ gcloud iam service-accounts create hyperfold-agent \\
  --display-name="Hyperfold Agent"
# Grant required roles
$ gcloud projects add-iam-policy-binding $PROJECT_ID \\
  --member="serviceAccount:hyperfold-agent@$PROJECT_ID.iam.gserviceaccount.com" \\
  --role="roles/datastore.user"
# Download key file
$ gcloud iam service-accounts keys create ./service-account.json \\
  --iam-account=hyperfold-agent@$PROJECT_ID.iam.gserviceaccount.com

Verification

Verify your installation is working:

# Verify SDK installation
$ pnpm exec hyperfold-sdk --version
@hyperfold/actions-sdk v1.2.0
# Check TypeScript decorators work
$ pnpm tsc --noEmit
# Run local development server
$ pnpm dev
> Agent running at http://localhost:3000
> ACP manifest: http://localhost:3000/.well-known/acp/manifest.json
# Test health endpoint
$ curl http://localhost:3000/health
{"status":"healthy","version":"1.0.0"}