Feishu

Overview

FeishuChannelExtension bridges inbound messages from a Feishu (Lark) bot into the VeADK Runner.

This page treats Feishu as an inbound message channel: messages from Feishu users trigger the agent. To let the agent call Feishu capabilities, see Feishu tools.

It listens for the bot’s message events and maps Feishu’s session identity onto VeADK: the message sender becomes the Runner’s user identity, and the thread the message belongs to becomes the session identity; when there is no thread, it falls back to the current group or direct chat as the session. In 1.0.5 it extracts text from plain messages, interactive cards, and merged-forward messages and supports the synchronous Channel SDK lifecycle.

Thread history and quoted-message retrieval are enabled by default. The extension reads related Feishu messages and sends their content to the model. If the application uses sessions, long-term memory, or logging, the content may also be retained under those policies. Before enabling the bot, confirm that message scopes, model processing, and retention meet your requirements. Disable include_thread_history and include_parent_message when this context is not required.

When an incoming message belongs to a Feishu thread or is a reply, the extension automatically fetches the thread history or the quoted parent message and prepends that context to the user message before forwarding it to the agent. See Thread history and quoted messages.

Environment & prerequisites

Installation:

pip install veadk-python[extensions]

If you only want this capability, install it on its own:

pip install lark-oapi

Environment variables:

TOOL_FEISHU_CHANNEL_APP_ID
TOOL_FEISHU_CHANNEL_APP_SECRET
TOOL_FEISHU_CHANNEL_TRANSPORT: defaults to ws
TOOL_FEISHU_CHANNEL_STREAMING: whether to enable streaming output, defaults to false
TOOL_FEISHU_CHANNEL_REACTIONS: whether to reply with a “received” reaction on incoming messages, defaults to false

Or configure in config.yaml:

config.yaml

tool:
  feishu_channel:
    app_id: cli_xxx
    app_secret: xxx
    transport: ws
    streaming: true
    reactions: true

Usage

examples/channel/feishu_bot.py

import asyncio

from veadk import Agent, Runner
from veadk.extensions import FeishuChannelExtension
from veadk.memory.short_term_memory import ShortTermMemory

agent = Agent(
    name="feishu_agent",
    model_name="doubao-seed-2-1-pro-260628",
    instruction="You are an assistant that talks to users through a Feishu bot.",
)

runner = Runner(
    agent=agent,
    app_name="veadk_feishu_demo",
    user_id="veadk_feishu_default_user",
    short_term_memory=ShortTermMemory(),
)

channel = FeishuChannelExtension(
    runner=runner,
    channel_kwargs={"transport": "ws"},
)


async def main():
    await channel.connect()


if __name__ == "__main__":
    asyncio.run(main())

Parameters

Parameter	Type	Default	Description
`runner`	`Runner`	None	Required. VeADK runner that handles inbound Feishu messages.
`app_id`	`str \| None`	`TOOL_FEISHU_CHANNEL_APP_ID`	Feishu application ID, with `TOOL_LARK_ENDPOINT` as a compatibility fallback.
`app_secret`	`str \| None`	`TOOL_FEISHU_CHANNEL_APP_SECRET`	Feishu application secret, with `TOOL_LARK_API_KEY` as a compatibility fallback. Supply it through an environment variable or secret manager.
`channel`	`Any \| None`	`None`	Existing Feishu Channel client. When supplied, the extension does not create a client.
`session_id_factory`	`Callable[[Any], str] \| None`	Thread, reply, chat, or message identifier	Custom mapping from a Feishu message to the VeADK `session_id`.
`user_id_factory`	`Callable[[Any], str] \| None`	Sender `union_id`, `open_id`, or `user_id`	Custom mapping from a Feishu sender to the VeADK `user_id`.
`message_handler`	`Callable \| None`	`None`	Custom message handler. When unset, the extension calls `runner`. It may return a string, an awaitable string, or `None`.
`response_formatter`	`Callable[[str], dict[str, str]] \| None`	`{"text": text}`	Converts agent text into the Feishu send payload.
`reply_in_thread`	`bool`	`True`	Whether to reply to the original message so output remains in its thread.
`ignore_empty_messages`	`bool`	`True`	Whether to ignore messages from which no text can be extracted.
`channel_kwargs`	`dict[str, Any] \| None`	`None`	Options passed when creating the Channel client. `transport` reads `TOOL_FEISHU_CHANNEL_TRANSPORT` and otherwise defaults to `ws`.
`streaming`	`bool`	`False`	Whether to stream replies. `TOOL_FEISHU_CHANNEL_STREAMING=true` also enables it.
`reactions`	`bool`	`False`	Whether to add a received reaction. `TOOL_FEISHU_CHANNEL_REACTIONS=true` also enables it.
`include_parent_message`	`bool`	`True`	Whether to fetch and attach the quoted parent message for replies.
`include_thread_history`	`bool`	`True`	Whether to fetch and attach thread history for thread messages.
`thread_history_limit`	`int`	`20`	Maximum thread-history messages to fetch. Values below `1` are treated as `1`.

Thread history and quoted messages

When an incoming message comes from a Feishu thread or is a reply, the extension fetches the relevant context and prepends it to the user message before forwarding it to the agent:

Thread history: when the message belongs to a thread, the extension fetches the thread’s history ordered oldest-first (up to thread_history_limit messages, excluding the current message) and prepends it as thread context.
Quoted message: when the message is a reply but does not belong to a thread, the extension fetches the quoted parent message; if the parent cannot be fetched, it falls back to the root message of the reply chain and prepends it as quoted context.

Thread history takes precedence over quoted messages: when a thread identifier is present, only the thread history is attached and the parent message is not fetched separately. Fetched message content is rendered back to readable text, covering text, rich-text (post), interactive card, and merged-forward messages.

Fetching thread history and quoted messages requires calling Feishu OpenAPI message endpoints, so app_id and app_secret must be configured (constructor parameters, or the TOOL_FEISHU_CHANNEL_APP_ID / TOOL_FEISHU_CHANNEL_APP_SECRET environment variables, falling back to TOOL_LARK_ENDPOINT / TOOL_LARK_API_KEY). When credentials are not configured the capability is skipped silently without raising an error.

Usage example

Save and configure the feishu_bot.py example above, then create the following file in the same directory:

examples/channel/feishu_bot_thread.py

from veadk.extensions import FeishuChannelExtension
from feishu_bot import runner

channel = FeishuChannelExtension(
    runner=runner,
    include_thread_history=True,
    thread_history_limit=30,
    include_parent_message=True,
)

Disable the capability so the extension forwards only the current message text:

examples/channel/feishu_bot_plain.py

from veadk.extensions import FeishuChannelExtension
from feishu_bot import runner

channel = FeishuChannelExtension(
    runner=runner,
    include_parent_message=False,
    include_thread_history=False,
)

Notes

The Feishu WebSocket long-connection mode is used by default, so as long as the bot has subscribed to message events, you can start the connection directly.
Replies are sent as replies to the original message by default, keeping VeADK output attached to the current Feishu message thread.
Override the default identity mapping via session_id_factory and user_id_factory.
connect() and disconnect() support both async clients and synchronous Channel SDK clients exposing start() / stop().

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Overview

Environment & prerequisites

Usage

Parameters

Thread history and quoted messages

Usage example

Notes

​Overview

​Environment & prerequisites

​Usage

​Parameters

​Thread history and quoted messages

​Usage example

​Notes

Overview

Environment & prerequisites

Usage

Parameters

Thread history and quoted messages

Usage example

Notes