CartesiaTools enable an Agent to perform text-to-speech, list available voices, and localize voices using Cartesia.

Prerequisites

The following example requires the cartesia library and an API key.

pip install cartesia
export CARTESIA_API_KEY="your_api_key_here"

Example

from agno.agent import Agent
from agno.tools.cartesia import CartesiaTools
from agno.utils.media import save_audio

agent = Agent(
    name="Cartesia TTS Agent",
    description="An agent that uses Cartesia for text-to-speech",
    tools=[CartesiaTools()],
    show_tool_calls=True,
)

response = agent.run(
    "Generate a simple greeting using Text-to-Speech: Say \"Welcome to Cartesia, the advanced speech synthesis platform. This speech is generated by an agent.\""
)
if response.audio:
    save_audio(
        base64_data=response.audio[0].base64_audio,
        output_path="tmp/greeting.mp3",
    )

Advanced Example: Translation and Voice Localization

This example demonstrates how to translate text, analyze emotion, localize a new voice, and generate a voice note using CartesiaTools.

from textwrap import dedent
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.cartesia import CartesiaTools
from agno.utils.media import save_audio

agent_instructions = dedent(
    """Follow these steps SEQUENTIALLY to translate text and generate a localized voice note:
    1. Identify the text to translate and the target language from the user request.
    2. Translate the text accurately to the target language.
    3. Analyze the emotion conveyed by the translated text.
    4. Call `list_voices` to retrieve available voices.
    5. Select a base voice matching the language and emotion.
    6. Call `localize_voice` to create a new localized voice.
    7. Call `text_to_speech` to generate the final audio.
    """
)

agent = Agent(
    name="Emotion-Aware Translator Agent",
    description="Translates text, analyzes emotion, selects a suitable voice, creates a localized voice, and generates a voice note (audio file) using Cartesia TTS tools.",
    instructions=agent_instructions,
    model=OpenAIChat(id="gpt-4o"),
    tools=[CartesiaTools(voice_localize_enabled=True)],
    show_tool_calls=True,
)

agent.print_response(
    "Translate 'Hello! How are you? Tell me more about the weather in Paris?' to French and create a voice note."
)
response = agent.run_response

if response.audio:
    save_audio(
        base64_data=response.audio[0].base64_audio,
        output_path="tmp/french_weather.mp3",
    )

Toolkit Params

ParameterTypeDefaultDescription
api_keystrNoneThe Cartesia API key for authentication. If not provided, uses the CARTESIA_API_KEY env variable.
model_idstrsonic-2The model ID to use for text-to-speech.
default_voice_idstr78ab82d5-25be-4f7d-82b3-7ad64e5b85b2The default voice ID to use for text-to-speech and localization.
text_to_speech_enabledboolTrueEnable text-to-speech functionality.
list_voices_enabledboolTrueEnable listing available voices functionality.
voice_localize_enabledboolFalseEnable voice localization functionality.

Toolkit Functions

FunctionDescription
list_voicesList available voices from Cartesia.
text_to_speechConverts text to speech.
localize_voiceCreate a new localized voice.

Developer Resources