adk-connector 0.4.2

Unified cross-platform connectors suite for Google ADK Agents

ADK Connectors

ADK Connectors is a plug-and-play toolkit that wraps any Google Agent Development Kit (ADK) agent and exposes it as a chatbot on Telegram, Discord, WhatsApp, and Slack.

By adding just a few lines of code, you can bridge the gap between local development, testing, and production messaging platforms.

---

🎥 Setup Demo: adk-connector with the blog-writer Agent

Below is a walkthrough showing how to set up the adk-connector Python package in the official blog-writer example project:

https://github.com/Harshk133/adk-connector/raw/main/assets/adk-connector-demo.mov

(If the video does not load or play automatically, you can view the file directly at assets/adk-connector-demo.mov.)

---

✨ Key Features

• 🚀 3-Line Wrapper: Deploy any google-adk agent (Python or JavaScript/TypeScript) to messaging channels with virtually zero code changes.
• ⚡ Auto Tunnel & Webhook Server: Set tunnel=True to automatically spin up a local HTTP server and a Cloudflare Tunnel with zero configuration, an automatic precompiled binary downloader, and port-collision avoidance.
• 🔄 Cross-Device Session Sync: Sync conversations seamlessly. Chat on Telegram or Discord, then inspect and continue the exact same conversation inside the ADK Web UI (adk web).
• 💾 Automatic Database Engine Setup: Transparently spins up an asynchronous SQLite backend to record session states, events, and tool invocations.
• 🔒 Local Persistent Mapping: Uses a secure, local JSON mapping engine so restarting the bot never breaks session IDs or active chats.
• 🧩 Extensible Architecture: Structured to support multiple providers (Telegram, Discord, and future modules for WhatsApp and Slack).

---

📦 Installation

This repository contains connectors for both Python and JavaScript / TypeScript.

🐍 Python (adk-connector)

You can install specific platform connectors or install all of them at once:

# Install individual connectors:
pip install "adk-connector[telegram]"
pip install "adk-connector[discord]"
pip install "adk-connector[whatsapp]"

# Or install all connectors:
pip install "adk-connector[all]"

For database-backed cross-device session synchronization (e.g. adk web UI), install the DB components:

pip install "google-adk[db]"

🟨 JavaScript / TypeScript (adk-connector-js)

npm install adk-connector-js
# or
pnpm install adk-connector-js

---

⚙️ Environment Configuration

Create a .env file in your project root and configure the required environment variables:

# Required for agent reasoning
GEMINI_API_KEY=your_gemini_api_key_here

# Required for Telegram bot
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
TELEGRAM_USER_ID=your_telegram_user_id_here

# Required for Discord bot
DISCORD_BOT_TOKEN=your_discord_bot_token_here
DISCORD_USER_ID=your_discord_user_id_here

---

⚡ Quick Start: Python vs JS/TS

🐍 Python Quick Start (Telegram)

1. Write the code (agent.py)

import os
from dotenv import load_dotenv
from google.adk.agents.llm_agent import Agent
from adk_connectors.telegram import TelegramConnector

# Load environment variables from .env
load_dotenv()

# 1. Define your standard Google ADK Agent
assistant = Agent(
    model='gemini-2.5-flash',
    name='my_assistant',
    instruction='You are a helpful assistant.'
)

if __name__ == "__main__":
    # 2. Retrieve your Telegram Bot Token
    token = os.getenv("TELEGRAM_BOT_TOKEN")
    
    # 3. Bind the connector
    connector = TelegramConnector(
        token=token,
        agent=assistant
    )
    
    # 4. Start polling!
    connector.start()

2. Run the Script

python agent.py

⚡ Local Webhook Tunneling (No setup required!)

By default, the Telegram connector uses long-polling to retrieve messages. For faster response times, lower latency, and production parity, you can switch to webhooks using the Auto-Tunnel feature:

    # Bind the connector with webhook tunneling enabled
    connector = TelegramConnector(
        token=token,
        agent=assistant,
        tunnel=True,  # <-- Spins up HTTP server & Cloudflare tunnel automatically!
        webhook_secret="optional-webhook-secret-token" # Verify Telegram payloads securely
    )

How it works:

1. Auto-Downloader: If the cloudflared executable is not found on your system PATH, the package automatically downloads the official binary for your platform (Windows, macOS, Linux) and caches it globally in your home directory (~/.adk/bin/).
2. Built-in Web Server: Starts a background HTTP web server (built on aiohttp) on your machine.
3. Port Collision Protection: If the default port (8000) is already occupied, the connector automatically finds the next free port to prevent crashes.
4. Cloudflare Tunnel: Spawns a background Cloudflare tunnel (using trycloudflare.com) to expose your local port securely to the internet.
5. Instant Registration: Registers the dynamic HTTPS endpoint with Telegram.
6. Graceful Teardown: Closing the bot automatically deletes the webhook registration and shuts down the background tunnel processes cleanly.

🐍 Python Quick Start (Discord)

1. Write the code (agent.py)

import os
from dotenv import load_dotenv
from google.adk.agents.llm_agent import Agent
from adk_connectors.discord import DiscordConnector

# Load environment variables from .env
load_dotenv()

# 1. Define your standard Google ADK Agent
assistant = Agent(
    model='gemini-2.5-flash',
    name='my_assistant',
    instruction='You are a helpful assistant.'
)

if __name__ == "__main__":
    # 2. Retrieve your Discord Bot Token
    token = os.getenv("DISCORD_BOT_TOKEN")
    
    # 3. Bind the connector
    connector = DiscordConnector(
        token=token,
        agent=assistant
    )
    # 4. Start the bot!
    connector.start()

2. Run the Script

python agent.py

🐍 Python Quick Start (WhatsApp)

The WhatsApp connector leverages a lightweight Node.js child process executing the @whiskeysockets/baileys library under the hood. There are zero binary Python dependencies.

🛠️ Prerequisites

Ensure you have Node.js (>= 18) and npm installed on your system. The connector will automatically set up its internal JS dependencies on first run.

1. Write the code (agent.py)

from google.adk.agents.llm_agent import Agent
from adk_connectors.whatsapp import WhatsAppWebConnector

# 1. Define your standard Google ADK Agent
assistant = Agent(
    model='gemini-2.5-flash',
    name='my_assistant',
    instruction='You are a helpful assistant.'
)

if __name__ == "__main__":
    # 2. Bind the connector
    connector = WhatsAppWebConnector(
        agent=assistant
    )
    
    # 3. Start the bot!
    connector.start()

2. Run the Script

python agent.py

3. Scan the QR Code

On first run, a QR code will be generated and printed directly in your terminal.

1. Open WhatsApp on your phone.
2. Go to Settings > Linked Devices > Link a Device.
3. Point your phone camera to scan the QR code printed in the terminal.
4. Once paired, test the bot by sending a message like "hi" to yourself (Message Yourself chat) or have any contact message your phone.

🟨 JavaScript / TypeScript Quick Start

1. Write the code (agent.ts)

import { LlmAgent } from '@google/adk';
import { TelegramConnector } from 'adk-connector-js';
import dotenv from 'dotenv';

// Load environment variables (.env)
dotenv.config();

// 1. Define your standard Google ADK Agent
export const rootAgent = new LlmAgent({
  name: 'my_assistant',
  model: 'gemini-2.5-flash',
  instruction: 'You are a helpful assistant.'
});

// 2. Launch the Telegram Connector under script entrypoint
if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('agent.ts')) {
  const connector = new TelegramConnector({
    token: process.env.TELEGRAM_BOT_TOKEN!,
    agent: rootAgent
  });

  connector.start();
}

2. Run the Script

npx tsx agent.ts

---

🌐 Unified Multi-Platform Deployment (New in v0.4.1)

If you want to deploy one agent across multiple platforms simultaneously (e.g., Telegram, Discord, and WhatsApp concurrently), you can use the ConnectorManager as a central hub.

Instead of running separate scripts or instances, you initialize the platform connectors without an agent argument, pass them into ConnectorManager, and run them together using start_sync().

🐍 Python Multi-Platform Example

import os
from dotenv import load_dotenv
from google.adk.agents.llm_agent import Agent
from adk_connectors import ConnectorManager
from adk_connectors.telegram import TelegramConnector
from adk_connectors.discord import DiscordConnector
from adk_connectors.whatsapp import WhatsAppConnector

# Load environment variables from .env
load_dotenv()

# 1. Define your standard Google ADK Agent
assistant = Agent(
    model='gemini-2.5-flash',
    name='my_assistant',
    instruction='You are a helpful assistant.'
)

if __name__ == "__main__":
    platforms = []

    # Initialize Telegram if token is set
    telegram_token = os.getenv("TELEGRAM_BOT_TOKEN")
    if telegram_token:
        platforms.append(
            TelegramConnector(token=telegram_token, streaming=True, tunnel=True)
        )

    # Initialize Discord if token is set
    discord_token = os.getenv("DISCORD_BOT_TOKEN")
    if discord_token:
        platforms.append(
            DiscordConnector(token=discord_token, streaming=True)
        )

    # Initialize WhatsApp (uses local Bridge server)
    platforms.append(
        WhatsAppConnector(port=3001)
    )

    # 2. Pass all platforms to the central manager
    manager = ConnectorManager(
        agent=assistant,
        platforms=platforms,
        session_management_across_device=True,
        dev_user_id=os.getenv("TELEGRAM_USER_ID") # Maps to user namespace for sync
    )

    # 3. Start all bots concurrently!
    manager.start_sync()

---

🔄 Python Advanced Setup: Session Synchronization (with adk web)

The advanced setup enables the unified cross-device sync engine so you can chat with your bot on Telegram or Discord, and view, inspect, or continue the exact same conversation inside the local ADK Web UI (adk web).

1. Configure the Connector

Set session_management_across_device=True and pass your personal user ID to dev_user_id. This automatically maps your chats to the "user" namespace in adk web:

# For Telegram Setup:
connector = TelegramConnector(
    token=token,
    agent=assistant,
    session_management_across_device=True,
    dev_user_id=os.getenv("TELEGRAM_USER_ID")
)

# For Discord Setup:
connector = DiscordConnector(
    token=token,
    agent=assistant,
    session_management_across_device=True,
    dev_user_id=os.getenv("DISCORD_USER_ID")
)

# For WhatsApp Setup:
connector = WhatsAppWebConnector(
    agent=assistant,
    session_management_across_device=True,
    dev_user_id=os.getenv("WHATSAPP_USER_ID") # e.g. "919421616978" or your account JID/LID JID
)

2. Run the Bot & Web Server

You can run this using your configured agent workspace:

1. Launch the Bot: Run the agent script:

   python my_agent/agent.py
   

2. Launch the ADK Web Server in a separate terminal:

   adk web my_agent
   

3. Open your browser and navigate to http://127.0.0.1:8000. Your conversation history and tool executions will appear in the sidebar session list. You can seamlessly chat from either your messaging client (Telegram/Discord) or the Web UI!

---

🤖 Multi-Agent & Sub-Agent Support

adk-connector is built out-of-the-box to support complex agents that delegate tasks to sub-agents (e.g. using sub_agents=[...] or tools=[AgentTool(agent=...)]).

1. Zero Extra Launcher Files Required

You can integrate adk-connector directly inside your main agent.py file under if __name__ == "__main__":. There is no need to write a separate script like run_telegram.py.

2. Auto-Resolution of Missing State Variables

In multi-agent setups, sub-agents often expect prompt context variables (e.g., {seminal_paper}) that get populated by parent outputs from previous turns. If a user triggers a tool in a single-turn or text-only scenario, these variables won't exist in the session state yet. adk-connector automatically scans all parent and sub-agent instructions for curly brace placeholders and pre-populates them dynamically with user input or fallback values before executing the runner. This prevents KeyError: 'Context variable not found' crashes.

3. Double-Import Safety

Running multi-agent code directly as a script (python -m package.module) often triggers Python double-import cycles if the package initialization files import the agent submodule. When an ADK agent is instantiated twice in this cycle, Pydantic throws a validation error because sub-agents are assigned a parent twice. adk-connector automatically overrides ADK parent-validation checks to allow safe duplicate parent resolution under import cycles, guaranteeing that your code runs correctly out of the box.

---

🗺️ Roadmap

• Telegram Connector (v0.1.0)
• Discord Connector (v0.2.2)
• WhatsApp Connector (v0.3.0)
• Slack Connector (Planned)

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.