Integration SDK

Integration Manifest
  |
  +-- Connection Config  (how to authenticate)
  +-- Tool Definitions   (what the agent can do)
  +-- Sync Config        (how to fetch data)
  +-- Webhook Config     (how to receive updates)
       |
       v
  Integration Registry  -->  Agent Tool Injection

import { defineIntegration } from '@agentix/sdk/integrations'
 
export const myIntegration = defineIntegration({
  id: 'my-crm',
  name: 'My CRM',
  description: 'Connect your CRM to let agents look up contacts and deals',
  version: '1.0.0',
  icon: 'database',
 
  // Connection configuration
  connection: {
    type: 'api-key',
    fields: [
      {
        key: 'apiKey',
        label: 'API Key',
        type: 'password',
        required: true,
        helpText: 'Find this in Settings > API',
      },
      {
        key: 'baseUrl',
        label: 'Instance URL',
        type: 'url',
        required: true,
        placeholder: 'https://your-instance.crm.com',
      },
    ],
    testConnection: async (config) => {
      const response = await fetch(`${config.baseUrl}/api/me`, {
        headers: { Authorization: `Bearer ${config.apiKey}` },
      })
      return response.ok
    },
  },
 
  // Tool definitions
  tools: [
    {
      name: 'search_contacts',
      description: 'Search for contacts by name, email, or phone',
      parameters: {
        type: 'object',
        properties: {
          query: { type: 'string', description: 'Search query' },
          limit: { type: 'number', description: 'Max results', default: 5 },
        },
        required: ['query'],
      },
      execute: async (params, context) => {
        const { query, limit = 5 } = params
        const { connection } = context
 
        const response = await fetch(
          `${connection.baseUrl}/api/contacts?q=${encodeURIComponent(query)}&limit=${limit}`,
          { headers: { Authorization: `Bearer ${connection.apiKey}` } }
        )
 
        return response.json()
      },
    },
    {
      name: 'get_contact',
      description: 'Get detailed information about a specific contact',
      parameters: {
        type: 'object',
        properties: {
          contactId: { type: 'string', description: 'Contact ID' },
        },
        required: ['contactId'],
      },
      execute: async (params, context) => {
        const response = await fetch(
          `${context.connection.baseUrl}/api/contacts/${params.contactId}`,
          { headers: { Authorization: `Bearer ${context.connection.apiKey}` } }
        )
        return response.json()
      },
    },
  ],
})

import { createTool } from '@agentix/sdk/integrations'
 
const searchProducts = createTool('search_products')
  .description('Search the product catalog')
  .parameter('query', 'string', 'Search query', { required: true })
  .parameter('category', 'string', 'Filter by category')
  .parameter('minPrice', 'number', 'Minimum price')
  .parameter('maxPrice', 'number', 'Maximum price')
  .parameter('limit', 'number', 'Max results', { default: 10 })
  .handler(async (params, context) => {
    // Your implementation
    return { products: [] }
  })
  .build()

import { IntegrationRegistry } from '@agentix/sdk/integrations'
 
const registry = new IntegrationRegistry()
 
// Register integration
registry.register(myIntegration)
 
// List all registered integrations
const integrations = registry.list()
 
// Get a specific integration
const crm = registry.get('my-crm')

connection: {
  type: 'api-key',
  fields: [
    { key: 'apiKey', label: 'API Key', type: 'password', required: true },
  ],
}

connection: {
  type: 'oauth2',
  authorizationUrl: 'https://service.com/oauth/authorize',
  tokenUrl: 'https://service.com/oauth/token',
  scopes: ['read', 'write'],
  fields: [
    { key: 'clientId', label: 'Client ID', type: 'text', required: true },
    { key: 'clientSecret', label: 'Client Secret', type: 'password', required: true },
  ],
}

connection: {
  type: 'basic',
  fields: [
    { key: 'username', label: 'Username', type: 'text', required: true },
    { key: 'password', label: 'Password', type: 'password', required: true },
  ],
}

sync: {
  // How often to sync (cron expression)
  schedule: '0 */6 * * *', // Every 6 hours
 
  // What to sync
  resources: [
    {
      name: 'products',
      fetch: async (context, options) => {
        const response = await fetch(
          `${context.connection.baseUrl}/api/products`,
          { headers: { Authorization: `Bearer ${context.connection.apiKey}` } }
        )
        const products = await response.json()
 
        return products.map(product => ({
          id: product.id,
          title: product.name,
          content: `${product.name} - ${product.description}. Price: $${product.price}`,
          metadata: {
            price: product.price,
            category: product.category,
            sku: product.sku,
          },
        }))
      },
    },
  ],
}

webhooks: {
  // Webhook endpoint path
  path: '/webhooks/my-crm',
 
  // Verify webhook signatures
  verify: (request, secret) => {
    const signature = request.headers['x-webhook-signature']
    return verifyHmac(request.body, secret, signature)
  },
 
  // Handle incoming events
  handlers: {
    'contact.created': async (payload, context) => {
      // Process new contact
      await context.syncResource('contacts', payload.contact.id)
    },
    'contact.updated': async (payload, context) => {
      // Update existing contact data
      await context.syncResource('contacts', payload.contact.id)
    },
  },
}

import { testIntegration } from '@agentix/sdk/integrations/testing'
 
describe('My CRM Integration', () => {
  it('should search contacts', async () => {
    const result = await testIntegration(myIntegration, {
      tool: 'search_contacts',
      params: { query: 'John' },
      connection: {
        apiKey: 'test-key',
        baseUrl: 'https://mock.crm.com',
      },
    })
 
    expect(result.contacts).toHaveLength(1)
    expect(result.contacts[0].name).toBe('John Doe')
  })
})