API Integrations

Connect agents with external APIs and services

8 min

API Integrations

Learn how to connect your Fantomu agents with external APIs and services to extend their capabilities.

Overview

API integrations allow your agents to:

Fetch data from external services

Send data to third-party platforms

Trigger actions in other systems

Access real-time information

Supported Integration Types

REST APIs

Most common integration type for web services.

javascript

// Configure REST API integration
await agent.integrations.add({
  type: 'rest_api',
  name: 'Weather Service',
  baseUrl: 'https://api.weather.com/v1',
  authentication: {
    type: 'api_key',
    key: 'weather_api_key',
    header: 'X-API-Key'
  },
  endpoints: {
    current: '/current',
    forecast: '/forecast'
  }
});

GraphQL APIs

For more complex data queries and mutations.

javascript

// Configure GraphQL integration
await agent.integrations.add({
  type: 'graphql',
  name: 'Content Management',
  endpoint: 'https://api.cms.com/graphql',
  authentication: {
    type: 'bearer_token',
    token: 'cms_bearer_token'
  },
  queries: {
    getPosts: `query GetPosts($limit: Int) {
        posts(limit: $limit) {
          id
          title
          content
          publishedAt
        }
      }`
  }
});

WebSocket Connections

For real-time data streaming.

javascript

// Configure WebSocket integration
await agent.integrations.add({
  type: 'websocket',
  name: 'Real-time Updates',
  url: 'wss://api.realtime.com/stream',
  authentication: {
    type: 'query_param',
    key: 'token',
    value: 'realtime_token'
  },
  events: {
    'user_online': 'handleUserOnline',
    'message_received': 'handleMessage'
  }
});

Authentication Methods

API Key Authentication

javascript

const integration = {
  type: 'rest_api',
  authentication: {
    type: 'api_key',
    key: 'your_api_key',
    header: 'Authorization', // or 'X-API-Key'
    prefix: 'Bearer' // optional
  }
};

OAuth 2.0

javascript

const integration = {
  type: 'oauth2',
  authentication: {
    clientId: 'your_client_id',
    clientSecret: 'your_client_secret',
    authorizationUrl: 'https://api.service.com/oauth/authorize',
    tokenUrl: 'https://api.service.com/oauth/token',
    scope: ['read', 'write'],
    redirectUri: 'https://your-app.com/oauth/callback'
  }
};

Basic Authentication

javascript

const integration = {
  type: 'rest_api',
  authentication: {
    type: 'basic',
    username: 'your_username',
    password: 'your_password'
  }
};

Using Integrations in Tasks

Simple API Call

javascript

const result = await agent.execute({
  task: 'Get current weather for New York',
  context: {
    city: 'New York',
    integration: 'weather_service'
  }
});

Complex API Workflow

javascript

const result = await agent.execute({
  task: 'Create a new blog post and publish it',
  context: {
    title: 'AI Trends 2024',
    content: 'Content about AI trends...',
    integrations: {
      cms: 'content_management',
      social: 'social_media'
    }
  }
});

Error Handling

Retry Logic

javascript

const integration = {
  type: 'rest_api',
  errorHandling: {
    retries: 3,
    retryDelay: 1000,
    retryCondition: (error) => error.status >= 500
  }
};

Fallback Strategies

javascript

const integration = {
  type: 'rest_api',
  errorHandling: {
    onError: 'use_cached_data',
    fallback: {
      type: 'cache',
      ttl: 3600 // 1 hour
    }
  }
};

Rate Limiting

Configure Rate Limits

javascript

const integration = {
  type: 'rest_api',
  rateLimiting: {
    requestsPerMinute: 60,
    requestsPerHour: 1000,
    burstLimit: 10
  }
};

Handle Rate Limits

javascript

const integration = {
  type: 'rest_api',
  rateLimiting: {
    onLimitExceeded: 'wait_and_retry',
    backoffStrategy: 'exponential'
  }
};

Data Transformation

Input Transformation

javascript

const integration = {
  type: 'rest_api',
  transformations: {
    input: (data) => ({
      query: data.searchTerm,
      limit: data.maxResults || 10,
      sort: data.sortBy || 'relevance'
    })
  }
};

Output Transformation

javascript

const integration = {
  type: 'rest_api',
  transformations: {
    output: (response) => ({
      results: response.data.items.map(item => ({
        id: item.id,
        title: item.title,
        url: item.link,
        snippet: item.snippet
      })),
      total: response.data.totalResults
    })
  }
};

Testing Integrations

Unit Testing

javascript

// Test integration configuration
const testResult = await agent.testIntegration({
  integrationId: 'weather_service',
  testData: {
    city: 'London',
    country: 'UK'
  }
});

console.log('Integration test result:', testResult);

Integration Testing

javascript

// Test with real API
const liveTest = await agent.testIntegration({
  integrationId: 'weather_service',
  live: true,
  testData: {
    city: 'London',
    country: 'UK'
  }
});

Monitoring and Logging

Integration Metrics

javascript

const metrics = await agent.getIntegrationMetrics({
  integrationId: 'weather_service',
  period: '7d',
  metrics: [
    'request_count',
    'success_rate',
    'average_response_time',
    'error_rate'
  ]
});

Integration Logs

javascript

const logs = await agent.getIntegrationLogs({
  integrationId: 'weather_service',
  level: 'error',
  limit: 100
});

Best Practices

1. Security

Store credentials securely

Use environment variables

Implement proper authentication

Validate all inputs

2. Performance

Implement caching where appropriate

Use connection pooling

Monitor response times

Handle rate limits gracefully

3. Reliability

Implement retry logic

Use circuit breakers

Have fallback strategies

Monitor error rates

4. Testing

Test with real APIs

Simulate error conditions

Validate data transformations

Monitor in production

Next Steps

Learn about [Webhooks](/docs/integrations/webhooks)

Explore [Database Connections](/docs/integrations/databases)

Check out [Third-party Connectors](/docs/integrations/connectors)

Webhooks

Set up webhooks for real-time notifications

6 min

Webhooks

Learn how to set up and use webhooks to receive real-time notifications from Fantomu agents and external services.

What are Webhooks?

Webhooks are HTTP callbacks that allow external services to send real-time notifications to your application when specific events occur. They enable:

Real-time Updates: Get notified immediately when events happen

Event-driven Architecture: Build reactive systems

Integration: Connect with external services seamlessly

Webhook Events

Agent Events

Events related to agent execution and performance.

javascript

// Configure agent webhooks
await agent.webhooks.create({
  url: 'https://your-app.com/webhooks/agent',
  events: [
    'task_started',
    'task_completed',
    'task_failed',
    'agent_updated'
  ],
  secret: 'your_webhook_secret'
});

Workflow Events

Events related to workflow execution.

javascript

// Configure workflow webhooks
await workflow.webhooks.create({
  url: 'https://your-app.com/webhooks/workflow',
  events: [
    'workflow_started',
    'workflow_completed',
    'workflow_failed',
    'step_completed'
  ],
  secret: 'your_webhook_secret'
});

Custom Events

Define your own custom events.

javascript

// Configure custom webhooks
await agent.webhooks.create({
  url: 'https://your-app.com/webhooks/custom',
  events: [
    'user_registered',
    'payment_completed',
    'content_published'
  ],
  secret: 'your_webhook_secret'
});

Webhook Payload Structure

Standard Payload

json

{
  "event": "task_completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "agentId": "agent_123",
    "taskId": "task_456",
    "executionId": "exec_789",
    "result": {
      "success": true,
      "output": "Task completed successfully"
    },
    "duration": 1500,
    "metadata": {
      "userId": "user_123",
      "sessionId": "session_456"
    }
  }
}

Custom Payload

javascript

// Configure custom payload
await agent.webhooks.create({
  url: 'https://your-app.com/webhooks/custom',
  events: ['task_completed'],
  payload: {
    customField: 'custom_value',
    includeMetadata: true,
    transform: (data) => ({
      id: data.taskId,
      status: data.result.success ? 'success' : 'failed',
      timestamp: data.timestamp
    })
  }
});

Webhook Security

Signature Verification

javascript

// Verify webhook signature
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Secret Management

javascript

// Store webhook secrets securely
const webhookSecret = process.env.WEBHOOK_SECRET;

await agent.webhooks.create({
  url: 'https://your-app.com/webhooks/agent',
  events: ['task_completed'],
  secret: webhookSecret
});

Handling Webhooks

Express.js Example

javascript

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.raw({ type: 'application/json' }));

app.post('/webhooks/agent', (req, res) => {
  const signature = req.headers['x-fantomu-signature'];
  const payload = req.body;
  
  // Verify signature
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  
  // Handle the event
  switch (event.event) {
    case 'task_completed':
      handleTaskCompleted(event.data);
      break;
    case 'task_failed':
      handleTaskFailed(event.data);
      break;
    default:
      console.log('Unknown event:', event.event);
  }
  
  res.status(200).send('OK');
});

Next.js API Route

javascript

// pages/api/webhooks/agent.js
import crypto from 'crypto';

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method not allowed' });
  }
  
  const signature = req.headers['x-fantomu-signature'];
  const payload = JSON.stringify(req.body);
  
  // Verify signature
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).json({ message: 'Invalid signature' });
  }
  
  const event = req.body;
  
  // Handle the event
  await handleWebhookEvent(event);
  
  res.status(200).json({ message: 'OK' });
}

Webhook Retry Logic

Automatic Retries

javascript

// Configure retry logic
await agent.webhooks.create({
  url: 'https://your-app.com/webhooks/agent',
  events: ['task_completed'],
  retry: {
    maxAttempts: 3,
    backoffStrategy: 'exponential',
    maxDelay: 30000
  }
});

Manual Retry

javascript

// Retry failed webhook
await agent.webhooks.retry({
  webhookId: 'webhook_123',
  eventId: 'event_456'
});

Webhook Monitoring

Delivery Status

javascript

// Check webhook delivery status
const status = await agent.webhooks.getStatus({
  webhookId: 'webhook_123',
  eventId: 'event_456'
});

console.log('Delivery status:', status);

Webhook Analytics

javascript

// Get webhook analytics
const analytics = await agent.webhooks.getAnalytics({
  webhookId: 'webhook_123',
  period: '7d',
  metrics: [
    'delivery_rate',
    'success_rate',
    'average_response_time',
    'error_rate'
  ]
});

Testing Webhooks

Webhook Testing

javascript

// Test webhook endpoint
const testResult = await agent.webhooks.test({
  webhookId: 'webhook_123',
  testEvent: {
    event: 'task_completed',
    data: {
      taskId: 'test_task',
      result: { success: true }
    }
  }
});

Local Development

javascript

// Use ngrok for local testing
const webhook = await agent.webhooks.create({
  url: 'https://abc123.ngrok.io/webhooks/agent',
  events: ['task_completed'],
  secret: 'your_webhook_secret'
});

Best Practices

1. Security

Always verify webhook signatures

Use HTTPS endpoints

Store secrets securely

Implement proper authentication

2. Reliability

Implement idempotency

Handle duplicate events

Use proper error handling

Monitor delivery status

3. Performance

Respond quickly to webhooks

Use async processing

Implement proper logging

Monitor response times

4. Testing

Test with real webhooks

Simulate failure scenarios

Validate payload structure

Monitor in production

Next Steps

Learn about [Database Connections](/docs/integrations/databases)

Explore [Third-party Connectors](/docs/integrations/connectors)

Check out [Monitoring](/docs/monitoring)

Database Connections

Connect agents to databases for data persistence

7 min

Database Connections

Learn how to connect your Fantomu agents to databases for data persistence, querying, and real-time updates.

Supported Databases

SQL Databases

PostgreSQL

MySQL

SQLite

SQL Server

Oracle

NoSQL Databases

MongoDB

Redis

DynamoDB

Cassandra

Elasticsearch

Cloud Databases

AWS RDS

Google Cloud SQL

Azure SQL Database

PlanetScale

Supabase

Database Configuration

PostgreSQL Connection

javascript

// Configure PostgreSQL connection
await agent.databases.add({
  name: 'main_database',
  type: 'postgresql',
  connection: {
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    database: process.env.DB_NAME,
    username: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    ssl: true
  },
  pool: {
    min: 2,
    max: 10,
    idleTimeoutMillis: 30000
  }
});

MongoDB Connection

javascript

// Configure MongoDB connection
await agent.databases.add({
  name: 'document_store',
  type: 'mongodb',
  connection: {
    uri: process.env.MONGODB_URI,
    database: 'myapp',
    options: {
      useNewUrlParser: true,
      useUnifiedTopology: true
    }
  }
});

Redis Connection

javascript

// Configure Redis connection
await agent.databases.add({
  name: 'cache_store',
  type: 'redis',
  connection: {
    host: process.env.REDIS_HOST,
    port: process.env.REDIS_PORT,
    password: process.env.REDIS_PASSWORD,
    db: 0
  }
});

Querying Data

SQL Queries

javascript

// Execute SQL query
const result = await agent.execute({
  task: 'Get user information',
  context: {
    database: 'main_database',
    query: 'SELECT * FROM users WHERE id = ?',
    parameters: [userId]
  }
});

MongoDB Queries

javascript

// Execute MongoDB query
const result = await agent.execute({
  task: 'Find user documents',
  context: {
    database: 'document_store',
    collection: 'users',
    query: {
      status: 'active',
      createdAt: { $gte: new Date('2024-01-01') }
    }
  }
});

Redis Operations

javascript

// Execute Redis operations
const result = await agent.execute({
  task: 'Cache user session',
  context: {
    database: 'cache_store',
    operation: 'set',
    key: `session:${sessionId}`,
    value: JSON.stringify(sessionData),
    ttl: 3600
  }
});

Data Operations

Insert Operations

javascript

// Insert new record
const result = await agent.execute({
  task: 'Create new user',
  context: {
    database: 'main_database',
    operation: 'insert',
    table: 'users',
    data: {
      name: 'John Doe',
      email: 'john@example.com',
      createdAt: new Date()
    }
  }
});

Update Operations

javascript

// Update existing record
const result = await agent.execute({
  task: 'Update user profile',
  context: {
    database: 'main_database',
    operation: 'update',
    table: 'users',
    where: { id: userId },
    data: {
      name: 'John Smith',
      updatedAt: new Date()
    }
  }
});

Delete Operations

javascript

// Delete record
const result = await agent.execute({
  task: 'Delete user account',
  context: {
    database: 'main_database',
    operation: 'delete',
    table: 'users',
    where: { id: userId }
  }
});

Transaction Management

SQL Transactions

javascript

// Execute transaction
const result = await agent.execute({
  task: 'Transfer funds between accounts',
  context: {
    database: 'main_database',
    transaction: true,
    operations: [
      {
        type: 'update',
        table: 'accounts',
        where: { id: fromAccountId },
        data: { balance: 'balance - ?' },
        parameters: [amount]
      },
      {
        type: 'update',
        table: 'accounts',
        where: { id: toAccountId },
        data: { balance: 'balance + ?' },
        parameters: [amount]
      }
    ]
  }
});

MongoDB Transactions

javascript

// Execute MongoDB transaction
const result = await agent.execute({
  task: 'Update multiple documents',
  context: {
    database: 'document_store',
    transaction: true,
    operations: [
      {
        collection: 'users',
        operation: 'updateOne',
        filter: { _id: userId },
        update: { $set: { status: 'inactive' } }
      },
      {
        collection: 'sessions',
        operation: 'deleteMany',
        filter: { userId: userId }
      }
    ]
  }
});

Data Validation

Schema Validation

javascript

// Configure schema validation
await agent.databases.configureValidation({
  database: 'main_database',
  table: 'users',
  schema: {
    name: { type: 'string', required: true, maxLength: 100 },
    email: { type: 'string', required: true, format: 'email' },
    age: { type: 'number', min: 0, max: 150 }
  }
});

Data Sanitization

javascript

// Configure data sanitization
await agent.databases.configureSanitization({
  database: 'main_database',
  table: 'users',
  sanitization: {
    name: 'trim,escape',
    email: 'trim,lowercase',
    bio: 'trim,stripHtml'
  }
});

Performance Optimization

Connection Pooling

javascript

// Configure connection pooling
await agent.databases.configurePooling({
  database: 'main_database',
  pool: {
    min: 5,
    max: 20,
    acquireTimeoutMillis: 60000,
    idleTimeoutMillis: 300000
  }
});

Query Optimization

javascript

// Configure query optimization
await agent.databases.configureOptimization({
  database: 'main_database',
  optimization: {
    enableQueryCache: true,
    cacheSize: 1000,
    enableIndexHints: true,
    maxQueryTime: 5000
  }
});

Caching

javascript

// Configure database caching
await agent.databases.configureCaching({
  database: 'main_database',
  cache: {
    enabled: true,
    ttl: 300, // 5 minutes
    maxSize: 10000,
    strategy: 'lru'
  }
});

Monitoring and Logging

Database Metrics

javascript

// Get database metrics
const metrics = await agent.databases.getMetrics({
  database: 'main_database',
  period: '1h',
  metrics: [
    'connection_count',
    'query_count',
    'average_query_time',
    'error_rate'
  ]
});

Query Logging

javascript

// Configure query logging
await agent.databases.configureLogging({
  database: 'main_database',
  logging: {
    enabled: true,
    level: 'info',
    logSlowQueries: true,
    slowQueryThreshold: 1000
  }
});

Security

Access Control

javascript

// Configure access control
await agent.databases.configureAccess({
  database: 'main_database',
  access: {
    readOnly: false,
    allowedTables: ['users', 'posts'],
    restrictedColumns: ['password', 'ssn'],
    ipWhitelist: ['192.168.1.0/24']
  }
});

Encryption

javascript

// Configure encryption
await agent.databases.configureEncryption({
  database: 'main_database',
  encryption: {
    enabled: true,
    algorithm: 'AES-256-GCM',
    keyRotation: 'monthly'
  }
});

Best Practices

1. Security

Use connection strings from environment variables

Implement proper access controls

Encrypt sensitive data

Regular security audits

2. Performance

Use connection pooling

Optimize queries

Implement caching

Monitor performance metrics

3. Reliability

Use transactions for critical operations

Implement proper error handling

Have backup strategies

Monitor database health

4. Testing

Test with real databases

Simulate failure scenarios

Validate data integrity

Monitor in production

Next Steps

Learn about [Third-party Connectors](/docs/integrations/connectors)

Explore [Monitoring](/docs/monitoring)

Check out [Deployment](/docs/deployment)