Tools & MCP

Give an agent capabilities beyond conversation: define function tools it can call, connect MCP servers to expose external tools, and handle DTMF and voicemail on telephony calls.

function_tool

def function_tool(func: 'Optional[Callable]' = None, *, name: 'Optional[str]' = None, filler: 'Optional[str]' = None, filler_grace_period: 'int' = 300)

Decorate a callable to register it as a function tool. Attaches a FunctionToolInfo to the callable, deriving the tool description from its docstring and a JSON parameters schema from its signature and type hints. May be used directly (@function_tool) or with keyword arguments (@function_tool(name=...)).

func

Optional[Callable]

The callable to decorate. When omitted, a decorator is returned so the function can be applied with arguments.

name

Optional[str]

Tool name to expose. Defaults to the callable’s __name__.

filler

Optional[str]

Optional filler text associated with the tool.

filler_grace_period

int

default:"300"

Grace period, in seconds, for the filler.

returns

The decorated callable with a _tool_info attribute when func is provided, otherwise a decorator that applies the same wrapping.

is_function_tool

def is_function_tool(obj: 'Any') -> 'bool'

Check whether an object is a registered function tool.

obj

Any

required

The object to inspect.

returns

bool

True if the object has a _tool_info attribute that is a FunctionToolInfo instance, False otherwise.

get_tool_info

def get_tool_info(tool: 'FunctionTool') -> 'FunctionToolInfo'

Return the tool metadata attached to a function tool.

tool

FunctionTool

required

A function tool created with function_tool.

returns

FunctionToolInfo

The FunctionToolInfo associated with the tool.

FunctionTool

Protocol for callables registered as function tools. A function tool is a callable that carries a _tool_info attribute describing its metadata, allowing it to be exposed to a model for function calling.

Constructor

FunctionTool(*args, **kwargs)

FunctionToolInfo

Metadata describing a function tool.

Fields

name

str

required

The tool’s exposed name.

description

str | None

Human-readable description, typically derived from the callable’s docstring.

parameters_schema

Optional[dict]

JSON schema describing the tool’s parameters.

filler

Optional[str]

Optional filler text associated with the tool.

filler_grace_period

int

default:"300"

Grace period, in seconds, for the filler.

ToolChoice

Strategies controlling whether and how the model calls tools.

class ToolChoice(Enum):
    AUTO = 'auto'
    NONE = 'none'
    REQUIRED = 'required'

build_openai_schema

def build_openai_schema(tool: 'FunctionTool') -> 'dict[str, Any]'

Build an OpenAI-compatible function tool schema.

tool

FunctionTool

required

A function tool created with function_tool.

returns

dict[str, Any]

A dictionary describing the tool in OpenAI’s function-calling format, containing the tool name, description, and parameters schema.

build_gemini_schema

def build_gemini_schema(tool: 'FunctionTool') -> 'dict[str, Any]'

Build a Gemini-compatible function tool schema. The parameters schema is simplified to remove keys that Gemini does not accept, such as additionalProperties, title, and definition blocks.

tool

FunctionTool

required

A function tool created with function_tool.

returns

dict[str, Any]

A dictionary describing the tool with its name, description, and a cleaned parameters schema.

build_nova_sonic_schema

def build_nova_sonic_schema(tool: 'FunctionTool') -> 'dict[str, Any]'

Build a Nova Sonic-compatible function tool schema. Nova Sonic uses the same format as OpenAI, so this delegates to build_openai_schema.

tool

FunctionTool

required

A function tool created with function_tool.

returns

dict[str, Any]

A dictionary describing the tool in OpenAI’s function-calling format.

MCPServerStdio

Configuration for an MCP server launched as a local subprocess. Describes how to start a Model Context Protocol server over standard input/output by running a command with optional arguments and environment variables.

Constructor

MCPServerStdio(command: 'str', args: 'List[str] | None' = None, env: 'Dict[str, str] | None' = None, **kwargs)

command

str

required

Executable used to launch the MCP server process.

args

List[str] | None

Command-line arguments passed to the executable. Defaults to an empty list when not provided.

env

Dict[str, str] | None

Environment variables for the server process. Defaults to an empty mapping when not provided.

MCPServerHTTP

Configuration for an MCP server reachable over HTTP. Describes how to connect to a Model Context Protocol server at a remote URL, optionally sending custom request headers.

Constructor

MCPServerHTTP(url: 'str', headers: 'Dict[str, str] | None' = None, **kwargs)

url

str

required

Endpoint URL of the MCP server.

headers

Dict[str, str] | None

HTTP headers sent with each request, such as authentication credentials. Defaults to an empty mapping when not provided.

DTMFHandler

Registers and dispatches callbacks for received DTMF input. Maintains handlers for individual digits and for digit sequences, invoking the matching callback as DTMF events arrive. A rolling buffer of recent digits is kept to detect registered sequences.

Constructor

DTMFHandler(**kwargs: 'Any') -> 'None'

on_digit

def on_digit(self, digit: 'str', callback: 'Callable') -> 'None'

Register a callback invoked when a specific digit is received. Registering a callback for a digit that already has one replaces the previous callback. Empty digit values are ignored.

digit

str

required

The single digit to listen for.

callback

Callable

required

Callable invoked with the received digit. May be a regular function or a coroutine function.

on_sequence

def on_sequence(self, sequence: 'str', callback: 'Callable') -> 'None'

Register a callback invoked when a digit sequence is received. The callback fires when the rolling buffer of recent digits ends with the given sequence. Registering the same sequence again replaces the previous callback. Empty sequences are ignored.

sequence

str

required

The ordered string of digits to match.

callback

Callable

required

Callable invoked with the matched sequence. May be a regular function or a coroutine function.

VoiceMailDetector

Detects whether an outbound call reached voicemail. Configures voicemail classification for outbound calls and tracks detection state, optionally invoking a callback and triggering hangup when voicemail is detected.

Constructor

VoiceMailDetector(*, llm: 'Any' = None, callback: 'Optional[Callable[[dict], CallbackResult]]' = None, duration: 'float' = 2.0, custom_prompt: 'Optional[str]' = None, auto_hangup: 'bool' = False, detection_threshold: 'float' = 1.0, max_detection_seconds: 'Optional[int]' = None) -> 'None'

llm

Any

Language model used to classify whether voicemail was reached.

callback

Optional[Callable[[dict], CallbackResult]]

Callable invoked with the detection event payload when voicemail is detected. May be a regular function or a coroutine function.

duration

float

default:"2.0"

Detection window in seconds. Defaults to 2.0.

custom_prompt

Optional[str]

Optional prompt overriding the default classifier prompt. Stored as an empty string when not provided.

auto_hangup

bool

default:"False"

Whether to automatically hang up once voicemail is detected. Defaults to False.

detection_threshold

float

default:"1.0"

Confidence threshold for declaring a detection. Defaults to 1.0.

max_detection_seconds

Optional[int]

Optional maximum detection duration in seconds. When provided, it overrides duration.

Python SDK

Core

Speech-to-text

LLM

Text-to-speech

Realtime models

Avatars

Turn detection

Voice activity detection

Noise cancellation

function_tool

is_function_tool

get_tool_info

FunctionTool

Constructor

FunctionToolInfo

Fields

ToolChoice

build_openai_schema

build_gemini_schema

build_nova_sonic_schema

MCPServerStdio

Constructor

MCPServerHTTP

Constructor

DTMFHandler

Constructor

on_digit

on_sequence

VoiceMailDetector

Constructor

​function_tool

​is_function_tool

​get_tool_info

​FunctionTool

​Constructor

​FunctionToolInfo

​Fields

​ToolChoice

​build_openai_schema

​build_gemini_schema

​build_nova_sonic_schema

​MCPServerStdio

​Constructor

​MCPServerHTTP

​Constructor

​DTMFHandler

​Constructor

​on_digit

​on_sequence

​VoiceMailDetector

​Constructor

function_tool

is_function_tool

get_tool_info

FunctionTool

Constructor

FunctionToolInfo

Fields

ToolChoice

build_openai_schema

build_gemini_schema

build_nova_sonic_schema

MCPServerStdio

Constructor

MCPServerHTTP

Constructor

DTMFHandler

Constructor

on_digit

on_sequence

VoiceMailDetector

Constructor