superbizon007/downloader-agent repository overview

⁠Downloader Agent

A download orchestration agent that downloads files from 80+ platforms via 67 specialized tools.

Exposes Google A2A (JSON-RPC 2.0) and OpenAI-compatible /v1/chat/completions APIs over HTTPS.

Implements an agent using the ReAct (Reasoning + Acting) pattern for intelligent download orchestration.

⁠Supported Platforms

⁠Video (yt-dlp)

YouTube, YouTube Playlist, Instagram, Instagram Stories, TikTok, Twitter/X, Vimeo, Dailymotion, Twitch (clips, VODs, live streams), Reddit, Facebook, Bilibili, Niconico, Weibo, LinkedIn, Crunchyroll, Funimation, ADN

⁠Audio (yt-dlp)

SoundCloud, Bandcamp, Mixcloud

⁠Images (gallery-dl)

Pinterest, Flickr, Tumblr, DeviantArt, ArtStation, Pixiv, Instagram, Twitter/X, Reddit, Weibo, Patreon, Newgrounds

⁠Imageboards (gallery-dl)

Danbooru, Gelbooru, e621, Rule34, Konachan, yande.re, Safebooru, nhentai

⁠Manga & Comics (gallery-dl)

MangaDex, Webtoon

⁠yt-dlp Plugin Platforms

⁠Spotify

download_spotify — tracks, albums, playlists, artists via spotdl + YouTube Music. Supports mp3/flac/ogg/opus/m4a/wav output, LRC lyrics, SponsorBlock.

⁠Telegram

download_telegram — files from channels and chats via tdl. Requires tdl login (run once).

⁠Multi-platform (pybalt / Cobalt API)

download_social — 22 social platforms including YouTube, Instagram, TikTok, Twitter/X, SoundCloud, Twitch, Vimeo, Dailymotion, Bilibili, Rutube, VK, ok.ru, and more.

⁠Protocol / Generic

⁠Discovery

check_platform — given any URL or platform name, returns the recommended tool and its full parameter list. Call this first for any unknown URL.

⁠Backends

⁠yt-dlp Plugins (installed in Docker)

⁠Environment Variables

⁠Shared Workspace (optional)

When running as part of a multi-agent pipeline, the downloader agent can mount a shared S3 workspace (via rclone FUSE) so it can read artifacts from prior steps and write outputs for downstream agents. It also publishes its status to a shared blackboard.

When a workspace is active, downloaded files are placed in {WORKSPACE_MOUNT_PATH}/downloads/ instead of DOWNLOADS_DIR, making them immediately available to other agents in the pipeline.

⁠Run Locally

pip install -e ".[server]"

# CLI backends
pip install yt-dlp gallery-dl you-get spotdl pybalt
brew install aria2 ffmpeg  # macOS; use apt on Linux

# yt-dlp plugins
pip install yt-dlp-rajiko hanime-plugin yt-dlp-coomer ytdlp-plugins
pip install "https://github.com/pratikpatel8982/yt-dlp-hianime/archive/master.zip"
pip install "https://github.com/wmrussell8653/yt-dlp-plugin-yellow/archive/main.zip"
pip install "https://github.com/smvz/yt-dlp-AppleDeveloper/archive/main.zip"
pip install "https://github.com/Earthworm-Banana/yt-dlp-PMVHaven_com-plugin/archive/master.zip"

# tdl (Telegram downloader)
# Download binary from https://github.com/iyear/tdl/releases, place in PATH
tdl login  # one-time interactive login

LLM_API_KEY=sk-... python3 -m app.server

⁠Docker

docker build --build-context a2a_pkg=../../packages/a2a_agent -f Dockerfile.ubuntu -t downloader_agent .

docker run -d \
  -p 443:443 \
  -v /path/to/downloads:/downloads \
  -e LLM_API_KEY=sk-... \
  -e LLM_MODEL=gpt-4o \
  downloader_agent

⁠API Usage

⁠Browser UI

Open https://localhost:443/ in a browser to watch the agent activity log in real-time (xterm.js terminal, read-only).

⁠Health check

curl -k https://localhost:443/health

⁠Agent card

curl -k https://localhost:443/.well-known/agent.json

⁠OpenAI-compatible

curl -k -X POST https://localhost:443/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Download https://www.youtube.com/watch?v=dQw4w9WgXcQ at 1080p"}]}'

curl -k -X POST https://localhost:443/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Download the Daft Punk discography from Spotify as FLAC"}]}'

⁠A2A (Google Agent2Agent)

curl -k -X POST https://localhost:443/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tasks/send","params":{"message":{"role":"user","parts":[{"type":"text","text":"Download https://soundcloud.com/artist/track as FLAC"}]}}}'

# Streaming (SSE)
curl -k -X POST https://localhost:443/ \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tasks/sendSubscribe","params":{"message":{"role":"user","parts":[{"type":"text","text":"Download the top 50 images from danbooru tagged miku solo"}]}}}'

⁠CA Certificate

Install the auto-generated CA cert to trust the HTTPS connection permanently:

curl -k https://localhost:443/ca.crt -o downloader-agent-ca.crt
# macOS:
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain downloader-agent-ca.crt
# Linux:
sudo cp downloader-agent-ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates

⁠MCP tools

The agent image exposes an MCP (Model Context Protocol) server on the same port as A2A at /mcp. Any MCP client — Claude Desktop, Cursor, Windsurf, ChatGPT Connectors, OpenAI Agents SDK — can list and invoke these tools using the pod's API_KEY as Bearer.

In production, Core proxies https://downloader-agent.agents.forfetch.ai/mcp → the worker pod's /mcp.

Input schemas are authored in apps/agents_mcp/app/seed.py. Skills without an explicit schema advertise a single {task: str} freeform parameter.