Integrations
Custom Tools

Custom Tools

Connect any API as a tool for your agents and flows.

Overview

Custom tools let you extend Lux by connecting external APIs. Once defined, tools can be:

  • Used by AI agents to take actions
  • Called from flows
  • Combined with other integrations

Creating a Tool

Via Lux Studio

  1. Navigate to Settings → Tools
  2. Click New Tool
  3. Configure:
    • Name and description
    • API endpoint
    • HTTP method
    • Parameters schema
    • Authentication
  4. Test the tool
  5. Save

Tool Configuration

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "endpoint": "https://api.weather.com/v1/current",
  "method": "GET",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or coordinates"
      },
      "units": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      }
    },
    "required": ["location"]
  },
  "headers": {
    "X-API-Key": "{{credentials.weatherApiKey}}"
  }
}

Parameter Schema

Define inputs using JSON Schema:

Basic Types

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" },
    "active": { "type": "boolean" },
    "score": { "type": "number" }
  }
}

With Validation

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "description": "User's email address"
    },
    "count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "status": {
      "type": "string",
      "enum": ["pending", "active", "closed"]
    }
  },
  "required": ["email"]
}

Authentication

API Key

{
  "headers": {
    "Authorization": "Bearer {{credentials.apiKey}}"
  }
}

Basic Auth

{
  "auth": {
    "type": "basic",
    "username": "{{credentials.username}}",
    "password": "{{credentials.password}}"
  }
}

Custom Headers

{
  "headers": {
    "X-API-Key": "{{credentials.apiKey}}",
    "X-Client-ID": "{{credentials.clientId}}"
  }
}

Using Tools in Agents

  1. Create the tool
  2. Open your agent settings
  3. Add the tool to the agent
  4. Reference in system prompt
# Available Tools
 
## get_weather
Get current weather for a location. Use when user asks about weather.
 
## create_ticket
Create a support ticket. Use when user has an issue that needs follow-up.
 
When using tools, call them with the required parameters and wait for results
before responding to the user.

Agent Tool Usage Example

User: "What's the weather in Seattle?"

Agent thinking: I should use the get_weather tool
Agent action: get_weather(location: "Seattle, WA")
Tool response: {"temp": 55, "condition": "cloudy", "humidity": 75}

Agent: "It's currently 55°F and cloudy in Seattle with 75% humidity."

Using Tools in Flows

Call tools using the API Request node or custom tool node:

{
  "tool": "get_weather",
  "inputs": {
    "location": "{{userLocation}}",
    "units": "fahrenheit"
  }
}

Testing Tools

Before using, test your tool:

  1. Open the tool configuration
  2. Click Test
  3. Enter sample parameters
  4. Verify response
// Test input
{
  "location": "New York"
}
 
// Expected output
{
  "temp": 72,
  "condition": "sunny"
}

Common Tool Patterns

CRM Lookup

{
  "name": "lookup_customer",
  "description": "Look up customer by email or ID",
  "endpoint": "https://crm.example.com/api/customers",
  "method": "GET",
  "parameters": {
    "properties": {
      "email": { "type": "string" },
      "customer_id": { "type": "string" }
    }
  }
}

Ticket Creation

{
  "name": "create_ticket",
  "description": "Create a support ticket",
  "endpoint": "https://support.example.com/api/tickets",
  "method": "POST",
  "parameters": {
    "properties": {
      "subject": { "type": "string" },
      "description": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] },
      "customer_email": { "type": "string" }
    },
    "required": ["subject", "description", "customer_email"]
  }
}

Calendar Check

{
  "name": "check_availability",
  "description": "Check calendar availability",
  "endpoint": "https://calendar.example.com/api/slots",
  "method": "GET",
  "parameters": {
    "properties": {
      "date": { "type": "string", "format": "date" },
      "duration": { "type": "integer" }
    },
    "required": ["date"]
  }
}

Best Practices

Tool Design

  • Clear, descriptive names
  • Detailed descriptions for AI understanding
  • Well-defined parameter schemas
  • Handle errors gracefully

Security

  • Store credentials in Lux, not in tool config
  • Use HTTPS endpoints
  • Validate inputs
  • Limit tool permissions

Performance

  • Set reasonable timeouts
  • Cache when appropriate
  • Handle rate limits

Troubleshooting

Tool Not Working

  • Test endpoint directly (curl, Postman)
  • Verify credentials
  • Check parameter format
  • Review error responses

Agent Not Using Tool

  • Improve tool description
  • Add examples to agent prompt
  • Verify tool is attached to agent

See Also:

SlackCredentials