adkbot

Multi-Model AI Assistant

🤖 ADKBot is a powerful, multi-model AI assistant framework built on Google's Agent Development Kit (ADK) with LiteLLM for universal model support. ADKBot is an ADK-native project, built from the ground up to leverage ADK's agent architecture while preserving and extending a rich tooling and channel ecosystem.

⚡ Use any LLM provider (NVIDIA NIM, Gemini, Groq, OpenRouter, Anthropic, OpenAI, xAI, Ollama, and 50+ more) through a single unified interface.

🔌 Connect to 12+ chat platforms (Telegram, Discord, WhatsApp, Slack, WeChat, and more).

🛠️ Equipped with 10+ built-in tools (web search, file operations, shell commands, scheduled tasks, MCP support, and sub-agent spawning).

Key Features

🧠 ADK-Powered: Built on Google's Agent Development Kit for robust agent lifecycle management, native callbacks, and session handling.

🌐 Multi-Model: LiteLLM integration means you can use Claude, GPT, Gemini, DeepSeek, Llama, and 50+ other models without changing code.

🔧 Rich Tooling: Web search (5 providers), file operations, shell execution, cron scheduling, MCP protocol support, and sub-agent spawning.

📱 12+ Chat Channels: Telegram, Discord, WhatsApp, WeChat, Feishu, DingTalk, Slack, Matrix, Email, QQ, WeCom, and Mochat.

⏰ Scheduled Tasks: Cron expressions, interval timers, and one-time scheduling with timezone support.

🔒 Security: Workspace sandboxing, command safety guards, SSRF protection, and per-channel access control.

💎 Easy to Use: One command to set up, one command to chat.

Table of Contents

• Key Features
• Install
• Quick Start
• Chat Apps
• Configuration
• Multiple Instances
• CLI Reference
• Python SDK
• OpenAI-Compatible API
• Docker
• Linux Service
• Project Structure
• Contributing

📦 Install

With uv (recommended, fast):

uv tool install adkbot

With pip:

pip install adkbot

# Install with Discord support
pip install "adkbot[discord]"

# Install with multiple channels
pip install "adkbot[discord,slack,feishu]"

# Install everything (all channels + tools)
pip install "adkbot[all]"

git clone https://github.com/nwokike/ADKbot.git
cd ADKbot
uv venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
uv sync --all-extras

# Install proot-distro
pkg update && pkg upgrade
pkg install proot-distro

# Install and log into Ubuntu
proot-distro install ubuntu
proot-distro login ubuntu

# Inside Ubuntu: install uv and configure it for Android's filesystem
apt update && apt upgrade -y
apt install curl -y
curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh
echo 'export UV_LINK_MODE=copy' >> ~/.bashrc
source ~/.bashrc

# Install ADKBot
uv tool install adkbot

Update to latest version

uv:

uv tool upgrade adkbot
adkbot --version

pip:

pip install -U adkbot
adkbot --version

Requirements

• Python >= 3.11
• An API key from any supported LLM provider

🚀 Quick Start

[!TIP] Get API keys:

• NVIDIA NIM (recommended, completely free, massive open-weight model catalog)
• Google Gemini (free tier available, best ADK integration, try gemini/gemma-4-31b-it practically impossible to hit the free limits)
• Groq (fastest inference, free tier)
• OpenRouter (access to many models via one key)
• Anthropic (Claude Opus 4.6)
• OpenAI (GPT 5.4)
• xAI (Grok 4.20)

API keys can be set as environment variables (e.g., NVIDIA_NIM_API_KEY=nvapi-xxx) or entered during the wizard.

For web search setup, see Web Search.

1. Initialize

adkbot onboard

This starts the interactive wizard by default. Use adkbot onboard --skip-wizard to create a basic config without the wizard.

2. Configure (~/.adkbot/config.json)

Configure your model using a LiteLLM model string:

{
  "agents": {
    "defaults": {
      "model": "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
    }
  }
}

LiteLLM model strings work with 100+ providers. Examples:

• "nvidia_nim/nvidia/nemotron-3-super-120b-a12b" - NVIDIA NIM (uses NVIDIA_NIM_API_KEY, free)
• "nvidia_nim/moonshotai/kimi-k2-instruct-0905" - Kimi K2 via NVIDIA NIM (free)
• "gemini/gemma-4-31b-it" - Google Gemma 4 (Uses GEMINI_API_KEY, generous free tier)
• "gemini/gemini-3.1-pro-preview" - Google Gemini (uses GEMINI_API_KEY)
• "groq/llama-3.3-70b-versatile" - Groq (uses GROQ_API_KEY)
• "anthropic/claude-opus-4-6" - Anthropic Claude (uses ANTHROPIC_API_KEY)
• "openai/gpt-5.4" - OpenAI (uses OPENAI_API_KEY)
• "openrouter/anthropic/claude-opus-4-6" - OpenRouter gateway (uses OPENROUTER_API_KEY)
• "xai/grok-4.20-beta-0309-reasoning" - xAI Grok (uses GROK_API_KEY)
• "deepseek/deepseek-chat" - DeepSeek (uses DEEPSEEK_API_KEY)
• "ollama/llama3.2" - Local Ollama (no API key needed)

Set your API key as an environment variable (e.g., NVIDIA_NIM_API_KEY=nvapi-xxx) or enter it during the wizard.

3. Chat

adkbot agent

That's it! You have a working AI assistant in 2 minutes.

💬 Chat Apps

Connect ADKBot to your favorite chat platform. Want to build your own? See the Channel Plugin Guide.

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

adkbot gateway

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"],
      "groupPolicy": "mention"
    }
  }
}

adkbot gateway

adkbot channels login whatsapp
# Scan QR with WhatsApp → Settings → Linked Devices

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890"]
    }
  }
}

adkbot gateway

pip install "adkbot[matrix]"

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "userId": "@adkbot:matrix.org",
      "accessToken": "syt_xxx",
      "deviceId": "ADKBOT01",
      "e2eeEnabled": true,
      "allowFrom": ["@your_user:matrix.org"],
      "groupPolicy": "open"
    }
  }
}

adkbot gateway

Read https://raw.githubusercontent.com/nwokike/MoChat/refs/heads/main/skills/adkbot/skill.md and register on MoChat. My Email account is onyeka@kiri.ng Bind me as your owner and DM me on MoChat.

adkbot gateway

{
  "channels": {
    "mochat": {
      "enabled": true,
      "base_url": "https://mochat.io",
      "socket_url": "https://mochat.io",
      "socket_path": "/socket.io",
      "claw_token": "claw_xxx",
      "agent_user_id": "6982abcdef",
      "sessions": ["*"],
      "panels": ["*"]
    }
  }
}

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "allowFrom": ["ou_YOUR_OPEN_ID"],
      "groupPolicy": "mention",
      "streaming": true
    }
  }
}

adkbot gateway

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "YOUR_APP_KEY",
      "clientSecret": "YOUR_APP_SECRET",
      "allowFrom": ["YOUR_STAFF_ID"]
    }
  }
}

adkbot gateway

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "allowFrom": ["YOUR_SLACK_USER_ID"],
      "groupPolicy": "mention"
    }
  }
}

adkbot gateway

{
  "channels": {
    "email": {
      "enabled": true,
      "consentGranted": true,
      "imapHost": "imap.gmail.com",
      "imapPort": 993,
      "imapUsername": "my-adkbot@gmail.com",
      "imapPassword": "your-app-password",
      "smtpHost": "smtp.gmail.com",
      "smtpPort": 587,
      "smtpUsername": "my-adkbot@gmail.com",
      "smtpPassword": "your-app-password",
      "fromAddress": "my-adkbot@gmail.com",
      "allowFrom": ["your-real-email@gmail.com"]
    }
  }
}

adkbot gateway

{
  "channels": {
    "qq": {
      "enabled": true,
      "appId": "YOUR_APP_ID",
      "secret": "YOUR_APP_SECRET",
      "allowFrom": ["YOUR_OPENID"]
    }
  }
}

adkbot gateway

pip install "adkbot[weixin]"

{
  "channels": {
    "weixin": {
      "enabled": true,
      "allowFrom": ["YOUR_WECHAT_USER_ID"]
    }
  }
}

adkbot channels login weixin

adkbot gateway

pip install adkbot[wecom]

{
  "channels": {
    "wecom": {
      "enabled": true,
      "botId": "your_bot_id",
      "secret": "your_bot_secret",
      "allowFrom": ["your_id"]
    }
  }
}

adkbot gateway

⚙️ Configuration

Config file: ~/.adkbot/config.json

Model Configuration

ADKBot uses LiteLLM under the hood, which means it supports 100+ LLM providers through a unified interface. Simply specify the model using a LiteLLM model string.

[!TIP]

• Groq provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed.
• For local models, use ollama or vllm model strings.

Gemini is a first-class citizen. ADKBot uses Google ADK natively, so Gemini models get the best possible integration.

{
  "agents": {
    "defaults": {
      "model": "gemini/gemini-3.1-pro-preview",
      "apiKey": "",
      "apiBase": null
    }
  }
}

ollama run llama3.2

{
  "agents": {
    "defaults": {
      "model": "ollama/llama3.2"
    }
  }
}

vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000

{
  "agents": {
    "defaults": {
      "model": "openai/meta-llama/Llama-3.1-8B-Instruct",
      "apiKey": "dummy",
      "apiBase": "http://localhost:8000/v1"
    }
  }
}

{
  "agents": {
    "defaults": {
      "model": "openai/your-model-name",
      "apiKey": "your-api-key",
      "apiBase": "https://api.your-provider.com/v1"
    }
  }
}

Channel Settings

Global settings that apply to all channels:

{
  "channels": {
    "sendProgress": true,
    "sendToolHints": false,
    "sendMaxRetries": 3,
    "telegram": { "..." : "..." }
  }
}

Web Search

[!TIP] Use proxy in tools.web to route all web requests through a proxy:

{ "tools": { "web": { "proxy": "http://127.0.0.1:7890" } } }

ADKBot supports multiple web search providers. Configure in ~/.adkbot/config.json under tools.web.search.

When credentials are missing, ADKBot automatically falls back to DuckDuckGo.

{
  "tools": { "web": { "search": { "provider": "brave", "apiKey": "BSA..." } } }
}

{
  "tools": { "web": { "search": { "provider": "tavily", "apiKey": "tvly-..." } } }
}

{
  "tools": { "web": { "search": { "provider": "duckduckgo" } } }
}

MCP (Model Context Protocol)

[!TIP] The config format is compatible with Claude Desktop / Cursor. You can copy MCP server configs directly from any MCP server's README.

ADKBot supports MCP — connect external tool servers and use them as native agent tools.

{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      },
      "my-remote-mcp": {
        "url": "https://example.com/mcp/",
        "headers": { "Authorization": "Bearer xxxxx" }
      }
    }
  }
}

MCP tools are automatically discovered and registered on startup. The LLM can use them alongside built-in tools — no extra configuration needed.

Security

[!TIP] For production deployments, set "restrictToWorkspace": true to sandbox the agent.

Timezone

By default, ADKBot uses UTC. Set agents.defaults.timezone to your local timezone:

{
  "agents": {
    "defaults": {
      "timezone": "Asia/Shanghai"
    }
  }
}

This affects runtime time context, cron schedule defaults, and one-shot at times.

Common examples: UTC, America/New_York, America/Los_Angeles, Europe/London, Asia/Tokyo, Asia/Shanghai.

🧩 Multiple Instances

Run multiple ADKBot instances simultaneously with separate configs and runtime data.

Quick Start

# Create separate instance configs
adkbot onboard --config ~/.adkbot-telegram/config.json --workspace ~/.adkbot-telegram/workspace
adkbot onboard --config ~/.adkbot-discord/config.json --workspace ~/.adkbot-discord/workspace

Run instances:

# Instance A - Telegram bot
adkbot gateway --config ~/.adkbot-telegram/config.json

# Instance B - Discord bot
adkbot gateway --config ~/.adkbot-discord/config.json

Path Resolution

Notes

• Each instance must use a different port if they run concurrently
• Use a different workspace per instance for isolated memory and sessions
• --workspace overrides the workspace defined in the config file

💻 CLI Reference

## Periodic Tasks

- [ ] Check weather forecast and send a summary
- [ ] Scan inbox for urgent emails

🐍 Python SDK

Use ADKBot as a library — no CLI, no gateway, just Python:

from adkbot import AdkBot

bot = AdkBot.from_config()
result = await bot.run("Summarize the README")
print(result.content)

Each call carries a session_id for conversation isolation — different IDs get independent history:

await bot.run("hi", session_id="user-alice")
await bot.run("hi", session_id="task-42")

ADKBot uses ADK's native callback system for lifecycle hooks:

# Callbacks are configured via the Agent's before/after hooks
# See adkbot/agent/callbacks.py for the full callback API

🔌 OpenAI-Compatible API

ADKBot can expose a minimal OpenAI-compatible endpoint for local integrations:

pip install "adkbot[api]"
adkbot serve

By default, the API binds to 127.0.0.1:8900.

Endpoints

• GET /health
• GET /v1/models
• POST /v1/chat/completions

curl

curl http://127.0.0.1:8900/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "hi"}],
    "session_id": "my-session"
  }'

Python (openai)

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8900/v1",
    api_key="dummy",
)

resp = client.chat.completions.create(
    model="adkbot",
    messages=[{"role": "user", "content": "hi"}],
    extra_body={"session_id": "my-session"},
)
print(resp.choices[0].message.content)

🐳 Docker

[!TIP] The -v ~/.adkbot:/root/.adkbot flag mounts your local config directory into the container for persistence.

Docker Compose

docker compose run --rm adkbot-cli onboard   # first-time setup
vim ~/.adkbot/config.json                     # add API keys
docker compose up -d adkbot-gateway           # start gateway

docker compose run --rm adkbot-cli agent -m "Hello!"   # run CLI
docker compose logs -f adkbot-gateway                   # view logs
docker compose down                                      # stop

Docker

# Build the image
docker build -t adkbot .

# Initialize config (first time only)
docker run -v ~/.adkbot:/root/.adkbot --rm adkbot onboard

# Edit config on host to add API keys
vim ~/.adkbot/config.json

# Run gateway
docker run -v ~/.adkbot:/root/.adkbot -p 18790:18790 adkbot gateway

# Or run a single command
docker run -v ~/.adkbot:/root/.adkbot --rm adkbot agent -m "Hello!"

🐧 Linux Service

You can automatically run the gateway in the background on system boot using the built-in systemd installer.

1. Install and start the system service:

adkbot install-service

Note: To keep the gateway running after you log out of SSH, enable user lingering:

loginctl enable-linger $USER

Common operations:

systemctl --user status adkbot-gateway        # check status
systemctl --user restart adkbot-gateway       # restart after config changes
journalctl --user -u adkbot-gateway -f        # follow logs

📁 Project Structure

adkbot/
├── agent/          # 🧠 Core agent (ADK Agent + Runner)
│   ├── callbacks.py#    ADK lifecycle callbacks
│   ├── context.py  #    Prompt builder
│   ├── memory.py   #    Persistent memory
│   ├── skills.py   #    Skills loader
│   ├── subagent.py #    Background task execution
│   └── tools/      #    Built-in tools (10+ tools)
├── adkbot.py       # 🤖 Main AdkBot class (ADK Agent + Runner + LiteLLM)
├── skills/         # 🎯 Bundled skills
├── channels/       # 📱 Chat channel integrations (12+ channels)
├── bus/            # 🚌 Message routing
├── cron/           # ⏰ Scheduled tasks
├── heartbeat/      # 💓 Proactive wake-up
├── session/        # 💬 Conversation sessions
├── config/         # ⚙️ Configuration
├── security/       # 🔒 Safety guards & SSRF protection
└── cli/            # 🖥️ CLI commands

🤝 Contributing

PRs welcome! The codebase is intentionally readable and well-structured. 🤗

Roadmap:

• Multi-modal — See and hear (images, voice, video)
• Long-term memory — Never forget important context
• Better reasoning — Multi-step planning and reflection
• More integrations — Calendar, GitHub, and more
• ADK Web UI — Built-in web interface via adk web
• Self-improvement — Learn from feedback and mistakes

By Kiri Research Labs
Inspired by OpenClaw
_{ADKBot is for educational, research, and technical exchange purposes only}