adk-connector 0.2.1

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 three lines of code, you can bridge the gap between local development, testing, and production messaging platforms.

---

✨ Key Features

• 🚀 3-Line Wrapper: Deploy any google-adk agent to messaging channels with virtually zero code changes.
• 🔄 Cross-Device Session Sync: Enable session_management_across_device to 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 (aiosqlite) 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 from day one to support multiple providers (Telegram, and future modules for WhatsApp, Discord, and Slack).

---

📦 Installation

Depending on your use case, install adk-connector using one of the following setups:

1. Standard Setup

For basic bot deployment without database session persistence or web UI synchronization:

pip install adk-connector

2. Advanced Setup (Session Synchronization)

For database-backed cross-device session synchronization (e.g. syncing with the adk web UI), you will also need the Google ADK database components:

pip install adk-connector
pip install "google-adk[db]"

3. Local Developer Setup (From Source)

If you are developing or testing adk-connector locally, clone this repository and install it in editable mode:

git clone https://github.com/Harshk133/adk-connector.git
cd adk-connector

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install package in editable mode with dependencies
pip install -e .

---

⚙️ Environment Configuration

Create a .env file in your project root (or copy .env.example) 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 Setup (to map your Telegram ID to the local Web UI user)
TELEGRAM_USER_ID=your_telegram_user_id_here

---

⚡ Standard Setup: Quick Start

The standard setup launches a standalone chatbot that handles messages but does not sync with the adk web UI.

1. Create your Run Script

Write the following code to agent_standard.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

Execute the script from your terminal:

python agent_standard.py

Alternatively, you can test this mode using the pre-configured basic example in the repository:

python examples/telegram-basic/main.py

---

🔄 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)
• WhatsApp Connector (Planned for v0.2.0)
• Discord Connector (Planned for v0.3.0)
• Slack Connector (Planned for v0.4.0)

---

📄 License

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