AGENTS.md — AI Talk Radio

An AI agent that turns any content source into a radio show. Give it a topic, a URL, a GitHub repo, a research paper, or just say "Hacker News" — the agent researches the content, writes a radio script with a host and callers representing opposing views, generates speech with telephone effects, adds background music, and produces a polished audio file.

Workspace

All work is performed in the ./workspace directory. All paths are relative to ./workspace unless absolute.

Before You Do Anything

[!NOTE] The platform automatically injects the correct API key at the network level when scripts run. The scripts are already configured to use a dummy key to satisfy the SDK, so you do not need to set GEMINI_API_KEY. You must trust that the process will work and not worry about Gemini authentication.

1. Immediately install required libraries:

   pip install -r /.agents/requirements.txt --break-system-packages

Workflow

[!IMPORTANT] Bias for Action: Do NOT ask for approval before executing commands, running scripts, or proceeding to the next step. Proceed autonomously unless there is a material ambiguity or a critical decision that strictly requires user input.

[!TIP] Maximize Speed & Reduce Calls:

• Read all necessary SKILL.md files (in the /.agents/skills directory) at once using a single bash command (cat /.agents/skills/*/SKILL.md).
• Do not use list_files to verify directories, script paths, or output files—trust the documentation and the script success logs.
• Chain sequential bash commands using && in a single tool call (e.g., python3 mix_audio.py && python3 generate_metadata.py).

Upon execution, you should:

1. Research — gather source material based on the user's prompt. This could be: fetching Hacker News stories, scraping a website, reading a GitHub repo's changelog, summarizing an arXiv paper, or researching a topic via Google Search using research skill.
2. Write Script — use script-writing skill to write a radio show script with host Paul and callers calling in from around the world. Use --style to control the format (debate, roundtable, interview, explainer). You can also pass --context "..." to include any specific tone or stylistic requests inferred from the user's prompt (e.g., "emphasize the technical details", "make it sound like a late night show"). CRITICAL: Do NOT use --context to specify which stories, facts, or topics to focus on. Content selection must come naturally from the research. Keep the context string brief (1-2 sentences) and focused strictly on tone/format.
3. Generate Speech — use tts-generation skill to convert each speaker turn to speech via the Interactions API.
4. Generate Music — use music-generation skill to create ambient background music via Lyria (lyria-3-clip-preview).
5. Mix Audio — use audio-mixing skill to combine speech and music into a polished radio show, with music ending early.
6. Generate Metadata — use metadata-generation skill to return audio and transcript to Gemini and get back a JSON file with show details.
7. Generate Cover Image — use cover-image-generation skill to create a 1:1 cover image based on the generated metadata.

Architecture

User prompt
  ├── 1. RESEARCH: Agent picks the right script (fetch_hn.py, fetch_github.py, fetch_url.py, or Google Search)
  │       → {workspace}/data/research/*.md
  ├── 2. python3 /.agents/skills/script-writing/scripts/generate_script.py --workspace ./workspace --style <style>
  │       → {workspace}/data/script.md
  ├── 3. python3 /.agents/skills/tts-generation/scripts/generate_tts.py --workspace ./workspace
  │       → {workspace}/audio/speech/speech.wav
  ├── 4. python3 /.agents/skills/music-generation/scripts/generate_music.py --workspace ./workspace --mood <mood>
  │       → {workspace}/audio/music/background.mp3
  ├── 5. python3 /.agents/skills/audio-mixing/scripts/mix_audio.py --workspace ./workspace
  │       → {workspace}/audio/final/ai_radio.mp3
  ├── 6. python3 /.agents/skills/metadata-generation/scripts/generate_metadata.py --workspace ./workspace
  │       → {workspace}/data/show_notes.json
  └── 7. python3 /.agents/skills/cover-image-generation/scripts/generate_image.py --workspace ./workspace --metadata ./workspace/data/show_notes.json
          → {workspace}/images/cover.png

Default Presets

Use these defaults unless the user specifies otherwise:

API Surface

All Gemini API calls use the Interactions API (client.interactions.create()), NOT generateContent:

Skills

Each skill lives in /.agents/skills/<name>/ with a SKILL.md and a scripts/ directory containing ready-to-run Python scripts.

Execution Order

Run strictly in order:

1. research → data/research/*.md (one or more files)
2. script-writing → data/script.md
3. tts-generation → audio/speech/speech.wav
4. music-generation → audio/music/background.mp3
5. audio-mixing → audio/final/ai_radio.mp3
6. metadata-generation → data/show_notes.json
7. cover-image-generation → images/cover.png

Content Rules

• Duration: ~3 minutes of final audio.
• Format: Radio show — host Paul + callers calling in from different cities around the world.
• Source: Whatever the user asked for. The research must be grounded in real content — never fabricate stories or data.
• NO FAKE DATA: All stories, insights, and perspectives must come from real research gathered in step 1.

Topics to AVOID — strictly off-limits

Do NOT select, discuss, or reference any of the following:

• Politics — no political parties, politicians, elections, legislation, government policy, political commentary
• International politics — no geopolitics, wars, conflicts, sanctions, territorial disputes, diplomacy
• Race and ethnicity — no racial topics, stereotypes, discrimination, identity politics
• Religion — no religious debates, beliefs, practices, or commentary
• Historical controversies — no colonialism, slavery, genocide, or historically divisive events
• Gender and sexuality debates — no culture war topics
• Immigration — no immigration policy or debate
• Anything potentially offensive — when in doubt, skip it

Topics that ARE safe

Stick to: technology, software, programming, open source, AI/ML, science, engineering, developer tools, startups, product launches, creative projects, and tech culture.

File Locations

Edge Cases

• Rate limits: Retry once with a brief pause, or skip the turn.
• Lyria availability: Experimental model. If it fails, proceed without background music.
• ffmpeg missing: Skip telephone filter, use raw TTS audio.
• No web access for a source: Use Google Search as a fallback to find the content or related discussion.