@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

Option	Type	Description
`name`	string	Unique agent identifier
`type`	AgentType	Agent type (negotiator, fulfillment, etc.)
`model`	ModelConfig	LLM provider and settings
`systemPrompt`	string \| Function	Agent instructions
`capabilities`	string[]	Enabled features
`integrations`	object	External system connections
`resources`	ResourceConfig	Memory, CPU, concurrency limits

Model Configuration

Configure the underlying LLM for your agent:

// OpenAI configuration
model: {
  provider: 'openai',
  model: 'gpt-4o',
  temperature: 0.7,
  maxTokens: 2048,
}
// Google Gemini configuration
model: {
  provider: 'google',
  model: 'gemini-1.5-pro',
  temperature: 0.7,
  maxTokens: 2048,
}
// Anthropic Claude configuration
model: {
  provider: 'anthropic',
  model: 'claude-3-opus',
  temperature: 0.7,
  maxTokens: 2048,
}
// Dynamic model selection based on context
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 system prompt
@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 within policy limits
    - Suggest relevant bundles and add-ons
    Rules:
    - Never go below the floor price
    - Always explain value, not just discount
    - Be friendly but professional
  `,
})
// Load from file (supports hot-swapping)
@HyperfoldAgent({
  name: 'sales-bot',
  type: 'negotiator',
  systemPromptFile: './prompts/negotiator-v2.txt',
})
// Dynamic prompt based on context
@HyperfoldAgent({
  name: 'sales-bot',
  type: 'negotiator',
  systemPrompt: async (context) => {
    const basePrompt = await loadPrompt('./prompts/base.txt');
    const seasonalContext = await getSeasonalContext();
    return `
      ${basePrompt}
      Current context:
      - Season: ${seasonalContext.season}
      - Active promotions: ${seasonalContext.promotions.join(', ')}
    `;
  },
})

Use systemPromptFile for prompts that need hot-swapping without redeployment. The file is read fresh for each new session.

Capabilities

Declare what your agent can do:

@HyperfoldAgent({
  name: 'sales-bot',
  type: 'negotiator',
  capabilities: [
    'negotiate',     // Price negotiation
    'bundle',        // Product bundling
    'recommend',     // Product recommendations
    'subscribe',     // Subscription handling
  ],
})
// 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() {
    console.log('Agent starting...');
    await this.warmupCache();
  }
  async onSessionStart(session: Session) {
    console.log(`Session started: ${session.id}`);
    await this.loadCustomerContext(session.customerId);
  }
  async onSessionEnd(session: Session, outcome: SessionOutcome) {
    console.log(`Session ended: ${outcome.status}`);
    await this.logMetrics(session, outcome);
  }
  async onShutdown() {
    console.log('Agent shutting down...');
    await this.cleanup();
  }
  async onError(error: Error, context: ErrorContext) {
    console.error(`Error in ${context.method}: ${error.message}`);
    await this.alertOps(error, context);
  }
}

Learn about handling ACP events with @OnACPEvent.

Search Documentation