LangBot EBA Adapter Development

LangBot EBA Adapter Development

Use this skill when implementing or reviewing a LangBot platform adapter under the Event-Based Agents architecture.

Controlling a running instance via MCP

Beyond writing code, you can drive a live LangBot instance over MCP — no raw HTTP needed. Two MCP servers exist (both reuse existing API keys; see AGENTS.md):

• LangBot instance — http://<host>:5300/mcp (auth: web-UI lbk_ key or the api.global_api_key from config.yaml). Manage bots, pipelines, models, knowledge bases, and skills. See the langbot-mcp-ops skill.
• LangBot Space marketplace — https://space.langbot.app/mcp (auth: Personal Access Token). Search plugins / MCP servers / skills. See the langbot-space-ops skill.

Any change to an agent-accessible HTTP API endpoint must keep the matching MCP tool and these skills in sync.

Core Rule

Do not let platform-native event or message shapes leak into LangBot's common path. Each adapter must convert incoming SDK objects into unified EBA entities before dispatch:

• Events: langbot_plugin.api.entities.builtin.platform.events
• Message chains: langbot_plugin.api.entities.builtin.platform.message.MessageChain
• Users/groups/members: langbot_plugin.api.entities.builtin.platform.entities
• Raw platform objects may remain only in source_platform_object for debugging or platform-specific escape hatches.

Start Here

1. Read the EBA design docs in LangBot/docs/event-based-agents/.
2. Read the architecture-level acceptance checklist before writing or validating code:
   • LangBot/docs/event-based-agents/adapters/acceptance-checklist.md
3. Read the current reference adapter before writing code. Prefer Telegram first:
   • LangBot/src/langbot/pkg/platform/adapters/telegram/
   • LangBot/docs/event-based-agents/adapters/telegram.md
4. Read the legacy source adapter for the target platform:
   • LangBot/src/langbot/pkg/platform/sources/<platform>.py
   • LangBot/src/langbot/pkg/platform/sources/<platform>.yaml
5. Inspect SDK entity definitions in langbot-plugin-sdk/src/langbot_plugin/api/entities/builtin/platform/.
6. Search before assuming APIs. Platform SDKs change often.

Adapter Layout

Create one directory per adapter:

LangBot/src/langbot/pkg/platform/adapters/<platform>/
├── __init__.py
├── adapter.py
├── api_impl.py
├── event_converter.py
├── manifest.yaml
├── message_converter.py
├── platform_api.py
├── types.py
└── <platform>.svg

Add optional helpers such as voice.py only when the platform has a real domain-specific surface.

Ensure pyproject.toml package data includes adapter assets:

package-data = { "langbot" = ["templates/**", "pkg/platform/sources/*", "pkg/platform/adapters/**", ...] }

Implementation Checklist

• manifest.yaml declares metadata.name, config schema, supported events, common APIs, and platform-specific APIs.
• adapter.py creates the platform client, subscribes to native events, filters self/bot loops where appropriate, calls event_converter.target2yiri(...), then dispatches the EBA event.
• event_converter.py maps native events to EBA event classes such as MessageReceivedEvent, MessageEditedEvent, MessageDeletedEvent, MessageReactionEvent, MemberJoinedEvent, BotInvitedToGroupEvent, and PlatformSpecificEvent.
• message_converter.py maps native messages to MessageChain, and maps MessageChain back to the platform send format.
• api_impl.py implements common EBA APIs: send, reply, edit, delete, forward, user/group/member lookup, moderation, upload/file URL, leave group.
• platform_api.py keeps platform-specific calls behind call_platform_api(action, params).
• Unsupported common APIs must raise explicit SDK platform errors such as NotSupportedError; do not silently no-op.
• Destructive APIs such as kick, ban, leave, delete, or moderation must be gated in live tests and documented.

Conversion Contract

For message events, the common shape should look like this regardless of platform:

platform_events.MessageReceivedEvent(
    type="message.received",
    adapter_name="<platform>",
    message_id=<platform_message_id>,
    message_chain=platform_message.MessageChain([...]),
    sender=platform_entities.User(...),
    chat_type=platform_entities.ChatType.PRIVATE or ChatType.GROUP,
    chat_id=<conversation_or_channel_id>,
    group=platform_entities.UserGroup(...) or None,
    source_platform_object=<raw_object>,
)

Message content should use common components:

• Source for original message id/time when available.
• Plain for text.
• At / AtAll for mentions.
• Image, Voice, File for media.
• Forward only when the platform can represent or emulate it safely.

If a platform event cannot cleanly map to a common event, emit PlatformSpecificEvent with a compact action and structured data.

Unit Tests

Add focused tests under LangBot/tests/unit_tests/platform/test_<platform>_eba_adapter.py.

Cover at least:

• Manifest supported events match adapter supported_events().
• Manifest supported APIs match adapter supported_apis().
• Platform API map matches manifest actions.
• Dispatcher chooses the most specific EBA listener.
• Message converter maps every supported common component both directions where possible:
  • Source
  • Plain
  • At
  • AtAll
  • Image
  • Voice
  • File
  • Quote
  • Face
  • Forward
  • Unknown
  • mixed chains preserving order
• Event converter maps message received/edited/deleted/reaction, raw uncached gateway events, member events, and bot join/leave events.
• Send/reply methods pass correct platform kwargs and return MessageResult.

Run the existing reference adapter tests too:

cd LangBot
uv run pytest tests/unit_tests/platform/test_<platform>_eba_adapter.py tests/unit_tests/platform/test_telegram_eba_adapter.py
uv run python -m py_compile tests/e2e/live_<platform>_eba_probe.py
git diff --check

Live Test Workflow

Direct adapter live probes are useful diagnostics, but they are not sufficient acceptance evidence for EBA. Treat tests/e2e/live_<platform>_eba_probe.py as an auxiliary tool only. The final adapter record must distinguish:

• plugin-e2e-ui: real SDK plugin through standalone runtime, LangBot core, adapter, and a real/simulator UI action. This can mark an inbound UI item complete.
• plugin-e2e-protocol: real SDK plugin through standalone runtime, LangBot core, adapter, and a protocol-boundary injected event. This is useful evidence but must not be claimed as UI coverage.
• plugin-e2e-outbound: real SDK plugin calls an API and the bot output is visible in the real/simulator UI. This can mark send/API coverage complete.
• adapter-live: direct adapter probe connected to a real/simulator endpoint. This is auxiliary only.
• unit: mocked conversion/API-shape coverage. This is auxiliary only.
• not-supported: platform protocol or SDK has no equivalent. Must include the reason.
• blocked: intended capability could not be verified. This is not complete.

Write a live probe in LangBot/tests/e2e/live_<platform>_eba_probe.py. It should:

1. Read token/client ids from environment variables or CLI args.
2. Start the adapter directly.
3. Register an EBA listener and write JSONL evidence to LangBot/data/temp/.
4. Wait for a real user/platform event instead of fabricating the entrypoint.
5. Exercise common APIs and call_platform_api actions.
6. Observe returned gateway events for edit/delete/reaction/member/bot lifecycle where available.
7. Print a summary containing passed, failed, skipped, and observed event types.
8. Redact or avoid printing secrets.
9. Keep destructive operations behind flags and run them last.

Use Computer Use when the user asks for real platform end-to-end coverage. Actually send messages/click reactions in the platform UI or otherwise trigger real user-side events; do not replace that with unit tests.

For media/component acceptance, keep the direction and trigger source explicit:

• Real inbound media only counts when a human-side platform UI or simulator UI sends the image/file/voice to the bot and the plugin JSONL records the corresponding common component.
• Bot outbound media only proves send_message/adapter send conversion. It does not prove inbound conversion.
• Protocol-boundary injection, such as sending a OneBot event directly into a reverse WebSocket adapter, is useful and should be labelled plugin-e2e-protocol, but it must not be reported as UI-level end-to-end media upload.
• If the UI cannot send or upload the media, record the item as blocked with the exact client/simulator limitation.