Calling Multiple Tool Endpoints

Overview

When the AI agent calls a tool (function), VoiceElements needs to know where to send the HTTP request. This endpoint is called a toolkit. There are two ways to configure it — a legacy single-endpoint style and a newer multi-toolkit style. Both are supported simultaneously.

Legacy Style

The original configuration uses two top-level fields inside VoiceElements_Instructions:

{
  "VoiceElements_Instructions": {
    "defaultToolsUrlBase": {
      "url": "https://your-api.example.com/api",
      "headers": {
        "Token": "<<vns-api-token:MyApiKey>>"
      }
    },
    "defaultToolsUrlAdapter": "?toolName=<<toolname>>&sessionGuid=<<sessionguid>>"
  }
}

Modern Style: Toolkits Array

The preferred approach is a toolkits array inside VoiceElements_Instructions. Each entry is a named endpoint with its own URL, headers, and adapter.

{
  "VoiceElements_Instructions": {
    "toolkits": [
      {
        "name": "default",
        "url": "https://your-api.example.com/api/tool",
        "headers": {
          "Token": "<<vns-api-token:MyApiKey>>"
        },
        "toolsUrlAdapter": "?toolName=<<toolname>>&sessionGuid=<<sessionguid>>"
      }
    ]
  }
}

Toolkit Entry Fields

The "default" Toolkit

If a toolkit named "default" exists in the array, it is used for all tool calls that do not specify a toolkit name. The named "default" toolkit takes precedence over the legacy defaultToolsUrlBase / defaultToolsUrlAdapter fields. This is the recommended migration path.

Resolution order for unqualified tool calls

Calling an Alternate Toolkit

To route a specific tool call to a different endpoint, prefix the tool name with the toolkit name and -- (two hyphens):

toolkitname--tool_function_name

For example, to route a transfer_request tool call to a sandbox endpoint instead of the default, define both toolkits and name the tool sandbox--transfer_request in your OpenAI tool definitions:

"toolkits": [
  {
    "name": "default",
    "url": "https://your-api.example.com/api/tool",
    "headers": { "Token": "<<vns-api-token:MainApiKey>>" },
    "toolsUrlAdapter": "?toolName=<<toolname>>&sessionGuid=<<sessionguid>>"
  },
  {
    "name": "sandbox",
    "url": "https://your-api.example.com/api/sandbox",
    "headers": { "Authorization": "Bearer <<vns-api-token:SandboxToken>>" },
    "toolsUrlAdapter": "?toolName=<<toolname>>&sessionGuid=<<sessionguid>>"
  }
]

When the AI calls sandbox--transfer_request, VoiceElements:

1. Splits on -- to extract toolkit name "sandbox" and tool name "transfer_request"
2. Looks up the "sandbox" toolkit
3. Sends the HTTP request to that toolkit's URL with its headers
4. If the toolkit name is not found, falls back to the default

Adapter Syntax

The toolsUrlAdapter (or legacy defaultToolsUrlAdapter) controls how the tool name and session GUID are passed to your endpoint. Two tokens are available:

Query string style (most common)

"toolsUrlAdapter": "?toolName=<<toolname>>&sessionGuid=<<sessionguid>>"

// Results in:
// https://your-api.example.com/api/tool?toolName=transfer_request&sessionGuid=abc123

Path style

"toolsUrlAdapter": "/<<toolname>>/<<sessionguid>>"

// Results in:
// https://your-api.example.com/api/tool/transfer_request/abc123

No adapter

If toolsUrlAdapter is null or omitted, the tool name and session GUID are sent in the POST body as a JSON object instead of the URL.