Cartesia | Agno

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

Prerequisites

The following example requires the agno, cartesia, and openai libraries plus API keys from Cartesia and OpenAI.

uv pip install agno cartesia openai

export CARTESIA_API_KEY="your_api_key_here"
export OPENAI_API_KEY="your_openai_api_key_here"

Example

from agno.agent import Agent
from agno.tools.cartesia import CartesiaTools
from pathlib import Path

# Initialize Agent with Cartesia tools
agent = Agent(
    name="Cartesia TTS Agent",
    description="An agent that uses Cartesia for text-to-speech.",
    tools=[CartesiaTools(enable_list_voices=False)],
)

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."
    """
)

# Save the generated audio
if response.audio and response.audio[0].content:
    output = Path("tmp/greeting.mp3")
    output.parent.mkdir(parents=True, exist_ok=True)
    output.write_bytes(response.audio[0].content)

Translate and generate speech with an existing voice

Use an existing voice ID from your Cartesia account. This example translates the text and generates speech without creating a new voice:

from os import environ
from pathlib import Path
from agno.agent import Agent
from agno.tools.cartesia import CartesiaTools

agent = Agent(
    tools=[CartesiaTools(
        default_voice_id=environ["CARTESIA_VOICE_ID"],
        enable_list_voices=False,
    )],
    instructions=["Translate the requested text, then call text_to_speech with the translation."],
)
response = agent.run("Translate 'Hello, how are you?' to French and create a voice note.")
if response.audio and response.audio[0].content:
    Path("french_greeting.mp3").write_bytes(response.audio[0].content)

Set CARTESIA_VOICE_ID to the existing voice's ID before running this script.

The current Agno adapter's list_voices reads the older items response field; the current SDK uses data. localize_voice also omits the now-required accent parameter. These two methods need upstream changes to work with the current SDK. Use the Cartesia voice API directly for voice discovery and localization; enabling all=True does not resolve these incompatibilities.

Toolkit Params

Parameter	Type	Default	Description
`api_key`	`Optional[str]`	`None`	The Cartesia API key for authentication. If not provided, uses the `CARTESIA_API_KEY` env variable.
`model_id`	`str`	`sonic-2`	The model ID to use for text-to-speech.
`default_voice_id`	`str`	`78ab82d5-25be-4f7d-82b3-7ad64e5b85b2`	The default voice ID to use for text-to-speech and localization.
`enable_text_to_speech`	`bool`	`True`	Enable text-to-speech functionality.
`enable_list_voices`	`bool`	`True`	Enable listing available voices functionality.
`enable_localize_voice`	`bool`	`False`	Enable voice localization functionality.
`all`	`bool`	`False`	Enable all tools.

Toolkit Functions

Function	Description
`list_voices`	List available voices from Cartesia.
`text_to_speech`	Converts text to speech.
`localize_voice`	Create a new localized voice.

Developer Resources

Tools