Custom Tools
Tools let an agent do things mid-call instead of only talking — look up an order, check a calendar, book a slot, create a ticket, or take any action your systems expose. During a live conversation the agent decides when a tool is needed, fills in the details from what the caller said, calls it, and speaks the result back.
You configure tools on an agent's Tools tab, entirely from the dashboard at your-infravoice-host — there's nothing to install and no code to write on the InfraVoice side.
How tools work
- You add a tool to an agent: a Function Name, a Description of when to use it, its Parameters, and where it runs — either your own HTTP Endpoint or a connected Integration.
- During a call, the LLM reads the description and calls the tool when the caller's intent matches — e.g. "What's the status of order 1234?" triggers your order-lookup tool.
- InfraVoice runs the tool (calling your API, filling in the values the agent extracted), feeds the result back to the model, and the agent speaks the answer.
The description is for the model, not the developer. Say clearly when to use the tool — that's how the agent decides whether to call it.
Add a tool
Open an agent, go to the Tools tab, and click Add Tool. Fill in the New Tool form:
| Field | What it's for |
|---|---|
| Function Name | A unique identifier in snake_case — e.g. book_appointment. The model calls the tool by this name. |
| Description | Plain-English explanation of what the tool does and when to use it. The agent relies on this to decide when to call it. |
| Execution Backend | Choose HTTP Endpoint (call your own API) or Connector (a service you've already connected). |
| Parameters | The typed inputs the tool needs. The agent fills these from the conversation. |
Click Create to save the tool (or Update when editing an existing one). Tools take effect on your next call — remember to Publish the agent to push changes live.
Option A — HTTP Endpoint (call your own API)
Point the tool at any HTTPS endpoint your backend exposes:
| Field | Notes |
|---|---|
| Endpoint URL | The full URL to call. Must start with http:// or https://, and must resolve to a public address — private, loopback and cloud-metadata addresses are refused, and redirects are not followed. (Self-hosted deployments can allow specific internal hosts via USF_TOOL_ALLOWED_INTERNAL_HOSTS.) |
| Method | GET, POST, PUT, PATCH, or DELETE. |
| Auth Type | None, Bearer Token, API Key, or Basic Auth. When set, a Token / Key field appears for your secret. |
| Timeout | How long (in ms) to wait for your API before giving up. |
| Retry Count | How many times to retry on failure (up to 5). |
| Response Path | Reserved — not currently applied. The full JSON response is always returned to the model. |
Dropping parameters into the URL. Wrap a parameter name in double braces to insert it into the
Endpoint URL — for example https://api.example.com/users/{{user_id}} or
https://api.example.com/weather?city={{city}}. InfraVoice replaces it at call time with the value
the agent extracted. Any parameters you don't place in the URL are sent automatically — as query
params for GET, or as a JSON body for POST / PUT / PATCH. Parameter names come from the
Parameters section of the form.
Your secrets stay yours. The Token / Key you enter for a tool's authentication is encrypted at rest and never exposed to the model.
Option B — Connector (a service you've connected)
If you've connected a third-party service under Build → Integrations, switch Execution Backend to Connector instead of wiring up an endpoint by hand:
- Pick the service under Integration.
- Choose one of its Actions — the agent will use it when appropriate.
No URL, method, or auth to configure — the connection handles it. Don't see your service? Connect one first under Build → Integrations, then it appears here.
Define the parameters
The Parameters section describes the inputs your tool accepts — for example an order_id
(string) or a party_size (number). Give each one a name, type, and a short description so the
model knows what to put there. The agent fills them in from what the caller says, so keep them
small and clearly named.
Test a tool before you go live
Every saved tool can be tried without placing a call. In the Tools list, click a tool to expand it — you'll see three tabs:
- Config — a read-only summary (endpoint or integration, auth, timeout, retries, response path).
- Schema — the exact function definition the model receives, with a Copy button.
- Test — paste a sample Request Body (JSON) and click Execute. InfraVoice calls your endpoint and shows the HTTP status, the response, and how long it took, so you can confirm your API answers correctly before a real caller ever triggers it.
Use Edit to change a tool or Delete to remove it (you'll be asked to confirm by typing the tool's name).
Best practices
- Write the description for the model. Say when to use the tool, not how it's implemented.
- Keep parameters small and typed. The agent fills them from the caller's words — fewer, clearer inputs work best.
- Return concise data. The agent reads results aloud, so avoid dumping large payloads; use Response Path to pull out just the value you need.
- Test before publishing. Use the Test tab to verify your endpoint, then Publish the agent to make the tool live on calls.