adk-connector 0.2.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.
• 🔄 Cross-Device Session Sync: Sync conversations seamlessly. Chat on Telegram, 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, and future modules for WhatsApp, Discord, and Slack).

---

📦 Installation

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

🐍 Python (adk-connector)

pip install adk-connector

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

# Required ONLY for Advanced Python Setup (to map your Telegram ID to the local Web UI user)
TELEGRAM_USER_ID=your_telegram_user_id_here

---

⚡ Quick Start: Python vs JS/TS

🐍 Python Quick Start

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

🟨 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

---

🔄 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, 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 Telegram user ID to dev_user_id. This automatically maps your chats to the "user" namespace in adk web:

connector = TelegramConnector(
    token=token,
    agent=assistant,
    session_management_across_device=True,  # Spin up DB & mapping persistence
    dev_user_id=os.getenv("TELEGRAM_USER_ID") # Syncs this ID to the "user" Web UI namespace
)

2. Run the Bot & Web Server

You can run this using the pre-configured my_agent workspace in the repository:

1. Launch the Telegram Bot: Run the agent code which has session_management_across_device=True:

   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 Telegram conversation history and tool executions will appear in the sidebar session list. You can seamlessly chat from either Telegram 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 (Planned)
• Slack Connector (Planned)

---

📄 License

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