Tools & Functions

Enable your agent to take actions and call external services

Enable your AI agent to take actions by configuring tools and functions.

What are Agent Tools?

Tools extend your agent's capabilities beyond conversation. With tools, agents can:

  • Call external APIs
  • Query databases
  • Send notifications
  • Execute custom logic
  • Interact with other systems

How Tools Work

┌─────────────────────────────────────────────────────────────┐
│                      Tool Execution Flow                     │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   User: "What's the status of order #12345?"                │
│                    │                                         │
│                    ▼                                         │
│   ┌────────────────────────────────────┐                    │
│   │         Agent Processing           │                    │
│   │  - Understands user intent         │                    │
│   │  - Identifies tool to use          │                    │
│   │  - Extracts parameters             │                    │
│   └────────────────┬───────────────────┘                    │
│                    │                                         │
│                    ▼                                         │
│   ┌────────────────────────────────────┐                    │
│   │      Tool: get_order_status        │                    │
│   │      Parameters: {order_id: 12345} │                    │
│   └────────────────┬───────────────────┘                    │
│                    │                                         │
│                    ▼                                         │
│   ┌────────────────────────────────────┐                    │
│   │         Tool Execution             │                    │
│   │  → Call Order API                  │                    │
│   │  ← Response: {status: "shipped"}   │                    │
│   └────────────────┬───────────────────┘                    │
│                    │                                         │
│                    ▼                                         │
│   Agent: "Order #12345 has been shipped and is              │
│           on its way to you!"                                │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Built-in Tools

HTTP Request

Make API calls to external services:

json
{
  "name": "http_request",
  "description": "Make HTTP requests to external APIs",
  "config": {
    "allowed_domains": ["api.example.com"],
    "timeout_ms": 5000,
    "auth": {
      "type": "bearer",
      "token_credential": "api-token"
    }
  }
}

Database Query

Query your databases:

json
{
  "name": "database_query",
  "description": "Query the customer database",
  "config": {
    "connection": "postgres-main",
    "allowed_tables": ["customers", "orders"],
    "read_only": true
  }
}

Send Email

Send emails through configured providers:

json
{
  "name": "send_email",
  "description": "Send email to customers",
  "config": {
    "provider": "sendgrid",
    "from_email": "support@company.com",
    "templates": ["welcome", "order-confirmation"]
  }
}

Create Ticket

Create support tickets:

json
{
  "name": "create_ticket",
  "description": "Create a support ticket for complex issues",
  "config": {
    "system": "zendesk",
    "default_priority": "medium",
    "auto_assign": true
  }
}

Creating Custom Tools

Tool Definition

Define a custom tool with JSON Schema:

json
{
  "name": "get_order_status",
  "description": "Retrieve the current status of a customer order",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The unique order identifier"
      },
      "include_tracking": {
        "type": "boolean",
        "description": "Whether to include tracking information",
        "default": false
      }
    },
    "required": ["order_id"]
  }
}

Implementation Options

1. Webhook Implementation

Point to your own endpoint:

json
{
  "name": "get_order_status",
  "implementation": {
    "type": "webhook",
    "url": "https://api.yourcompany.com/tools/order-status",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{credentials.api_token}}"
    }
  }
}

2. Direct API Call

Call an external API directly:

json
{
  "name": "get_weather",
  "implementation": {
    "type": "http",
    "url": "https://api.weather.com/v1/current",
    "method": "GET",
    "query_params": {
      "location": "{{parameters.city}}",
      "apikey": "{{credentials.weather_api_key}}"
    }
  }
}

3. Built-in Function

Use ArcanFlows built-in functions:

json
{
  "name": "calculate_shipping",
  "implementation": {
    "type": "function",
    "function": "shipping.calculate",
    "config": {
      "carrier": "ups",
      "origin": "US"
    }
  }
}

Tool Configuration

Adding Tools to an Agent

  1. Go to your agent's settings
  2. Click the Tools tab
  3. Click Add Tool
  4. Select or create a tool
  5. Configure permissions
  6. Save and test

Tool Permissions

Control what tools can do:

PermissionDescription
Read OnlyCan fetch data, cannot modify
WriteCan create and update data
DeleteCan remove data
AdminFull access

Rate Limiting

Prevent abuse:

json
{
  "rate_limits": {
    "calls_per_minute": 10,
    "calls_per_hour": 100,
    "calls_per_day": 1000
  }
}

Tool Response Handling

Success Response

json
{
  "success": true,
  "data": {
    "order_id": "12345",
    "status": "shipped",
    "tracking_number": "1Z999AA10123456784",
    "estimated_delivery": "2025-01-20"
  }
}

Error Response

json
{
  "success": false,
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "No order found with ID 12345"
  }
}

Response Transformation

Transform responses before the agent uses them:

json
{
  "response_transform": {
    "template": "Order {{data.order_id}} is {{data.status}}. {{#if data.tracking_number}}Tracking: {{data.tracking_number}}{{/if}}"
  }
}

Best Practices

Tool Naming

Use clear, descriptive names:

GoodBad
get_order_statusgetStatus
send_password_resetemail
calculate_shipping_costcalc

Parameter Descriptions

Help the agent understand parameters:

json
{
  "parameters": {
    "type": "object",
    "properties": {
      "customer_email": {
        "type": "string",
        "description": "Customer's email address used to look up their account. Must be a valid email format.",
        "format": "email"
      }
    }
  }
}

Error Handling

Define clear error messages:

json
{
  "error_messages": {
    "ORDER_NOT_FOUND": "I couldn't find that order. Please check the order number and try again.",
    "UNAUTHORIZED": "I don't have permission to access that information. Let me connect you with a team member.",
    "TIMEOUT": "The system is taking longer than expected. Please try again in a moment."
  }
}

Security

  1. Validate inputs - Check parameters before execution
  2. Use credentials vault - Never hardcode secrets
  3. Limit scope - Grant minimum necessary permissions
  4. Log usage - Track tool calls for auditing

Testing Tools

In the Agent Test Interface

  1. Open agent test chat
  2. Ask questions that trigger tools
  3. View tool calls in debug panel
  4. Verify correct parameters and responses

Example Test Scenarios

Test: Order Status Tool
Input: "What's the status of order ABC123?"
Expected: Tool called with order_id="ABC123"
Expected: Response includes order status

Test: Error Handling
Input: "Check order INVALID"
Expected: Graceful error message to user

Next Steps