Skip to main content

🔧 Advanced Usage Guide

This guide covers advanced features and capabilities of Eliza, including complex integrations, custom services, and specialized plugins.

Service Integration

Video Processing Service

Eliza supports advanced video processing capabilities through the VideoService:

import { VideoService } from "@ai16z/eliza/plugin-node";

// Initialize service
const videoService = new VideoService();

// Process video content
const result = await videoService.processVideo(url, runtime);

Key features:

  • Automatic video downloading
  • Transcription support
  • Subtitle extraction
  • Cache management
  • Queue processing

Image Processing

The ImageDescriptionService provides advanced image analysis:

import { ImageDescriptionService } from "@ai16z/eliza/plugin-node";

const imageService = new ImageDescriptionService();
const description = await imageService.describeImage(imageUrl, "gpu", runtime);

Features:

  • Local and cloud processing options
  • CUDA acceleration support
  • Automatic format handling
  • GIF frame extraction

Blockchain Integration

Solana Integration

The Solana plugin provides comprehensive blockchain functionality:

import { solanaPlugin } from "@ai16z/eliza/plugin-solana";

// Initialize plugin
runtime.registerPlugin(solanaPlugin);

Token Operations

// Buy tokens
const swapResult = await swapToken(
connection,
walletPublicKey,
inputTokenCA,
outputTokenCA,
amount,
);

// Sell tokens
const sellResult = await sellToken({
sdk,
seller: walletKeypair,
mint: tokenMint,
amount: sellAmount,
priorityFee,
allowOffCurve: false,
slippage: "1",
connection,
});

Trust Score System

const trustScoreManager = new TrustScoreManager(tokenProvider, trustScoreDb);

// Generate trust scores
const score = await trustScoreManager.generateTrustScore(
tokenAddress,
recommenderId,
recommenderWallet,
);

// Monitor trade performance
await trustScoreManager.createTradePerformance(runtime, tokenAddress, userId, {
buy_amount: amount,
is_simulation: false,
});

Custom Services

Speech Generation

Implement text-to-speech capabilities:

class SpeechService extends Service implements ISpeechService {
async generate(runtime: IAgentRuntime, text: string): Promise<Readable> {
if (runtime.getSetting("ELEVENLABS_XI_API_KEY")) {
return textToSpeech(runtime, text);
}

const { audio } = await synthesize(text, {
engine: "vits",
voice: "en_US-hfc_female-medium",
});

return Readable.from(audio);
}
}

PDF Processing

Handle PDF document analysis:

class PdfService extends Service {
async convertPdfToText(pdfBuffer: Buffer): Promise<string> {
const pdf = await getDocument({ data: pdfBuffer }).promise;
const numPages = pdf.numPages;
const textPages = [];

for (let pageNum = 1; pageNum <= numPages; pageNum++) {
const page = await pdf.getPage(pageNum);
const textContent = await page.getTextContent();
const pageText = textContent.items
.filter(isTextItem)
.map((item) => item.str)
.join(" ");
textPages.push(pageText);
}

return textPages.join("\n");
}
}

Advanced Memory Management

Retrievable Memory System

class MemoryManager {
async getMemories({
agentId,
roomId,
count,
}: {
agentId: string;
roomId: string;
count: number;
}): Promise<Memory[]> {
// Implement memory retrieval logic
}

async createMemory(
memory: Memory,
allowDuplicates: boolean = false,
): Promise<void> {
// Implement memory storage logic
}
}

Trust Score Database

Implement advanced scoring systems:

class TrustScoreDatabase {
async calculateValidationTrust(tokenAddress: string): number {
const sql = `
SELECT rm.trust_score
FROM token_recommendations tr
JOIN recommender_metrics rm ON tr.recommender_id = rm.recommender_id
WHERE tr.token_address = ?;
`;

const rows = this.db.prepare(sql).all(tokenAddress);
if (rows.length === 0) return 0;

const totalTrust = rows.reduce((acc, row) => acc + row.trust_score, 0);
return totalTrust / rows.length;
}
}

Plugin Development

Creating Custom Plugins

const customPlugin: Plugin = {
name: "custom-plugin",
description: "Custom Plugin for Eliza",
actions: [
// Custom actions
],
evaluators: [
// Custom evaluators
],
providers: [
// Custom providers
],
};

Advanced Action Development

export const complexAction: Action = {
name: "COMPLEX_ACTION",
similes: ["ALTERNATIVE_NAME", "OTHER_NAME"],
validate: async (runtime: IAgentRuntime, message: Memory) => {
// Implement validation logic
return true;
},
handler: async (
runtime: IAgentRuntime,
message: Memory,
state: State,
options: { [key: string]: unknown },
callback?: HandlerCallback,
): Promise<boolean> => {
// Implement complex handling logic
return true;
},
};

Advanced Configuration

Custom Runtime Configuration

const customRuntime = new AgentRuntime({
databaseAdapter: new PostgresDatabaseAdapter(config),
modelProvider: new OpenAIProvider(apiKey),
plugins: [solanaPlugin, customPlugin],
services: [
new VideoService(),
new ImageDescriptionService(),
new SpeechService(),
],
});

Advanced Model Configuration

const modelConfig = {
modelClass: ModelClass.LARGE,
temperature: 0.7,
maxTokens: 2000,
topP: 0.9,
frequencyPenalty: 0.5,
presencePenalty: 0.5,
};

const response = await generateText({
runtime,
context: prompt,
...modelConfig,
});

Performance Optimization

Caching Strategy

class CacheManager {
private cache: NodeCache;
private cacheDir: string;

constructor() {
this.cache = new NodeCache({ stdTTL: 300 });
this.cacheDir = path.join(__dirname, "cache");
this.ensureCacheDirectoryExists();
}

private async getCachedData<T>(key: string): Promise<T | null> {
// Implement tiered caching strategy
}
}

Queue Management

class QueueManager {
private queue: string[] = [];
private processing: boolean = false;

async processQueue(): Promise<void> {
if (this.processing || this.queue.length === 0) {
return;
}

this.processing = true;
while (this.queue.length > 0) {
const item = this.queue.shift();
await this.processItem(item);
}
this.processing = false;
}
}

Best Practices

Error Handling

try {
const result = await complexOperation();
if (!result) {
throw new Error("Operation failed");
}
return result;
} catch (error) {
console.error("Error in operation:", error);
await errorReporting.log(error);
throw new OperationalError("Failed to complete operation", { cause: error });
}

Resource Management

class ResourceManager {
private resources: Map<string, Resource> = new Map();

async acquire(id: string): Promise<Resource> {
// Implement resource acquisition with timeout
}

async release(id: string): Promise<void> {
// Implement resource cleanup
}
}

Troubleshooting

Common Issues

  1. Memory Leaks

    • Monitor memory usage
    • Implement proper cleanup
    • Use WeakMap for caching
  2. Performance Bottlenecks

    • Profile slow operations
    • Implement batching
    • Use connection pooling
  3. Integration Issues

    • Verify API credentials
    • Check network connectivity
    • Validate request formatting

Debugging

const debug = require("debug")("eliza:advanced");

debug("Detailed operation info: %O", {
operation: "complexOperation",
parameters: params,
result: result,
});

Further Resources