agentica-gateway

Agentica Gateway

Agentica Gateway 服务，调用 agentica SDK。

支持Lark/Feishu(飞书)、WeCom(企微)、Telegram、Discord、Gradio 等多渠道接入的 AI Agent 网关。

特性

• FastAPI 服务 - REST API + WebSocket Gateway
• 多渠道支持 - Gradio / Lark / WeCom / Telegram / Discord
• 调用 agentica SDK - Agent / Memory / Skills / Tools
• 消息路由 - 多 Agent 路由支持
• 定时任务 - APScheduler Cron 调度
• 流式输出 - WebSocket 实时推送

架构

┌─────────────────────────────────────────────────────────┐
│                   agentica-gateway                       │
│                                                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │              FastAPI Application                 │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────────────┐│    │
│  │  │ REST API │ │WebSocket │ │   Webhooks       ││    │
│  │  │ /api/*   │ │ /ws      │ │   /webhook/*     ││    │
│  │  └────┬─────┘ └────┬─────┘ └────────┬─────────┘│    │
│  └───────┼────────────┼────────────────┼──────────┘    │
│          │            │                │                │
│  ┌───────▼────────────▼────────────────▼──────────┐    │
│  │              Core Services                      │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐       │    │
│  │  │ Channels │ │  Router  │ │Scheduler │       │    │
│  │  │ Manager  │ │          │ │          │       │    │
│  │  └────┬─────┘ └────┬─────┘ └──────────┘       │    │
│  └───────┼────────────┼──────────────────────────┘    │
│          │            │                                │
│  ┌───────▼────────────▼──────────────────────────┐    │
│  │              agentica SDK                      │    │
│  │  Agent | Workspace | Skills | Memory | Tools  │    │
│  └────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘

安装

pip install -e .

# 可选：安装 Telegram/Discord 支持
pip install -e ".[telegram]"
pip install -e ".[discord]"
pip install -e ".[all]"

配置

复制 .env.example 为 .env 并填写：

# 服务配置
HOST=0.0.0.0
PORT=8789

# 模型配置
MODEL_PROVIDER=zhipuai   # zhipuai / openai / deepseek
MODEL_NAME=glm-4.7-flash # glm-4.7-flash is free

# Gradio WebUI
GRADIO_ENABLED=true
GRADIO_PORT=7863

# 飞书
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

# Telegram（可选）
TELEGRAM_BOT_TOKEN=xxx

# Discord（可选）
DISCORD_BOT_TOKEN=xxx

启动

开发模式

python -m uvicorn src.main:app --reload --reload-dir src --port 8789

生产模式

方式一：Gunicorn + Uvicorn（推荐）

# 安装 gunicorn
pip install gunicorn

# 启动（4 个 worker 进程）
gunicorn src.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8789

方式二：直接运行

agentica-gateway

方式三：Docker Compose

# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f

API

REST API

WebSocket Gateway

ws://localhost:8789/ws

# 连接
→ {"type":"req","id":"1","method":"connect","params":{"auth":{"token":"..."}}}
← {"type":"res","id":"1","ok":true,"payload":{"type":"hello-ok"}}

# 聊天（流式）
→ {"type":"req","id":"2","method":"agent","params":{"message":"你好"}}
← {"type":"event","event":"agent.content","payload":{"delta":"你好"}}
← {"type":"res","id":"2","ok":true,"payload":{"content":"你好！"}}

飞书机器人配置

配置

1. 在 飞书开放平台 创建自建应用
2. 在凭证页面获取 App ID 和 App Secret
3. 开启所需权限（见下方）
4. 配置事件订阅（见下方）⚠️ 重要
5. 配置插件：

必需权限

可选权限

文档工具权限

使用飞书文档工具（feishu_doc_*）需要以下权限：

事件订阅 ⚠️

这是最容易遗漏的配置！ 如果机器人能发消息但收不到消息，请检查此项。

在飞书开放平台的应用后台，进入 事件与回调 页面：

1. 事件配置方式：选择 使用长连接接收事件（推荐）
2. 添加事件订阅，勾选以下事件：

3. 确保事件订阅的权限已申请并通过审核

License

Apache-2.0