Tools

During a voice session the agent can decide to call one of its tools, for example to look up an order or book an appointment. The voice provider sends your client a function call with a tool name and arguments. Your client passes that call to this endpoint, and VoisX runs the tool with the credentials and settings you saved in the console. Then your client sends the result back to the provider.

Tools come from the integrations, custom tools and knowledge base you attach to the agent in the console. See Integrations.

Run a tool

POST/widget/v1/tools/execute

Runs one tool for an agent and returns the tool's result.

Requires the widget:tools permission. Only keys created from a website channel or the widget settings page have it. See Permissions.

Headers

X-API-Keystringrequired

Your project API key.

Body

agent_idintegerrequired

The agent the session is with.

tool_namestringrequired

The tool name, exactly as the voice provider sent it. For the agent's knowledge base the name is search_knowledge_base.

argumentsobjectoptional

The tool arguments, exactly as the voice provider sent them. Defaults to an empty object.

session_idstringrequired

The session_id from Start a session.

Response

The response is the tool's own result, as JSON. Its shape depends on the tool. Pass it back to the voice provider as the function call output.

A knowledge base search returns the matching passages in result:

resultstringoptional

The matching passages with their source, or a message saying nothing relevant was found.

Responses

200

The tool ran. The body is the tool's result.

400

The agent has no tool with this name, or the tool failed. detail says why.

401

The key is invalid, revoked, lacks widget:tools, or is not allowed from this domain.

403

The key cannot use this agent, or the agent is in another project.

404

The agent was not found.

422

A required field is missing.

429

The key's rate limit was reached.

500

The tool could not be run.

cURL

curl -X POST https://in.api.voisx.ai/widget/v1/tools/execute \
  -H "X-API-Key: $VOISX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 2210,
    "session_id": "6f1c2a9e-3b7d-4e2a-9c51-0d8e4f7a1b23",
    "tool_name": "search_knowledge_base",
    "arguments": { "query": "opening hours" }
  }'

Node.js

const res = await fetch("https://in.api.voisx.ai/widget/v1/tools/execute", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.VOISX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: 2210,
    session_id: session.session_id,
    tool_name: call.name,
    arguments: JSON.parse(call.arguments),
  }),
});
const output = await res.json();

Python

import os
import requests

res = requests.post(
    "https://in.api.voisx.ai/widget/v1/tools/execute",
    headers={"X-API-Key": os.environ["VOISX_API_KEY"]},
    json={
        "agent_id": 2210,
        "session_id": session_id,
        "tool_name": "search_knowledge_base",
        "arguments": {"query": "opening hours"},
    },
)
output = res.json()

200 OK

{
  "result": "[1] (source: opening-hours.pdf, relevance: 0.82)\nWe are open 9am to 6pm, Sunday to Thursday."
}

400 Bad Request

{
  "detail": "Tool 'lookup_order' not found for agent 2210."
}

note

Tool calls count against your key's rate limit. Each call also shows in the session's analytics in the console.