@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
| 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:
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 configurationmodel: { provider: 'openai', model: 'gpt-4o', // or 'gpt-4o-mini', 'gpt-4-turbo' temperature: 0.7, maxTokens: 2048,} // Google Gemini configurationmodel: { provider: 'google', model: 'gemini-1.5-pro', // or 'gemini-1.5-flash' temperature: 0.7, maxTokens: 2048,} // Anthropic Claude configurationmodel: { provider: 'anthropic', model: 'claude-3-opus', // or 'claude-3-sonnet' temperature: 0.7, maxTokens: 2048,} // Dynamic model selection based on contextmodel: { 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.