Commands

This module provides utility classes for parsing and handling exclamation-prefixed commands (e.g., !help) commonly used by chat bots and conversational agents on Nostr.

Overview

The module features two main classes:

• Commands: A lightweight, generic dispatcher that routes incoming commands to registered asynchronous handler functions. It provides a base for creating custom command sets.

• DefaultCommands: A concrete implementation of Commands that includes a useful set of built-in commands for most agents:

  • !help: Lists all available commands.

  • !describe: Shows the agent’s name and description.

  • !balance: Returns the user’s current satoshi balance.

  • !deposit [amount]: Creates a Nostr Wallet Connect (NWC) invoice to allow users to top up their balance.

• If the default commands are sufficient, Agentstr will automatically wire them up for you.

• If the default commands are not sufficient, you can create your own by subclassing the Commands class and registering your own command handlers.

Customizing Commands

Here is an example of adding custom commands to an agent. The following example shows how to add a custom command called !custom that sends a message back to the user.

# Override DefaultCommands to add a custom command
class CustomCommands(DefaultCommands):
    def __init__(self):
        super().__init__()
        self.commands.update({
            "custom": self._custom,
        })
        print(f'Commands: {self.commands}')

    # Custom command handler (invoked when user sends "!custom")
    async def _custom(self, command: str, pubkey: str):
        await self.nostr_client.send_direct_message(pubkey, "Custom command received!")

Note

For a complete, working example, check out the Custom Commands example.

Reference

class agentstr.commands.base.Commands(nostr_client: NostrClient, commands: dict[str, Callable[[str, str], None]])

Bases: object

Generic dispatcher that routes exclamation-prefixed commands to asynchronous handler functions.

Parameters:

• nostr_client (NostrClient) – Client instance used to send direct messages back to users.

• commands (dict[str, Callable[[str, str], Awaitable[None]]]) – Mapping from command name (without the leading !) to an async coroutine accepting (command_text, pubkey).

__init__(nostr_client: NostrClient, commands: dict[str, Callable[[str, str], None]])

async default(command: str, pubkey: str)

Fallback handler for unknown or non-command messages.

Parameters:

• command (str) – The raw message text received from the user.

• pubkey (str) – Hex-encoded public key identifying the sender. The dispatcher will reply to this pubkey via a Nostr DM.

async run_command(command: str, pubkey: str)

Parse the incoming text and forward it to the matching command coroutine.

The method expects an exclamation-prefixed string such as "!help" or "!deposit 100".

Example Usage

>>> cmds = DefaultCommands(db, nostr_client, agent_card)
>>> await cmds.run_command("!help", pubkey)

class agentstr.commands.commands.DefaultCommands(db: BaseDatabase | None = None, nostr_client: NostrClient | None = None, agent_card: AgentCard | None = None)

Bases: Commands

Opinionated default command set that most Agentstr agents will want to expose.

Besides inheriting all behaviour from Commands, this class wires up four pre-defined commands (help, describe, balance and deposit) and provides the concrete handler implementations.

Parameters:

• db (Database) – Persistent storage used for reading/updating a user’s balance.

• nostr_client (NostrClient) – Active client connection for sending replies and NWC invoices.

• agent_card (AgentCard) – Metadata about the running agent (name, description, …) used by !describe.

__init__(db: BaseDatabase | None = None, nostr_client: NostrClient | None = None, agent_card: AgentCard | None = None)

See Also

• agentstr.agents.nostr_agent.NostrAgentServer — which intercepts and processes incoming commands from Nostr messages.