voice.addTools()

The addTools() method equips a voice provider with tools (functions) that can be called by the model during real-time interactions. This enables voice assistants to perform actions like searching for information, making calculations, or interacting with external systems.

Usage example

import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

// Define tools
const weatherTool = createTool({
  id: 'getWeather',
  description: 'Get the current weather for a location',
  inputSchema: z.object({
    location: z.string().describe('The city and state, e.g. San Francisco, CA'),
  }),
  outputSchema: z.object({
    message: z.string(),
  }),
  execute: async inputData => {
    // Fetch weather data from an API
    const response = await fetch(
      `https://api.weather.com?location=${encodeURIComponent(inputData.location)}`,
    )
    const data = await response.json()
    return {
      message: `The current temperature in ${inputData.location} is ${data.temperature}°F with ${data.conditions}.`,
    }
  },
})

// Initialize a real-time voice provider
const voice = new OpenAIRealtimeVoice({
  realtimeConfig: {
    model: 'gpt-5.1-realtime',
    apiKey: process.env.OPENAI_API_KEY,
  },
})

// Add tools to the voice provider
voice.addTools({
  getWeather: weatherTool,
})

// Connect to the real-time service
await voice.connect()

Parameters

<PropertiesTable content={[ { name: 'tools', type: 'ToolsInput', description: 'Object containing tool definitions that can be called by the voice model', isOptional: false, }, ]} />

Return value

This method doesn't return a value.

Notes

• Tools must follow the Mastra tool format with name, description, input schema, and execute function
• This method is primarily used with real-time voice providers that support function calling
• If called on a voice provider that doesn't support tools, it will log a warning and do nothing
• Tools added with this method are typically combined with any tools provided by an associated Agent
• For best results, add tools before starting a conversation (before calling connect())
• The voice provider will automatically handle the invocation of tool handlers when the model decides to use them
• Multiple calls to addTools() may either replace or merge with existing tools, depending on the provider implementation