Setting up agent tools
How to add tools (APIs the AI calls during a call, on your side or a third party's) to an agent in the dashboard and try them before saving, plus viewing and rotating the signing secret.
A tool is an API the AI calls during a call, for example to check open slots or look up a customer. Set tools up under Tools on the agent's page, with the developer role or above. For how tools work and how to build your API, see Tools.
Add a tool#
- Under Tools on the agent's page, press + Add tool (up to 10).
- Fill in the settings below.
- Press Save as v… at the bottom of the page.
| Setting | What |
|---|---|
| Tool name | Up to 40 lowercase letters, digits and _, starting with a letter |
| Description | What the tool does and when to use it. The AI uses this to decide whether to call it (up to 500 characters) |
| URL | A URL starting with https |
| Method | GET or POST |
| Sign requests | Adds the voicast signature (Standard Webhooks) and POSTs the tool name, arguments and call details as JSON. Use for your own API |
| Authentication | None or an API key. The API key goes in Authorization (Bearer) or another header |
| Arguments | Values the AI takes from the conversation: name, description, required (up to 20) |
| Confirm before use | Reads out what will happen and gets the caller's consent first. Use for tools that change data, such as booking or canceling |
| Confirmation and completion messages | What is read out when confirming (up to 200 characters). Insert values with {argument name} |
| No lead-in | Only the say text from the tool's response is spoken |
| Include the caller's words | Adds what the caller just said (up to 5 utterances) as heard in the request body (signed requests only) |
API keys are stored encrypted and not shown after saving. They are not kept in agent versions. Enter one only when changing it.
Try a tool#
You can call a tool once with the form's current content, even before saving.
- Press Try on the tool.
- Enter argument values and press Try.
- Check the result (success or failure, status code, elapsed time, body).
Trying a tool isn't charged and isn't kept in the call history. Tools that change data really change it. If the API doesn't respond within 8 seconds, the call times out.
View the signing secret#
Signed tool requests are signed with a secret per environment. Your server uses it to verify webhook-signature (Tools). Requires the admin role or above.
- Open Environment settings in the left menu.
- Under Tools signing secret, press Show to see the value, or Copy to copy it.
Rotate the signing secret#
Rotate the secret if it may have leaked.
- Press Rotate secret under Tools signing secret.
- Press Rotate secret in the confirmation dialog.
For 24 hours after rotating, requests are also signed with the previous secret. Switch your server to the new secret within that time.
The live and test environments have separate secrets.