Custom Tools — Deep Dive - Burki Voice AI Docs

For built-in tools, quick scenarios, and API links, see Tools & Custom Actions.

Custom Tools Deep Dive

Creating Custom Tools

Custom tools are created and managed through the Tools Library in your dashboard. Each tool is independent and can be assigned to multiple assistants.

Endpoint Tools
Python Functions
AWS Lambda

What are Endpoint Tools?

Endpoint tools allow your assistant to make HTTP requests to external APIs during conversations. Perfect for:

CRM lookups
Database queries
Order status checks
User authentication
Third-party integrations

Configuration

Example Tool Definition

{
  "name": "get_customer_info",
  "display_name": "Customer Information Lookup",
  "description": "Look up customer information by phone number or email",
  "parameters": {
    "type": "object",
    "properties": {
      "phone_number": {
        "type": "string",
        "description": "Customer's phone number"
      },
      "email": {
        "type": "string", 
        "description": "Customer's email address"
      }
    },
    "required": ["phone_number"]
  }
}

Endpoint Configuration

URL: https://api.yourcompany.com/customers/lookup
Method: GET, POST, PUT, DELETE
Headers: Authentication, Content-Type, etc.
Authentication: API keys, Bearer tokens, Basic auth
Timeout: Maximum execution time (default: 30 seconds)

Test your endpoint tools thoroughly. Failed API calls can interrupt conversations.

What are Python Function Tools?

Execute custom Python code during calls with access to popular libraries. Perfect for:

Complex calculations
Data processing
Business logic
API integrations with libraries
File operations

Available Libraries

Pre-installed libraries include:

requests - HTTP requests
pandas - Data manipulation
numpy - Numerical computing
datetime - Date/time operations
json - JSON processing
re - Regular expressions
math - Mathematical functions

Example Python Tool

def calculate_monthly_payment(principal, rate, years):
    """Calculate monthly loan payment"""
    monthly_rate = rate / 100 / 12
    num_payments = years * 12
    
    if monthly_rate == 0:
        return principal / num_payments
    
    payment = principal * (monthly_rate * (1 + monthly_rate) ** num_payments) / \
             ((1 + monthly_rate) ** num_payments - 1)
    
    return round(payment, 2)

# Your function should return a dictionary
return {
    "monthly_payment": calculate_monthly_payment(
        float(principal), 
        float(annual_rate), 
        int(loan_years)
    ),
    "total_paid": round(payment * years * 12, 2)
}

Security Features

Sandboxed Execution: Code runs in isolated environment
Timeout Protection: Maximum execution time limits
Resource Limits: Memory and CPU usage controls
Input Validation: Parameter validation before execution

Python tools are sandboxed but avoid executing untrusted code. Always validate inputs.

What are Lambda Tools?

Trigger AWS Lambda functions during calls for serverless, scalable processing. Perfect for:

Heavy computations
Database operations
Machine learning inference
Integration with AWS services
Scalable business logic

✨ Lambda Function Discovery

Burki Voice AI now includes automatic function discovery to make Lambda integration effortless:

Enter AWS Credentials

Provide your AWS Access Key ID and Secret Access Key in the tool configuration form.

Select Region

Choose the AWS region where your Lambda functions are deployed.

Discover Functions

Click ”🔍 Discover Functions” to automatically fetch all Lambda functions from your AWS account.

Browse & Select

Choose from a visual list showing function names, descriptions, runtime, and memory configuration.

Auto-populate

Tool details are automatically filled based on your function’s metadata.

Function Discovery Benefits:

🔍 No Guesswork: See all available functions
📊 Rich Metadata: Runtime, memory, timeout info
✅ Validation: Ensures function exists before saving
⚡ Speed: Auto-fills description and details
🛡️ Error Prevention: Reduces typos and invalid names

Configuration Options

Option 1: Function Discovery (Recommended)

Auto-discovered Function

{
  "function_name": "customer-lookup-service",
  "description": "Look up customer data by phone number",
  "runtime": "python3.9",
  "memory_size": 512,
  "timeout": 30,
  "aws_region": "us-east-1"
}

Option 2: Manual Entry

Manual Configuration

{
  "function_name": "customer-lookup-function",
  "aws_region": "us-east-1", 
  "invocation_type": "RequestResponse",
  "parameters": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "Unique customer identifier"
      }
    }
  }
}

Authentication Setup

Configure AWS credentials for function discovery and execution:

Access Key ID: Your AWS access key
Secret Access Key: Your AWS secret key
Region: AWS region containing your Lambda functions

Security Note: Credentials are stored securely and encrypted. For production, consider using IAM roles for enhanced security.

Lambda Function Requirements

Your Lambda function should:

Accept parameters in the event object
Return a JSON-serializable response
Handle errors gracefully
Complete within timeout limits (default: 30 seconds)

Example Lambda Function

import json
import boto3

def lambda_handler(event, context):
    try:
        customer_id = event.get('customer_id')
        
        # Your business logic here
        customer_data = get_customer_from_db(customer_id)
        
        return {
            'statusCode': 200,
            'body': {
                'customer_name': customer_data['name'],
                'account_status': customer_data['status'],
                'last_order': customer_data['last_order_date']
            }
        }
    except Exception as e:
        return {
            'statusCode': 500,
            'body': {'error': str(e)}
        }

Function Discovery Workflow

The discovery process provides detailed function information:

Function Discovery Response

{
  "functions": [
    {
      "function_name": "customer-lookup-service",
      "description": "Look up customer data by phone number", 
      "runtime": "python3.9",
      "timeout": 30,
      "memory_size": 512,
      "code_size": 1024000,
      "handler": "lambda_function.lambda_handler",
      "version": "$LATEST",
      "last_modified": "2024-01-15T10:30:00Z"
    },
    {
      "function_name": "order-processing",
      "description": "Process customer orders and payments",
      "runtime": "nodejs18.x",
      "timeout": 60,
      "memory_size": 1024,
      "handler": "index.handler"
    }
  ]
}

IAM Permissions Required

For function discovery to work, your AWS credentials need the following permissions:

IAM Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:ListFunctions",
        "lambda:GetFunction", 
        "lambda:GetFunctionConfiguration",
        "lambda:InvokeFunction"
      ],
      "Resource": "*"
    }
  ]
}

Security Best Practice: Create a dedicated IAM user for Burki Voice AI with minimal required permissions. Never use your root AWS credentials.

Tool Testing & Validation

Before deploying tools to production:

Testing Checklist

Parameter Validation:
- Test with valid parameters
- Test with invalid/missing parameters
- Verify parameter type conversion
Error Handling:
- Network timeouts
- API errors (4xx, 5xx)
- Invalid responses
- Service unavailability
Performance:
- Response times under load
- Timeout scenarios
- Rate limiting behavior
Security:
- Input sanitization
- Authentication validation
- Data privacy compliance

Best Practices

Tool Design Best Practices

Keep It Simple:

One tool, one purpose
Clear, descriptive names
Minimal required parameters

Handle Errors Gracefully:

Return meaningful error messages
Provide fallback responses
Log errors for debugging

Optimize Performance:

Cache frequently accessed data
Use efficient APIs
Set appropriate timeouts

Security First:

Validate all inputs
Use secure authentication
Follow data privacy rules
Audit tool usage regularly

Tool Assignment & Management

Managing Tools Across Assistants

Tool Library Workflow:

Create tools in the Tools Library
Test tools with sample data
Assign tools to specific assistants
Monitor usage and performance
Update tools as needed

Assignment Benefits:

Reusability: Use the same tool across multiple assistants
Consistency: Standardize integrations across your organization
Maintenance: Update tools in one place, apply everywhere
Governance: Control which assistants can use specific tools

Usage Analytics:

Track tool execution frequency
Monitor success/failure rates
Analyze performance metrics
Identify optimization opportunities

Tool Integration Examples

Customer Service Use Cases

CRM Integration

{
  "name": "lookup_customer",
  "tool_type": "endpoint",
  "endpoint_url": "https://api.salesforce.com/services/data/v52.0/query",
  "description": "Look up customer information from Salesforce CRM"
}

Use Case: Assistant can instantly access customer history, preferences, and previous interactions during calls.

Order Status Check

def get_order_status(order_number):
    """Look up order status from internal database"""
    import requests
    
    response = requests.get(f"https://internal-api.company.com/orders/{order_number}")
    order_data = response.json()
    
    return {
        "status": order_data["status"],
        "estimated_delivery": order_data["delivery_date"],
        "tracking_number": order_data["tracking"]
    }

Use Case: Customers can get real-time order updates without transferring to human agents.

Sales & Lead Qualification

Lead Scoring

{
  "name": "calculate_lead_score",
  "tool_type": "lambda",
  "function_name": "lead-scoring-ml-model",
  "description": "Calculate lead score using ML model"
}

Use Case: Assistant gathers information and provides real-time lead scoring to prioritize follow-ups.

Product Recommendations

def get_product_recommendations(customer_profile, budget):
    """Generate personalized product recommendations"""
    # Business logic for recommendations
    recommendations = analyze_customer_preferences(customer_profile, budget)
    
    return {
        "recommended_products": recommendations,
        "reasoning": "Based on your preferences and budget",
        "next_steps": "Schedule a demo call"
    }

Use Case: Provide personalized product suggestions during sales calls.

Technical Support

System Status Check

{
  "name": "check_system_status",
  "tool_type": "endpoint", 
  "endpoint_url": "https://status-api.company.com/health",
  "description": "Check if customer's systems are experiencing issues"
}

Use Case: Proactively identify system issues before customers report them.

Troubleshooting Assistant

def diagnose_connectivity_issue(ip_address, error_code):
    """Diagnose network connectivity issues"""
    import subprocess
    import json
    
    # Run network diagnostics
    ping_result = subprocess.run(['ping', '-c', '3', ip_address], 
                               capture_output=True, text=True)
    
    return {
        "connectivity": "good" if ping_result.returncode == 0 else "poor",
        "recommended_action": get_action_for_error(error_code),
        "escalate_to_tech": ping_result.returncode != 0
    }

Use Case: Provide first-level technical diagnostics and troubleshooting.

Getting Started

Core Concepts

AI Providers

Features

Advanced

Help & Resources

Custom Tools — Deep Dive