# Cartesia (/examples/tools/cartesia-tools)



Use Cartesia with Agno Agents for generating text-to-speech and audio.

## Prerequisites [#prerequisites]

* Get an API key from [https://play.cartesia.ai/keys](https://play.cartesia.ai/keys) and export it: `export CARTESIA_API_KEY=your_api_key`.
* Run `uv pip install agno cartesia openai` to install the dependencies.
* Export your OpenAI API key: `export OPENAI_API_KEY=your_openai_api_key_here`.

```python

from agno.agent import Agent
from agno.tools.cartesia import CartesiaTools
from agno.utils.audio import write_audio_to_file

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------


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

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    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:
        write_audio_to_file(
            audio=response.audio[0].content, filename="tmp/greeting.mp3"
        )
```

## Save the returned audio bytes [#save-the-returned-audio-bytes]

`response.audio[0].content` contains raw MP3 bytes. The imported `write_audio_to_file` helper expects base64, so replace the saving block with:

```python
from pathlib import Path

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)
```

For this fixed-voice example, use `CartesiaTools(enable_list_voices=False)`. The current voice-listing wrapper expects `items`, whereas the current SDK page exposes `data`; disabling that tool keeps the agent on text-to-speech with the configured voice.

## Run the Example [#run-the-example]

```bash
# Clone and setup repo
git clone https://github.com/agno-agi/agno.git
cd agno
git checkout d703c34f3abf3c41275d3fb2da6e0518a8881f24

# Create and activate virtual environment
./scripts/demo_setup.sh
source .venvs/demo/bin/activate

uv pip install -U cartesia

python cookbook/91_tools/cartesia_tools.py
```

For details, see [Cartesia cookbook](https://github.com/agno-agi/agno/blob/main/cookbook/91_tools/cartesia_tools.py).