building-agents_skill

Overview

This skill covers core XMTP Agent SDK setup and patterns for building event-driven messaging agents. It focuses on creating agents, configuring environment variables, handling messages and events, and composing middleware and filters. Use it as a compact reference when starting new agents or adding message handling logic.

How this skill works

The skill explains how to create an XMTP agent from environment variables or manually with a signer, register event handlers for text, lifecycle, and conversation events, and add middleware to process or filter messages. It surfaces key environment variables, middleware patterns, and filter strategies so you can wire agents to react to incoming messages and lifecycle events. Short examples show agent creation, registering handlers, and starting the agent.

When to use it

• Starting a new XMTP agent project or scaffolding an agent service
• Configuring environment variables for secure wallet and DB access
• Implementing message handling for text, reactions, replies, or attachments
• Adding middleware for command routing, error handling, or logging
• Filtering incoming messages (e.g., ignore self-sent messages or specific types)

Best practices

• Prefer Agent.createFromEnv() for consistent environment-driven setup in production
• Keep sensitive keys out of source control and use XMTP_DB_ENCRYPTION_KEY for local DB encryption
• Use middleware chains for cross-cutting concerns (auth, logging, validation) instead of inline handlers
• Register specific event handlers (text, lifecycle, conversation) to keep logic modular
• Filter out self-messages and unsupported message types early to reduce processing

Example use cases

• A notification bot that listens for specific keywords and replies with formatted text
• A command-driven agent using middleware-based CommandRouter to handle slash commands
• A support agent that opens conversations for new DMs and routes attachments to storage
• A lifecycle monitor that logs agent start/stop and exposes a debug test URL
• An archival agent that filters and stores conversations into an encrypted local DB