Kimi Agent Module API

The stable, host-independent contracts for building Kimi application modules: separately installed packages that add commands, LLM tools, background jobs, event handlers, per-guild settings, and durable data to a Kimi deployment.

This package contains no bot runtime, Discord client, database implementation, or module loader. It exports:

• ModuleSpec, ModuleLoadContext, ModuleRuntimeContext: the declaration a module publishes and the two contexts the host hands it.
• kimi_agent_module_api.contracts: every runtime port as a typing.Protocol (storage, scheduler, events, Discord actions, interactions, HTTP, services, trust, proposals, health) plus the validators the host runs at preflight.
• kimi_agent_module_api.events: the normalized discord.* event payloads.
• kimi_agent_module_api.testing: a fake for every port, load_context() for exercising create(), and MemoryStorage (install the testing extra) so a module can unit test itself with only this package installed.

A module exposes a ModuleSpec through the kimi_agent.modules entry-point group:

[project]
dependencies = ["kimi-agent-module-api>=1,<2"]

[project.entry-points."kimi_agent.modules"]
my_module = "my_module_package:SPEC"

The module guide documents installation, declarations, lifecycle, and every runtime port. The reference module is a complete, commented example that exercises most ports; start there.

Guild-scoped live command replacement was added in 1.1. Modules using InteractionRouter.replace_guild_commands() should depend on kimi-agent-module-api>=1.1,<2 and require the host capability discord.guild_commands.v1.

Version 1.2 adds typed modal forms and a narrow Components V2 layout model. Once a response uses that layout model, Discord requires every later edit of the same message to remain a layout. Modules using them should depend on kimi-agent-module-api>=1.2,<2 and require discord.modals.v1 and/or discord.components_v2.v1.

Version 1.3 adds cached author classification to message-deletion events: MessageDeleteEvent.author_is_bot and MessageBulkDeleteEvent.bot_message_ids. The values remain unknown for messages that were absent from Discord's cache.

Testing the SDK

From this package directory, run its tests without installing the Kimi application:

uv run --isolated --group test python -m pytest -q