vapi4k-core/com.vapi4k.api.tools/ExternalTool

ExternalTool

interface ExternalTool : ToolWithParameters

Properties

abstract var async: Boolean

This determines if the tool is async.
If async, the assistant will move forward without waiting for your server to respond. This is useful if you just want to trigger something on your server.
If sync, the assistant will wait for your server to respond. This is useful if want assistant to respond with the result from your server.
Defaults to synchronous (false).

description

abstract var description: String

This is the description of what the function does, used by the AI to choose when and how to call the function.

name

abstract var name: String

This is the name of the function to be called.
Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

Functions

condition

abstract fun condition(requiredCondition: ToolMessageCondition, vararg additionalConditions: ToolMessageCondition, block: ToolCondition.() -> Unit)

Adds a ToolCondition to the optional array of conditions that the tool call arguments must meet in order for this message to be triggered.

parameters

abstract fun parameters(block: Parameters.() -> Unit)

These are the parameters the functions accepts, described as a JSON Schema object.
See the OpenAI guide for examples, and the JSON Schema reference for documentation about the format.
Omitting parameters defines a function with an empty parameter list.

requestCompleteMessage

abstract fun requestCompleteMessage(block: ToolMessageComplete.() -> Unit): ToolMessageComplete

Adds a ToolMessageComplete to the messages in the tool.
This message is triggered when the tool call is complete.
This message is triggered immediately without waiting for your server to respond for async tool calls.
If this message is not provided, the model will be requested to respond.
If this message is provided, only this message will be spoken and the model will not be requested to come up with a response. It's an exclusive OR.

requestDelayedMessage

abstract fun requestDelayedMessage(block: ToolMessageDelayed.() -> Unit): ToolMessageDelayed

Adds a ToolMessageDelayed to the messages in the tool.
This message is triggered when the tool call is delayed.
There are the two things that can trigger this message:

The user talks with the assistant while your server is processing the request. Default is "Sorry, a few more seconds."
The server doesn't respond within timingMilliseconds.
This message is never triggered for async tool calls.

requestFailedMessage

abstract fun requestFailedMessage(block: ToolMessageFailed.() -> Unit): ToolMessageFailed

Adds a ToolMessageFailed to the messages in the tool.
This message is triggered when the tool call fails.
This message is never triggered for async tool calls.
If this message is not provided, the model will be requested to respond.
If this message is provided, only this message will be spoken and the model will not be requested to come up with a response. It's an exclusive OR.

requestStartMessage

abstract fun requestStartMessage(block: ToolMessageStart.() -> Unit): ToolMessageStart

Adds a ToolMessageStart to the messages in the tool.
This message is triggered when the tool call starts.
This message is never triggered for async tools.
If this message is not provided, one of the default filler messages "Hold on a sec", "One moment", "Just a sec", "Give me a moment" or "This'll just take a sec" will be used.

server

abstract fun server(block: Server.() -> Unit): Server

This is the server that will be hit when this tool is requested by the LLM.
All requests will be sent with the call object among other things. You can find more details in the Server URL documentation.
his overrides the serverUrl set on the org and the phoneNumber. Order of precedence: highest tool.server.url, then assistant.serverUrl, then phoneNumber.serverUrl, then org.serverUrl.