Nostr Agent Server

This module implements a Nostr agent server that handles incoming Nostr events and processes them according to the configured agent capabilities. It provides the core server functionality for receiving, processing, and responding to Nostr events in an agentic manner.

pydantic model agentstr.nostr_agent_server.NoteFilters

Bases: BaseModel

Filters for filtering Nostr notes/events.

Show JSON schema

{
   "title": "NoteFilters",
   "description": "Filters for filtering Nostr notes/events.",
   "type": "object",
   "properties": {
      "nostr_pubkeys": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Nostr Pubkeys"
      },
      "nostr_tags": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Nostr Tags"
      },
      "following_only": {
         "default": false,
         "title": "Following Only",
         "type": "boolean"
      }
   }
}

Fields:

• following_only (bool)

• nostr_pubkeys (list[str] | None)

• nostr_tags (list[str] | None)

field nostr_pubkeys: list[str] | None = None

Filter by specific public keys

field nostr_tags: list[str] | None = None

Filter by specific tags

field following_only: bool = False

Only show notes from followed users (not implemented)

class agentstr.nostr_agent_server.NostrAgentServer(nostr_client: NostrClient | None = None, nostr_mcp_client: NostrMCPClient | None = None, relays: list[str] | None = None, private_key: str | None = None, nwc_str: str | None = None, agent_info: AgentCard | None = None, agent_callable: Callable[[ChatInput], str] | None = None, note_filters: NoteFilters | None = None, price_handler: PriceHandler | None = None)

Bases: object

Server that integrates an external agent with the Nostr network.

Handles direct messages and optional payments, routing them to an external agent.

__init__(nostr_client: NostrClient | None = None, nostr_mcp_client: NostrMCPClient | None = None, relays: list[str] | None = None, private_key: str | None = None, nwc_str: str | None = None, agent_info: AgentCard | None = None, agent_callable: Callable[[ChatInput], str] | None = None, note_filters: NoteFilters | None = None, price_handler: PriceHandler | None = None)

Initialize the agent server.

Parameters:

• nostr_client – Existing NostrClient instance (optional).

• nostr_mcp_client – Existing NostrMCPClient instance (optional).

• relays – List of Nostr relay URLs (if no client provided).

• private_key – Nostr private key (if no client provided).

• nwc_str – Nostr Wallet Connect string for payments (optional).

• agent_info – Agent information (optional).

• agent_callable – Callable to handle agent responses.

• note_filters – Filters for listening to Nostr notes (optional).

• price_handler – PriceHandler to use for determining if an agent can handle a request and calculate the cost (optional).

async chat(message: str, thread_id: str | None = None) → Any

Send a message to the agent and retrieve the response.

Parameters:

• message – The message to send to the agent.

• thread_id – Optional thread ID for conversation context.

Returns:

Response from the agent, or an error message.

async start()

Start the agent server, updating metadata and listening for direct messages and notes.