@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.

typescript
1
2
3
4
5
6
7
8
9
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:

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
@HyperfoldAgent({
// Required
name: 'sales-bot-01',
type: 'negotiator',
// LLM Configuration
model: {
provider: 'openai', // 'openai' | 'google' | 'anthropic'
model: 'gpt-4o', // Model identifier
temperature: 0.7, // Creativity (0-1)
maxTokens: 2048, // Max response length
topP: 0.95, // Nucleus sampling
},
// Agent instructions
systemPrompt: `
You are a sales agent for Acme Sports.
Be helpful and friendly while protecting margins.
Never go below the floor price.
`,
// Or load from file
// systemPromptFile: './prompts/negotiator.txt',
// Capabilities
capabilities: ['negotiate', 'bundle', 'recommend'],
// Connections
integrations: {
catalog: 'default', // Firestore collection
payments: 'stripe', // Payment provider
crm: 'salesforce', // CRM integration
},
// Resource limits
resources: {
memory: '512Mi',
cpu: '1',
maxConcurrency: 80,
timeout: 60,
},
// Pricing policy
pricing: {
policyFile: './pricing-policy.yaml',
maxDiscountPercent: 20,
approvalThreshold: 100,
},
// Metadata
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:

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// OpenAI configuration
model: {
provider: 'openai',
model: 'gpt-4o', // or 'gpt-4o-mini', 'gpt-4-turbo'
temperature: 0.7,
maxTokens: 2048,
}
// Google Gemini configuration
model: {
provider: 'google',
model: 'gemini-1.5-pro', // or 'gemini-1.5-flash'
temperature: 0.7,
maxTokens: 2048,
}
// Anthropic Claude configuration
model: {
provider: 'anthropic',
model: 'claude-3-opus', // or 'claude-3-sonnet'
temperature: 0.7,
maxTokens: 2048,
}
// Dynamic model selection based on context
model: {
provider: 'openai',
model: async (context) => {
// Use cheaper model for simple queries
if (context.queryComplexity < 0.5) {
return 'gpt-4o-mini';
}
return 'gpt-4o';
},
temperature: 0.7,
}

System Prompt

Define agent behavior through system prompts:

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
// 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:

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Define agent capabilities
@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:

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
@HyperfoldAgent({
name: 'sales-bot',
type: 'negotiator',
})
export class SalesBot {
// Called when agent starts
async onStart() {
console.log('Agent starting...');
await this.warmupCache();
}
// Called before each session
async onSessionStart(session: Session) {
console.log(`Session started: ${session.id}`);
await this.loadCustomerContext(session.customerId);
}
// Called after each session
async onSessionEnd(session: Session, outcome: SessionOutcome) {
console.log(`Session ended: ${outcome.status}`);
await this.logMetrics(session, outcome);
}
// Called on shutdown
async onShutdown() {
console.log('Agent shutting down...');
await this.cleanup();
}
// Called on errors
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.