# How to Configure the Groq API Key for Podcast Transcription in Agent Reach

> Learn how to manually configure your Groq API key for podcast transcription in Agent Reach. Discover the config file location and fallback options for seamless audio processing.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-01

---

**Agent Reach stores the Groq API key in `~/.agent-reach/config.yaml` under the `groq_api_key` field and automatically falls back to OpenAI's Whisper service only when Groq's `whisper-large-v3` model is unavailable.**

The Panniantong/Agent-Reach repository provides a seamless podcast transcription pipeline that prioritizes Groq's free Whisper API for speed and cost efficiency. To enable this functionality, you must configure the Groq API key for podcast transcription in Agent Reach before processing audio files. This guide covers the exact file locations, validation logic, and command-line methods used by the transcription engine.

## Configuration Storage and Validation

Agent Reach persists sensitive credentials outside the repository using a YAML-based configuration system. The transcription engine validates these credentials before attempting API calls to avoid unnecessary network failures.

### The Configuration File Structure

In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the `Config` class manages the `groq_api_key` value within the user’s home directory at `~/.agent-reach/config.yaml`. When you save a key, the system writes it to this file under the exact field name `groq_api_key`, ensuring consistent retrieval across CLI and programmatic interfaces.

### Environment Variable Fallback

As a secondary source, Agent Reach checks the `GROQ_API_KEY` environment variable. If the YAML configuration lacks the key but the environment variable is present, the transcription pipeline uses the environment value without modifying the config file.

### Validation via `is_configured`

The `Config.is_configured("groq_whisper")` helper (lines 90‑94 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) verifies that a valid Groq API key exists in either the config file or the environment. This check runs before any transcription attempt to ensure the provider order can be established correctly.

## Setting the Groq API Key

You can populate the credential store using the CLI convenience command or direct Python instantiation.

### CLI Configuration Command

The [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) file implements a dedicated configure sub-command that writes the key safely:

```bash
agent-reach configure groq-key gsk_YourGroqKeyHere

```

This command invokes `config.set("groq_api_key", …)` (lines 104‑107), persisting the value to `~/.agent-reach/config.yaml` with proper file permissions.

### Programmatic Configuration

For automated setups or testing environments, instantiate the `Config` class directly:

```python
from agent_reach.config import Config

cfg = Config()
cfg.set("groq_api_key", "gsk_YourGroqKeyHere")

```

This approach writes immediately to the YAML file and makes the key available for subsequent transcription calls within the same process.

## Transcription Pipeline Architecture

Once configured, the transcription engine routes audio through Groq’s infrastructure using a provider-agnostic abstraction layer.

### Provider Mapping in [`transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/transcribe.py)

The [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) file defines a `PROVIDERS` mapping (lines 30‑36) that specifies the Groq endpoint (`https://api.groq.com/openai/v1/audio/transcriptions`), the model name (`whisper-large-v3`), and the config field to read (`groq_api_key`). This mapping decouples the transcription logic from specific vendor implementations.

### Key Extraction and HTTP Requests

The internal `_provider_key()` method (lines 57‑61) extracts the key from the `Config` instance, while `transcribe_chunk()` (lines 63‑71) constructs the multipart HTTP POST request to Groq’s API. The function sends the audio chunk along with the stored API key in the Authorization header.

### Automatic Fallback Logic

The `transcribe()` function (lines 107‑118) builds a provider order list `["groq", "openai"]` when the user specifies `provider="auto"`. It first validates that at least one key is configured (lines 22‑25), then delegates to `_transcribe_with_fallback()` (lines 49‑61), which attempts Groq first and catches errors to retry with OpenAI’s `whisper-1` model if necessary.

## Practical Usage Examples

With the Groq API key configured, you can process podcast URLs immediately.

**Transcribe with automatic provider selection (Groq first):**

```bash
agent-reach transcribe https://example.com/podcast.mp3

```

**Force Groq only (fails fast if the key is missing):**

```bash
agent-reach transcribe https://example.com/podcast.mp3 --provider groq

```

**Use the Python API directly:**

```python
from agent_reach.transcribe import transcribe
from agent_reach.config import Config

cfg = Config()
text = transcribe(
    "https://example.com/podcast.mp3",
    provider="auto",
    config=cfg,
)
print(text)

```

## Troubleshooting and Verification

If transcription fails immediately with a configuration error, verify the setup using the built-in diagnostics.

### Checking Configuration Status

Run a quick Python check to confirm the key is recognized:

```python
from agent_reach.config import Config

cfg = Config()
print(f"Groq configured: {cfg.is_configured('groq_whisper')}")

```

A `True` result indicates that [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) successfully located the `groq_api_key` in `~/.agent-reach/config.yaml` or the `GROQ_API_KEY` environment variable.

### Installation Reminders

The `_install_xiaoyuzhou_deps()` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 71‑78) prints a helpful reminder if the Groq key is missing during channel setup, explicitly suggesting the `agent-reach configure groq-key` command format. This ensures users discover the configuration requirement during initial setup rather than at runtime.

## Summary

- Agent Reach stores the Groq API key in `~/.agent-reach/config.yaml` under the field `groq_api_key`, with fallback support for the `GROQ_API_KEY` environment variable.
- Use `agent-reach configure groq-key <key>` to persist credentials via the CLI, or call `Config().set("groq_api_key", …)` programmatically.
- The transcription pipeline in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) routes audio to `https://api.groq.com/openai/v1/audio/transcriptions` using the `whisper-large-v3` model.
- When `provider="auto"` is selected, the system automatically falls back to OpenAI’s `whisper-1` only if Groq requests fail or the key is absent.
- Validation occurs via `Config.is_configured("groq_whisper")` before any network requests are attempted.

## Frequently Asked Questions

### Where does Agent Reach store the Groq API key?

Agent Reach writes the key to a YAML file located at `~/.agent-reach/config.yaml` under the field name `groq_api_key`. This path is hardcoded in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) to keep credentials outside version-controlled directories.

### Can I use environment variables instead of the config file?

Yes. The `Config` class checks for the `GROQ_API_KEY` environment variable as a fallback when the `groq_api_key` field is missing from the YAML file. You can export this variable in your shell profile to avoid writing the key to disk.

### What happens if my Groq API key is invalid or rate-limited?

The `_transcribe_with_fallback()` function in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) catches errors from Groq and automatically retries the request using OpenAI’s Whisper API, provided you have configured an OpenAI key. If you force Groq with `--provider groq`, the command raises an error immediately instead of falling back.

### How do I force Agent Reach to use OpenAI instead of Groq?

Pass the `--provider openai` flag to the CLI command, or set `provider="openai"` in the Python API. This bypasses the default provider order of `["groq", "openai"]` and skips the Groq validation check entirely.