Lark Agentx - Your Feishu AI Assistant 🚀

An AI Agent based on Feishu (Lark) that enables large models to perform function calls and message processing via Feishu.

No Feishu bot configuration required; your Feishu account acts as the AI assistant.

Simply define functions and comments, and your Feishu bot will automatically call them based on the context.

Project Overview 🌟

Lark Agentx is a modern Python application capable of:

• 📊 Reverse-engineering Websockets and APIs transmitting in Feishu Protobuf format to listen to and record messages

• 🤖 Providing custom functions for large models to call

• 🔄 Implementing a function-calling framework based on MCP (Model Context Protocol)

• 💾 Storing messages in a MySQL database using SQLAlchemy

Related MCP server: Feishu MCP Server

Screenshots 🧸

✨ Features

• Function Registration Mechanism: Simple and intuitive function registration decorator

• Automatic Message Processing: Records all received messages (private and group chats)

• Asynchronous Processing: Uses async/await pattern for asynchronous communication

• Data Persistence: Uses SQLAlchemy to store messages in a MySQL database

• Flexible Configuration: Configurable via environment variables

• Containerized Deployment: Supports rapid deployment via Docker

• Intelligent Function Calling: The AI automatically analyzes user input and calls the most relevant function; developers only need to add the function and its comment description

📦 Currently Supported Functions

The project currently includes the following built-in functions for large models to call:

You can call these functions by entering a trigger command in Feishu followed by the operation, for example: /run tell a joke

📂 Project Structure

project/
├── app/                    # 应用程序模块
│   ├── api/                # API相关模块
│   │   ├── auth.py         # 认证模块
│   │   └── lark_client.py  # 飞书客户端
│   ├── config/             # 配置模块
│   │   └── settings.py     # 应用配置
│   ├── core/               # 核心业务逻辑
│   │   ├── mcp_server.py   # MCP服务器（函数注册和处理）
│   │   ├── llm_service.py  # LLM服务
│   │   └── message_service.py  # 消息处理服务
│   ├── db/                 # 数据库相关
│   │   ├── models.py       # 数据模型
│   │   └── session.py      # 数据库会话管理
│   └── utils/              # 工具函数
├── builder/                # 请求构建器
├── extension/              # 扩展功能
│   └── weather_api/        # 天气API集成
├── static/                 # 静态资源
│   ├── resource/           # 图片资源
│   ├── proto_pb2.py        # 协议定义
│   └── lark_decrypt.js     # 飞书解密工具
├── .env                    # 环境变量
├── main.py                 # 应用入口
├── requirements.txt        # 项目依赖
├── docker-compose.yml      # Docker Compose配置
└── Dockerfile              # Docker配置

🛠️ Custom Function Development

In the app/core/mcp_server.py file, you can add your own custom functions using the @register_tool decorator:

@register_tool(name="tell_joke", description="讲一个随机笑话")
def tell_joke() -> str:
    jokes = [
        "为什么程序员都喜欢黑色？因为他们不喜欢 bug 光。",
        "Python 和蛇有什么共同点？一旦缠上你就放不下了。",
        "为什么 Java 开发者很少被邀去派对？因为他们总是抛出异常。",
    ]
    return random.choice(jokes)

@register_tool(name="send_message", description="给指定用户发送消息 {user:用户名称 content:消息内容}")
def send_message(user: str, content: str) -> str:
    """给指定用户发送私信"""
    lark_client = LarkClient(get_auth())
    # ... 实现逻辑 ...
    return f"成功向 {user} 发送了私信: '{content}'"

Important: Simply add the function and its corresponding description; the AI will automatically analyze and call the most matching function based on the user's text, with no need to manually implement function matching logic.

🔧 Requirements

• Python 3.10+

• Node.js 18+

• MySQL Database

📦 Installation

Using Local Environment

1. Install dependencies:

   pip install -r requirements.txt

2. Note for Windows users: Windows systems require additional dependencies:

   pip install win-inet-pton==1.1.0

Using Docker

Method 1: Build image separately

# 构建镜像 
docker build -t feishuapp .

# 运行容器 需要外部mysql 通过docker网关连接宿主机mysql 推荐--env-file
docker run -it feishuapp bash

Method 2: Use Docker Compose (Recommended)

# 启动所有服务（应用和数据库）
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止所有服务
docker-compose down

Using Docker Compose allows you to start the entire application environment with one click, including the MySQL database and application services, which is more convenient and efficient.

🛠️ Configuration

Copy the .env.example file and rename it to .env, containing the following configuration:

# 数据库设置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=123456
DB_NAME=lark_messages

# 飞书的Cookie设置 - 只需配置LARK_COOKIE即可，告别飞书机器人
LARK_COOKIE=""

# 调用函数的触发前缀 （以FUNCTION_TRIGGER_FLAG开头的消息会被大模型解析，所有消息都会被记录到数据库，无论是否以该前缀开头）
FUNCTION_TRIGGER_FLAG="/run"

# 机器人发言前缀 （暂未使用）
AI_BOT_PREFIX="Lark AI Bot:"

# OpenAI API配置 默认是通义千问的，满足OpenAI的大模型厂商都可以
OPENAI_API_KEY=""
OPENAI_API_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
OPENAI_API_MODEL="qwen-plus"

🚀 Usage Guide

Running the Application

Method 1: Run directly

python main.py

Method 2: Use Docker Compose

docker-compose up -d

The application will:

1. Initialize the MCP server

2. Connect to the Feishu API and use your Feishu account as the AI assistant

3. Listen for incoming messages

4. Process and execute function calls initiated by the large model via Feishu

5. Store messages in the MySQL database

🗄️ Database Schema

The application stores messages in the messages table, which has the following structure:

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork this repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing features')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

🐛 Issues and Support

If you encounter any problems or have questions, please submit an issue or visit our discussion forum.

📈 Star Trend

🍔 Community Group

If you are interested in web scraping and AI Agents, please add the author's WeChat from their homepage to be invited to the group chat.

ps: Please join Group 7; if full or expired, please leave an issue | WeChat reminder