Integrations (Apps)

AI Builder supports various integration approaches:

• API Integrations: Connect to external services via REST, GraphQL, or other API protocols
• Database Connections: Access and manipulate data in various database systems
• Webhook Mechanisms: Receive and send event notifications to external systems
• File System Operations: Read, write, and process files in various formats
• Authentication Systems: Connect with identity providers and SSO solutions
• Marketplace Apps: Pre-built integrations installed from the app marketplace

Each type serves different integration needs and scenarios.

AI Builder integrations follow a modern, secure architecture:

• Isolation: Each integration operates in its own secure context
• Authentication: Secure credential management and authentication flows
• Authorization: Fine-grained access control to integration capabilities
• Monitoring: Comprehensive logging and performance tracking
• Error Handling: Robust error management and recovery mechanisms

This architecture ensures reliable, secure integrations with external systems.

Integrations can be implemented through:

• Built-in Instructions: Using pre-built automation instructions for common integration patterns
• Marketplace Apps: Installing pre-configured integration apps
• Custom Development: Creating specialized integration logic with code
• API Configuration: Setting up connections to external APIs and services
• Authentication Setup: Configuring secure access to protected resources

The flexibility of implementation approaches accommodates various technical requirements.

Connect to SQL databases such as:

• MySQL
• PostgreSQL
• SQL Server
• Oracle
• SQLite

Example configuration for a PostgreSQL connection:

connection:
  type: postgresql
  host: database.example.com
  port: 5432
  database: customer_data
  username: "{{secrets.DB_USERNAME}}"
  password: "{{secrets.DB_PASSWORD}}"
  ssl: true
  pool:
    min: 5
    max: 20

Connect to document, key-value, and graph databases:

• MongoDB
• Cosmos DB
• Redis
• Cassandra
• Neo4j

Example configuration for a MongoDB connection:

connection:
  type: mongodb
  uri: "mongodb+srv://{{secrets.MONGO_USERNAME}}:{{secrets.MONGO_PASSWORD}}@cluster.example.mongodb.net"
  database: analytics
  options:
    retryWrites: true
    w: majority
    maxPoolSize: 10

Connect to specialized vector databases for AI applications:

• Pinecone
• Weaviate
• Milvus
• Qdrant
• ChromaDB

Example configuration for a Pinecone connection:

connection:
  type: pinecone
  apiKey: "{{secrets.PINECONE_API_KEY}}"
  environment: us-west1-gcp
  projectId: "e12345-abc-123"
  namespace: customer-support
  dimensions: 1536

Authenticate with external services:

• API Keys: Simple key-based authentication
• OAuth 2.0: Token-based authentication with various flows
  • Authorization Code
  • Client Credentials
  • Resource Owner Password
  • Implicit Flow
• Bearer Tokens: Token-based authentication
• Basic Authentication: Username/password encoded in headers
• Custom Authentication: Specialized methods for specific services

Securely store and use sensitive credentials:

• Workspace Secrets: Store sensitive values
• Reference Notation: {{secrets.KEY_NAME}} syntax
• Access Control: Restricted visibility of secret values
• Version History: Track credential changes
• Environment Separation: Different secrets per environment

Control access to integration capabilities:

• Role-Based Access Control: Limit integration usage by role
• Scopes: Fine-grained permissions for API access
• IP Restrictions: Limit integration access by network
• Rate Limiting: Control usage frequency
• Usage Quotas: Set limits on integration usage

Create integrations using existing automation capabilities:

• Combine HTTP requests with data transformations
• Set up authentication flows
• Implement error handling and retries
• Create event-based integration patterns
• Build data synchronization processes

This approach requires no coding but may be limited for complex scenarios.

Develop integrations with JavaScript/TypeScript:

• Use the full power of programming languages
• Implement complex business logic
• Leverage npm libraries for integration
• Create sophisticated data processing
• Optimize performance for specific needs

This approach provides maximum flexibility for complex integration requirements.

// Example custom code for a specialized API integration
async function integrateWithSpecializedService(data, apiKey) {
  try {
    // Prepare the data according to the service's requirements
    const transformedData = transformForService(data);
    
    // Make the API request with proper authentication
    const response = await fetch('https://api.specialized-service.com/endpoint', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`,
        'X-Custom-Header': 'Value'
      },
      body: JSON.stringify(transformedData)
    });
    
    // Process the response
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API Error: ${errorData.message || response.statusText}`);
    }
    
    const result = await response.json();
    
    // Post-process the response data
    return processServiceResponse(result);
  } catch (error) {
    console.error('Integration error:', error);
    throw error;
  }
}

Package integrations as reusable apps:

• Create self-contained integration packages
• Include both UI components and backend logic
• Provide configuration interfaces
• Enable easy deployment across workspaces
• Share with other teams or organizations

This approach is ideal for integrations that will be used repeatedly across projects.

# Example app manifest for a custom integration
app:
  name: Custom CRM Integration
  version: 1.0.0
  description: Integration with our proprietary CRM system
  author: Enterprise Integration Team
  
components:
  blocks:
    - name: CRM Customer Lookup
      slug: crm-customer-lookup
      description: Search for customers in the CRM
      
    - name: CRM Ticket Creator
      slug: crm-ticket-creator
      description: Create support tickets in the CRM
      
  automations:
    - name: CRM Data Sync
      slug: crm-data-sync
      description: Synchronize data with the CRM
      
    - name: CRM Webhook Handler
      slug: crm-webhook-handler
      description: Process webhooks from the CRM
      
configuration:
  - name: API Endpoint
    type: string
    required: true
    description: The base URL of the CRM API
    
  - name: Authentication Method
    type: select
    options:
      - apiKey
      - oauth2
      - jwt
    default: apiKey
    description: Authentication method to use with the CRM

Subscribe to document events to enhance the knowledge base:

• documents_created: Triggered when new documents are added
• documents_updated: Triggered when documents are modified
• documents_deleted: Triggered when documents are removed

Example use cases:

• Custom document processing pipelines
• Content enrichment with additional metadata
• Advanced document validation
• Integration with document management systems

Intercept and enhance user queries:

• queries: Triggered when users ask questions

Response options:

• Return custom chunks for context inclusion
• Generate complete prompts for the LLM
• Provide entire answers, bypassing the LLM
• Override AI parameters for specific queries

Example use cases:

• Custom retrieval strategies
• Multi-step reasoning pipelines
• Integration with specialized knowledge sources
• Query routing to different processing paths

Customize the testing and evaluation process:

• tests_results: Triggered for each test case execution

Response options:

• Provide custom analysis of test results
• Return context and answer scores
• Implement specialized evaluation criteria

Example use cases:

• Domain-specific evaluation metrics
• Integration with quality management systems
• Custom test analytics and reporting
• Comparative analysis across models