Nov 28, 2025

Custom Agent Development

Hyperfold Team

Agents

SDK Setup

Create a new custom agent project:

# 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:

// 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:

// 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:

// 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:

# 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