@gea-ai/agent-extension-feishu
The Feishu bot Channel for GEA Agents, with an optional Extension that adds the first-party Feishu business Connector and integration Skill.
npm install @gea-ai/agent-extension-feishu @gea-ai/agent-sdk
Use the Channel independently in agent.ts:
import { defineAgent } from "@gea-ai/agent-sdk";
import { feishuChannel } from "@gea-ai/agent-extension-feishu/channel";
export default defineAgent({
name: "Feishu assistant",
slug: "feishu-assistant",
model: "<configured-model-id>",
channels: [feishuChannel()],
});
feishuChannel() returns a regular SDK Channel definition. Use it in channels
or export it from a discovered channels/*.ts file. The SDK collects its hidden
GEA identity Connector and Host environment requirements automatically. It supports feishu and gea
identity modes, receives messages and delivers replies, without adding business
Tools or Skills. Configure FEISHU_APP_ID, secret FEISHU_APP_SECRET and
FEISHU_ALLOWED_SENDERS (* or JSON { tenantKey, openId }[]). WebSocket is the
default; { transport: "http" } also requires FEISHU_VERIFICATION_TOKEN.
To add Feishu business Tools and the integration Skill, use the Extension instead:
// extensions/feishu.ts
export { default } from "@gea-ai/agent-extension-feishu";
The Extension reuses feishuChannel() and adds the following business capabilities.
Business calls use the exposed {alias}__call Tool with lark-cli argv and optional
stdin. The platform executes the official CLI in its sandbox and manages the
Connector's encrypted state. The Agent chooses --as bot or --as user for each
business command. Computer and Bash are optional and do not install lark-cli.
Hosted Channel calls use the application's configured Feishu bot credentials.
--as user requires that message sender's own authorized login for the same app;
missing authorization returns a link for the sender. The Channel delivers ordinary
chat replies, and all credentials stay outside Computer. Independent Connector
invocations retain the existing Connection authorization flow.
The bot accepts private text and rich-text (post) messages, and group messages that explicitly mention
this application's bot. Group replies create or continue the triggering message's
topic. Members share that topic's conversation while each call retains its actual
sender's authorization. Ordinary group messages and empty mention-only messages
do not start an Agent run. Both HTTP callbacks and WebSocket input use this policy.
Rich text preserves titles, paragraphs, links, mentions and code as Agent input.
Unsupported message types or embedded media receive an explicit request to resend
the content as text; these messages do not start an Agent run or submit a partial summary.
All Channels can declare the SDK's generic requirePlatformUser policy. Feishu uses
this same policy; the Host enforces admission, history
reads and execution. Hosted GEA requires a Controller with channel-user-policy-v1;
unsupported Controllers fail explicitly. Local default and explicit false policies
support bot messages and replies without GEA login. Local true policy and invalid
policy values are rejected. Environment selection requires an upgraded local App
Server; the selector remains private and is not exposed through ctx.env.
Both standalone Channel and Extension accept a fixed { requirePlatformUser: true }
or { requirePlatformUser: false } option, or a selector such as
{ requirePlatformUser: { env: "REQUIRE_PLATFORM_USER", default: false } }. Omit requirePlatformUser to select the mode
through environment configuration. Set FEISHU_REQUIRE_PLATFORM_USER=true to require GEA user authorization before every
Run and attribute LLM usage to that user. Without a matcher, configure CHANNEL_GEA_CLIENT_ID and
secret CHANNEL_GEA_CLIENT_SECRET for a GEA OAuth Client with
openid agents:invoke offline_access and access to this Project/Agent environment.
Omitting the environment value uses false; invalid values or failed GEA authorization never
silently downgrade. On hosted GEA, duplicate events retain their original identity
decision. Local external mode uses the verified Feishu principal without a hosted
identity receipt and does not issue GEA grants.
To identify senders without another GEA login, declare a platform user matcher. It is a plain synchronous function that runs as ordinary Agent Worker code in the pinned Worker:
feishuChannel({
platformUserMatcher: (sender, candidate) =>
sender.openId === candidate.account.accountId,
});
The Host verifies the Feishu event, selects candidate GEA accounts and asks the
matcher to accept or reject each one; it still checks the user's current membership
and permissions. The matcher runs before requirePlatformUser. A rejection or
failure gives private guidance and never falls back to OAuth or external identity.
With transport: "http" the Host verifies callback signatures, so also configure
secret FEISHU_ENCRYPT_KEY. Packages built for the retired native matcher must be
rebuilt with the current SDK and redeployed. Without a matcher, requirePlatformUser
alone decides identity and true uses the OAuth entry. Feishu business user consent
remains separate.
Both modes use the same transport and cards. GEA group histories remain separate
from external-mode histories, and Feishu business --as bot|user authorization
is independent. Hosted upgrades require a rebuilt Agent and a new Channel
installation on an upgraded Host. Both entrypoints share the same identity flow.
With platformUserMatcher, the SDK does not generate an identity OAuth Connector
or CHANNEL_GEA_CLIENT_ID / CHANNEL_GEA_CLIENT_SECRET requirements. Verified
events use the Channel installation, its bound Project and the matched active
organization member. Revoked installations, removed Project bindings and removed
members invalidate authorization. Upgrade the Host and Controller (native grant
capability channel-native-user-grant-v1) and rebuild the Agent together. New
channel-user: principals do not inherit historical channel-oauth: private
Sessions or Connections; old grants retain their original validation. Explicit
OAuth without a matcher and business Connector authorization are unchanged.
Local development versus hosted preview
For local gea agent dev, use an explicit development entry with
feishuChannel() and no platformUserMatcher. Configure a development Feishu
app and sender allowlist, with FEISHU_REQUIRE_PLATFORM_USER unset or false.
Messages then use local/external sender identity, not verified platform identity.
The default WebSocket receiver is supported; real connectivity and delivery
still require valid Feishu credentials.
Local dev hard-rejects matcher declarations, including when
requirePlatformUser: false: the local Host lacks the verified ingress, candidate
account, membership and Project authorization chain. Test the matcher as a pure
function using synthetic inputs locally. To test full authorization, pack/upload
the matcher-enabled entry and run a hosted preview installation. Keep that
release entry separate and check its matcher descriptor before upload so the
local declaration is not accidentally shipped. A local preview page or changing
an environment header does not provide hosted authorization.
If startup fails at Runtime channel-object/converge with 403, upgrade the CLI
and its bundled Runtime together. Standalone Runtime authenticates this request
against the selected Worker's registered profile, not a process-global secret.
Do not set a shared Runtime global secret as a workaround. Provider credential or
WebSocket failures after converge require separate diagnosis; converge success
alone does not verify Feishu send/receive.