Hyperfold AI
Back

Nov 28, 2025

Custom Agent Development

H
Hyperfold Team
Agents

SDK Setup

Create a new custom agent project:

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
# Initialize project
$ hyperfold agents init my-custom-agent --template=blank
 
# Project structure:
my-custom-agent/
├── src/
│   └── agent.ts        # Agent implementation
├── config/
│   └── agent.yaml      # Agent configuration
├── tests/
│   └── agent.test.ts   # Unit tests
├── package.json
└── tsconfig.json

Using Decorators

Build your agent using SDK decorators:

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
// custom-agent.ts
import {
  HyperfoldAgent,
  OnACPEvent,
  OnSchedule,
  OnEndpoint,
} from '@hyperfold/sdk';
import { getProduct, getCustomerContext } from '@hyperfold/tools';
 
@HyperfoldAgent({
  name: 'my-custom-agent',
  version: '1.0.0',
  model: 'gpt-4o',
  systemPrompt: `Your custom system prompt here...`,
})
export class MyCustomAgent {
  // Handle ACP events
  @OnACPEvent('search')
  async handleSearch(query: string, filters: any) {
    // Your search implementation
  }
 
  // Scheduled tasks
  @OnSchedule('0 0 * * *') // Daily at midnight
  async dailyTask() {
    // Runs on schedule
  }
 
  // Custom HTTP endpoints
  @OnEndpoint('/custom/action', { method: 'POST' })
  async customAction(request: Request) {
    // Custom endpoint logic
  }
}

Agent Tools

Available tools for your agent:

  • getProduct(id) - Fetch product details
  • searchProducts(query, filters) - Semantic search
  • calculateDynamicPrice(product, context) - Pricing
  • getCustomerContext(id) - Customer data
  • checkInventory(productId) - Stock levels
  • recommendSimilar(productId) - Recommendations

State Management

Persist state across sessions:

typescript
1
2
3
4
5
6
7
8
9
10
11
12
// Using agent state
@HyperfoldAgent({ ... })
export class MyAgent {
  // State is automatically persisted to Firestore
  async saveSessionState(sessionId: string, data: any) {
    await this.state.set(`session:${sessionId}`, data);
  }
 
  async getSessionState(sessionId: string) {
    return await this.state.get(`session:${sessionId}`);
  }
}

Testing Agents

Write unit tests 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
// agent.test.ts
import { createTestAgent, mockTools } from '@hyperfold/testing';
import { MyCustomAgent } from './custom-agent';
 
describe('MyCustomAgent', () => {
  let agent: MyCustomAgent;
 
  beforeEach(() => {
    agent = createTestAgent(MyCustomAgent, {
      mockLLM: true,
      mockTools: mockTools({
        getProduct: async (id) => ({ id, name: 'Test Product', price: 100 }),
      }),
    });
  });
 
  it('should handle search queries', async () => {
    const result = await agent.handleSearch('test query', {});
    expect(result.results).toBeDefined();
  });
 
  it('should respect pricing rules', async () => {
    const quote = await agent.handleQuote('prod_123', 50);
    expect(quote.status).toBe('reject'); // Below floor
  });
});

Deployment

Deploy your custom agent:

bash
1
2
3
4
5
6
7
# Build and deploy
$ hyperfold agents deploy ./my-custom-agent
 
# With environment variables
$ hyperfold agents deploy ./my-custom-agent \
  --env OPENAI_API_KEY=$OPENAI_API_KEY \
  --env CUSTOM_CONFIG=value