Component: Event Listener

LangBot's pipeline generates events during runtime for plugins to hook into and process. Each plugin can only have one event listener (components/event_listener/default.yaml), but can register any number of events within it.

Adding Event Listener Component

Execute the command lbp comp EventListener in the plugin directory. Creating an event listener component doesn't require any configuration.

➜  HelloPlugin > lbp comp EventListener
Generating component EventListener...
Component EventListener generated successfully.
组件 EventListener 生成成功。

This will generate default.yaml and default.py files in the components/event_listener/ directory. The .yaml file defines the basic information for the event listener, and the .py file is the event listener handler:

➜  HelloPlugin > tree
...
├── components
│   ├── __init__.py
│   └── event_listener
│       ├── __init__.py
│       ├── default.py
│       └── default.yaml
...

Manifest File: Event Listener

Since each plugin can only have one event listener, no modifications are needed in the manifest file.

Plugin Processing

The following code is generated by default (components/event_listener/default.py). You need to register and implement event processing logic in the initialize method of the DefaultEventListener class.

# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
from __future__ import annotations

from langbot_plugin.api.definition.components.common.event_listener import EventListener
from langbot_plugin.api.entities import events, context


class DefaultEventListener(EventListener):

    async def initialize(self):
        await super().initialize()

        "Fill with your code here"

Adding listeners for specific events:

...
class DefaultEventListener(EventListener):

    async def initialize(self):
        await super().initialize()
        
        @self.handler(events.PersonMessageReceived)
        async def handler(event_context: context.EventContext):
            print("Hello LangBot Plugin!")
            print(event_context)
            
            await event_context.reply(
                platform_message.MessageChain([
                    platform_message.Plain(text=f"Hello from Nahida Plugin!"),
                ])
            )

This code registers a listener for the PersonMessageReceived (receiving any message from private chat) event, prints the event context (EventContext) information when the event is triggered, and calls the event context API to reply with a message.

EventContext stores common context information for this event trigger, while EventContext.event is an object of PersonMessageReceived (or other corresponding event types), storing detailed information about the event.

# Summary of EventContext definition
class EventContext(pydantic.BaseModel):
    """Event context, stores information for this event execution"""
    ...

    event: pydantic.SerializeAsAny[BaseEventModel]
    """Event object, specific type is the type specified when registering the handler, can be found in events.py"""
    
    ...

Event Registration

Event registration is implemented through the @self.handler decorator, with the decorator parameter being the event type. All monitorable events are defined in langbot_plugin.api.entities.builtin.events.

One installation, many usages

The same event listener is called concurrently by several Workspaces and several events:

• Never accumulate state per event on the instance (counters, last event, conversation maps); concurrent callbacks will overwrite each other.
• A callback takes its data only from the current EventContext; never reuse a context or its fields across calls.
• Data that must survive calls belongs in Host storage, keyed with the installation identity and the event-related identity (Workspace, conversation, and so on).
• If you keep per-installation process-local state, release it in on_installation_revoked(binding).

See Certified plugins and shared runtime for the full specification.

What's Next

You have learned the basic information about event listeners. Next, you can:

• See Pipeline Events for event types and fields.
• See the complete EventContext API reference.
• Check out Plugin Common APIs