Skip to content

ADK Connector

Supported in ADKPythonTypeScript

ADK Connector 是一个即插即用的工具包，可以包装任何 ADK 智能体，并将其暴露为 Telegram 和 Discord 等热门消息渠道上的聊天机器人。有关当前支持的渠道列表，请参阅项目仓库。

只需添加几行代码，你就可以弥合本地开发、测试和生产消息平台之间的鸿沟，并原生支持基于数据库的跨设备会话同步。

使用场景

  • 多渠道部署：立即将你的 ADK 智能体（用 Python 或 JavaScript/TypeScript 编写）部署为 Telegram 和 Discord 等支持的消息渠道上的聊天机器人。
  • 跨设备会话同步：无缝过渡对话。在 Telegram 或 Discord 上聊天，然后在本地 ADK Web UI（adk web）中检查、调试并继续完全相同的对话。
  • 弹性状态管理：自动配置异步 SQLite 后端，记录会话状态、工具调用和用户交互。
  • 健壮的多智能体工作流：双导入安全性和跨父子智能体的提示上下文变量自动解析。

前置条件

  • Python 3.10+ 或 Node.js 18+
  • Gemini API 密钥（设置为 GOOGLE_API_KEY）
  • 消息渠道凭据：
    • Telegram：Telegram 账号和来自 BotFather 的 Bot Token
    • Discord：Discord 开发者账号、Discord Bot Token 和客户端 ID

安装

你可以根据 ADK 项目安装 Python 或 JavaScript / TypeScript 版本的连接器。

pip install adk-connector

要启用基于数据库的跨设备会话同步（例如 adk web UI），还需安装 ADK 数据库组件：

pip install "google-adk[db]"

npm install adk-connector-js

与智能体配合使用

以下是如何包装你现有的 Google ADK 智能体并将其启动到消息渠道上。

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

# 加载环境变量
load_dotenv()

# 1. 定义你的标准 Google ADK 智能体
assistant = Agent(
    model='gemini-flash-latest',
    name='my_assistant',
    instruction='你是一个有用的助手。'
)

if __name__ == "__main__":
    # 2. 获取你的 Telegram Bot Token
    token = os.getenv("TELEGRAM_BOT_TOKEN")

    # 3. 绑定连接器
    connector = TelegramConnector(
        token=token,
        agent=assistant
    )

    # 4. 开始轮询
    connector.start()

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

# 加载环境变量
load_dotenv()

# 1. 定义你的标准 Google ADK 智能体
assistant = Agent(
    model='gemini-flash-latest',
    name='my_assistant',
    instruction='你是一个有用的助手。'
)

if __name__ == "__main__":
    # 2. 获取你的 Discord Bot Token
    token = os.getenv("DISCORD_BOT_TOKEN")

    # 3. 绑定连接器
    connector = DiscordConnector(
        token=token,
        agent=assistant
    )

    # 4. 启动机器人！
    connector.start()

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

dotenv.config();

// 1. 定义你的标准 Google ADK 智能体
export const rootAgent = new LlmAgent({
  name: 'my_assistant',
  model: 'gemini-flash-latest',
  instruction: '你是一个有用的助手。'
});

// 2. 在脚本入口点下启动 Telegram 连接器
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();
}

与 adk web 同步会话

对于 Python 项目，你可以将 Telegram 或 Discord 聊天历史直接同步到本地 ADK Web UI，方法是将你的特定提供者用户 ID 映射到本地开发环境。

  1. 在你的代码中，设置 session_management_across_device=True 并传入你的用户 ID：

    connector = TelegramConnector(
    token=token,
    agent=assistant,
    session_management_across_device=True,  # 启动数据库和映持久化
    dev_user_id=os.getenv("TELEGRAM_USER_ID") # 将此 ID 同步到 "user" Web UI 命名空间
)

    connector = DiscordConnector(
    token=token,
    agent=assistant,
    session_management_across_device=True,  # 启动数据库和映持久化
    dev_user_id=os.getenv("DISCORD_USER_ID")  # 将此 ID 同步到 "user" Web UI 命名空间
)

  2. 运行你的机器人脚本： 

    python agent.py

  3. 在另一个终端中运行 ADK Web UI： 
    adk web .
  4. 访问 http://127.0.0.1:8000，直接在浏览器中查看活动对话和工具执行日志。

附加资源