Hyperfold AI

@HyperfoldAgent

The core decorator for defining agent classes with configuration.

Overview

The @HyperfoldAgent decorator marks a class as a Hyperfold agent and provides configuration for LLM, capabilities, and runtime behavior.

import { HyperfoldAgent } from '@hyperfold/actions-sdk';
@HyperfoldAgent({
  name: 'sales-bot-01',
  type: 'negotiator',
})
export class SalesBot {
  // Agent methods...
}

Configuration Options

Full configuration with all available options:

@HyperfoldAgent({
  name: 'sales-bot-01',
  type: 'negotiator',
  model: {
    provider: 'openai',
    model: 'gpt-4o',
    temperature: 0.7,
    maxTokens: 2048,
    topP: 0.95,
  },
  systemPrompt: `
    You are a sales agent for Acme Sports.
    Be helpful and friendly while protecting margins.
    Never go below the floor price.
  `,
  capabilities: ['negotiate', 'bundle', 'recommend'],
  integrations: {
    catalog: 'default',
    payments: 'stripe',
    crm: 'salesforce',
  },
  resources: {
    memory: '512Mi',
    cpu: '1',
    maxConcurrency: 80,
    timeout: 60,
  },
  pricing: {
    policyFile: './pricing-policy.yaml',
    maxDiscountPercent: 20,
    approvalThreshold: 100,
  },
  metadata: {
    version: '1.2.0',
    team: 'sales',
    environment: process.env.NODE_ENV,
  },
})
export class SalesBot { }

Configuration Reference

OptionTypeDescription
namestringUnique agent identifier
typeAgentTypeAgent type (negotiator, fulfillment, etc.)
modelModelConfigLLM provider and settings
systemPromptstring | FunctionAgent instructions
capabilitiesstring[]Enabled features
integrationsobjectExternal system connections
resourcesResourceConfigMemory, CPU, concurrency limits

Model Configuration

Configure the underlying LLM for your agent:

// OpenAI
model: {
  provider: 'openai',
  model: 'gpt-4o',
  temperature: 0.7,
  maxTokens: 2048,
}
// Google Gemini
model: {
  provider: 'google',
  model: 'gemini-1.5-pro',
  temperature: 0.7,
  maxTokens: 2048,
}
// Anthropic Claude
model: {
  provider: 'anthropic',
  model: 'claude-3-opus',
  temperature: 0.7,
  maxTokens: 2048,
}
// Dynamic model selection
model: {
  provider: 'openai',
  model: async (context) => {
    if (context.queryComplexity < 0.5) return 'gpt-4o-mini';
    return 'gpt-4o';
  },
  temperature: 0.7,
}

System Prompt

Define agent behavior through system prompts:

// Inline
@HyperfoldAgent({
  name: 'sales-bot',
  type: 'negotiator',
  systemPrompt: `
    You are a sales agent for Acme Sports.
    Your goals: Help customers find the right products, negotiate fair prices, suggest bundles.
    Rules: Never go below the floor price. Always explain value. Be friendly but professional.
  `,
})
// Load from file (hot-swapping)
@HyperfoldAgent({
  name: 'sales-bot',
  type: 'negotiator',
  systemPromptFile: './prompts/negotiator-v2.txt',
})
// Dynamic prompt
@HyperfoldAgent({
  name: 'sales-bot',
  type: 'negotiator',
  systemPrompt: async (context) => {
    const basePrompt = await loadPrompt('./prompts/base.txt');
    const seasonalContext = await getSeasonalContext();
    return `${basePrompt}\nCurrent context:\n- Season: ${seasonalContext.season}\n- Active promotions: ${seasonalContext.promotions.join(', ')}`;
  },
})

Capabilities

Declare what your agent can do:

@HyperfoldAgent({
  name: 'sales-bot',
  type: 'negotiator',
  capabilities: ['negotiate', 'bundle', 'recommend', 'subscribe'],
})
// Capabilities affect ACP manifest GET /.well-known/acp/manifest.json
// "merchant": { "capabilities": ["negotiate", "bundle", "recommend", "subscribe"] }

Lifecycle Hooks

Handle agent and session lifecycle events:

@HyperfoldAgent({ name: 'sales-bot', type: 'negotiator' })
export class SalesBot {
  async onStart() {
    await this.warmupCache();
  }
  async onSessionStart(session: Session) {
    await this.loadCustomerContext(session.customerId);
  }
  async onSessionEnd(session: Session, outcome: SessionOutcome) {
    await this.logMetrics(session, outcome);
  }
  async onShutdown() {
    await this.cleanup();
  }
  async onError(error: Error, context: ErrorContext) {
    await this.alertOps(error, context);
  }
}