Configuring Groq API Key for Xiaoyuzhou Podcast Transcription in Agent Reach

To enable Xiaoyuzhou podcast transcription in Agent Reach, provide your Groq API key by setting the GROQ_API_KEY environment variable or executing agent-reach configure groq-key gsk_xxxxx to store it permanently in ~/.agent-reach/config.yaml.

Agent Reach integrates with Groq's Whisper API to transcribe audio from Xiaoyuzhou (小宇宙) podcast episodes. The system requires a valid Groq API key to process downloads, which it discovers through environment variables or a local configuration file. This guide explains the exact lookup mechanism implemented in the Panniantong/Agent-Reach repository and provides step-by-step configuration instructions.

How Agent Reach Discovers the Groq API Key

According to the source code in agent_reach/channels/xiaoyuzhou.py, the XiaoyuzhouChannel.check() method validates transcription readiness by checking for the Groq key in two locations:

1. Environment variable GROQ_API_KEY (checked first)
2. Configuration file at ~/.agent-reach/config.yaml under the key groq_api_key (checked second)

If neither location contains a key, the channel returns a warning with registration instructions. The relevant logic appears in lines 39-52 of the Xiaoyuzhou channel implementation:

# agent_reach/channels/xiaoyuzhou.py

# Lines 39-52

has_key = bool(os.environ.get("GROQ_API_KEY"))
if not has_key:
    cfg = config if config is not None else Config()
    has_key = bool(cfg.get("groq_api_key"))
if not has_key:
    return "warn", (
        "需要配置 Groq API Key（免费）。步骤：\n"
        "  1. 注册 https://console.groq.com\n"
        "  2. 运行: agent-reach configure groq-key gsk_xxxxx"
    )

Setting the Groq API Key

You can configure the key using either temporary environment variables or the persistent configuration command.

Method 1: Environment Variable (Session-Only)

Set the GROQ_API_KEY variable in your shell to make the credential available to the current session:

export GROQ_API_KEY=gsk_XXXXXXXXXXXXXXXX

This approach does not persist across terminal sessions but takes precedence over the configuration file when present.

Method 2: Persistent Configuration (Recommended)

Use the built-in CLI command to write the key to ~/.agent-reach/config.yaml. This method stores the credential under the groq_api_key field as defined in agent_reach/config.py:

agent-reach configure groq-key gsk_XXXXXXXXXXXXXXXX

The configuration manager in agent_reach/config.py (specifically within Config.FEATURE_REQUIREMENTS at lines 21-27) handles the persistence and retrieval of this value.

Verification and Installation Checks

During the installation routine (agent-reach install --env=auto), the CLI performs the same key validation found in agent_reach/cli.py lines 45-51:

# agent_reach/cli.py

# Lines 45-51

has_key = bool(os.environ.get("GROQ_API_KEY")) or bool(config.get("groq_api_key"))
if has_key:
    print("  ✅ Groq API key configured")
else:
    print("  -- Groq API key not set. Get free key at https://console.groq.com")
    print("     Then run: agent-reach configure groq-key gsk_xxxxx")

To verify your configuration manually, run the diagnostic command:

python -m agent_reach.cli doctor

Look for the line indicating "✅ Groq API key configured" in the output.

Running Xiaoyuzhou Transcription

Once configured, the Xiaoyuzhou channel automatically invokes the Groq Whisper service via the transcribe.sh script located at ~/.agent-reach/tools/xiaoyuzhou/. Pass a podcast URL to the read command:

agent-reach read https://www.xiaoyuzhoufm.com/episode/12345

Complete workflow example:

# Obtain key from https://console.groq.com

agent-reach configure groq-key gsk_XXXXXXXXXXXXXXXX

# Verify configuration

python -m agent_reach.cli doctor | grep "Groq API key"

# Transcribe episode

agent-reach read https://www.xiaoyuzhoufm.com/episode/12345

Summary

• Agent Reach requires a Groq API key to transcribe Xiaoyuzhou podcasts using Groq's Whisper API.
• The system checks the GROQ_API_KEY environment variable first, then falls back to ~/.agent-reach/config.yaml.
• Use agent-reach configure groq-key <key> for persistent storage managed by agent_reach/config.py.
• Validation occurs in XiaoyuzhouChannel.check() and during CLI installation routines.
• Verify your setup with python -m agent_reach.cli doctor before attempting transcription.

Frequently Asked Questions

Where does Agent Reach store the Groq API key when using the configure command?

The command writes to ~/.agent-reach/config.yaml under the field name groq_api_key. This file is managed by the Config class in agent_reach/config.py, which defines the feature requirements and handles all configuration persistence.

Why does my transcription fail even after setting the environment variable?

Ensure the variable is exported in the same shell session running Agent Reach. The code in agent_reach/channels/xiaoyuzhou.py uses os.environ.get("GROQ_API_KEY"), which requires the variable to be present in the process environment. Simply defining it in .bashrc or .zshrc without exporting it to the current session will cause the check to fail.

Can I use both the environment variable and config file simultaneously?

Yes. The implementation checks the environment variable first (lines 39-42 in xiaoyuzhou.py), so if GROQ_API_KEY is set, it takes precedence regardless of config file contents. The configuration file only serves as a fallback when the environment variable is absent.

Is the Groq API key required for all Agent Reach channels or only Xiaoyuzhou?

The Groq key specifically enables the Xiaoyuzhou channel's transcription capability, as implemented in XiaoyuzhouChannel.check() at lines 39-52. Other channels may have different API requirements defined in their respective validation logic within the agent_reach/channels/ directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}