Groq

GroqTools allows an Agent to interact with the Groq API for performing fast audio transcription, translation, and text-to-speech (TTS).

Agno's defaults still name playai-tts and Chip-PlayAI, which Groq retired on December 31, 2025. The examples below select the supported Orpheus model and voice explicitly.

Prerequisites

Before using GroqTools, ensure you have the groq and openai libraries installed and your Groq API key configured.

Install dependencies:
```
uv pip install agno -U groq openai
```
Set your API key: Obtain your API key from the Groq Console and set it as an environment variable.
export GROQ_API_KEY="your-groq-api-key"

The Agent model uses an OpenAI key, separately from any toolkit provider credentials.

Set OpenAI Key

Set your OPENAI_API_KEY as an environment variable. You can get one from OpenAI.

export OPENAI_API_KEY=sk-***

Initialization

Import GroqTools and add it to your Agent's tool list.

from agno.agent import Agent
from agno.tools.models.groq import GroqTools

agent = Agent(
    instructions=[
        "You are a helpful assistant that can transcribe audio, translate text and generate speech."
    ],
    tools=[GroqTools(tts_model="canopylabs/orpheus-v1-english", tts_voice="troy")],
    )

Usage Examples

1. Transcribing Audio

Transcribe an audio file hosted at a URL:

transcription_agent.py

import os
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.models.groq import GroqTools

audio_url = "https://agno-public.s3.amazonaws.com/demo_data/sample_conversation.wav"

agent = Agent(
    name="Groq Transcription Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[GroqTools(tts_model="canopylabs/orpheus-v1-english", tts_voice="troy")],
    )

agent.print_response(f"Please transcribe the audio file located at '{audio_url}'")

2. Translating Audio and Generating Speech

Translate an audio file (e.g., French) to English, then generate a new audio file from the translated text.

Place an existing non-English audio file at tmp/sample-fr.mp3, or replace local_audio_path below with its actual path.

translation_agent.py

import base64
from pathlib import Path
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.models.groq import GroqTools
from agno.utils.media import save_base64_data

local_audio_path = "tmp/sample-fr.mp3"
output_path = Path("tmp/sample-en.wav")
output_path.parent.mkdir(parents=True, exist_ok=True)

agent = Agent(
    name="Groq Translation Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[GroqTools(tts_model="canopylabs/orpheus-v1-english", tts_voice="troy")],
)

instruction = (
    f"Translate the audio file at '{local_audio_path}' to English. "
    f"Then, generate a new audio file using the translated English text."
)
response = agent.run(instruction)
if response and response.audio:
    base64_audio = base64.b64encode(response.audio[0].content).decode("utf-8")
    save_base64_data(base64_audio, str(output_path))

You can customize the underlying Groq models used for transcription, translation, and TTS during initialization:

groq_tools = GroqTools(
    transcription_model="whisper-large-v3",
    translation_model="whisper-large-v3",
    tts_model="canopylabs/orpheus-v1-english",
    tts_voice="troy"
)

Toolkit Params

Parameter	Type	Default	Description
`api_key`	`Optional[str]`	`None`	Groq API key for authentication. If not provided, uses GROQ_API_KEY environment variable.
`transcription_model`	`str`	`"whisper-large-v3"`	Model to use for audio transcription.
`translation_model`	`str`	`"whisper-large-v3"`	Model to use for audio translation to English.
`tts_model`	`str`	`"playai-tts"`	Upstream default is retired; override with an active TTS model.
`tts_voice`	`str`	`"Chip-PlayAI"`	Upstream default is retired; select a voice for the chosen model.
`enable_transcribe_audio`	`bool`	`True`	Enable the audio transcription function.
`enable_translate_audio`	`bool`	`True`	Enable the audio translation function.
`enable_generate_speech`	`bool`	`True`	Enable the text-to-speech generation function.
`all`	`bool`	`False`	Enable all available functions. When True, all enable flags are ignored.

Toolkit Functions

The GroqTools toolkit provides the following functions:

Function	Description
`transcribe_audio`	Transcribes audio from a local file path or a public URL using Groq Whisper.
`translate_audio`	Translates audio from a local file path or public URL to English using Groq.
`generate_speech`	Generates speech from text using Groq TTS.