xmtplabs/building-agents

XMTP agent basics

Build event-driven, middleware-powered messaging agents on the XMTP network using the @xmtp/agent-sdk.

When to apply

Reference these guidelines when:

• Creating a new XMTP agent
• Setting up environment variables
• Handling text messages and events
• Implementing middleware
• Using filters and context helpers

Rule categories by priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Setup | CRITICAL | setup- | | 2 | Events | HIGH | events- | | 3 | Middleware | MEDIUM | middleware- | | 4 | Filters | MEDIUM | filters- |

Quick reference

Setup (CRITICAL)

• setup-environment - Configure environment variables for agent
• setup-from-env - Create agent using Agent.createFromEnv()
• setup-manual - Manual agent creation with signer

Events (HIGH)

• events-text - Handle text messages
• events-lifecycle - Handle start/stop events
• events-conversation - Handle new DM and group conversations
• events-message-types - Handle different message types (reaction, reply, attachment)

Middleware (MEDIUM)

• middleware-basics - Create and register middleware
• middleware-error-handling - Handle errors in middleware chain
• middleware-command-router - Use CommandRouter for slash commands

Filters (MEDIUM)

• filters-message-types - Filter by message type
• filters-sender - Filter out self-messages

Installation

npm install @xmtp/agent-sdk
# or
yarn add @xmtp/agent-sdk

SDK 2.0+ uses unified exports: import everything from @xmtp/agent-sdk (no /debug, /middleware, /user, /util subpaths).

Quick start

import { Agent, getTestUrl } from "@xmtp/agent-sdk";

// Create agent using environment variables
const agent = await Agent.createFromEnv();

// Handle text messages
agent.on("text", async (ctx) => {
  await ctx.conversation.sendText("Hello from my XMTP Agent!");
});

// Log when ready
agent.on("start", () => {
  console.log(`Agent online: ${getTestUrl(agent.client)}`);
});

await agent.start();

Environment variables

| Variable | Purpose | Example | |----------|---------|---------| | XMTP_WALLET_KEY | Private key for wallet | 0x1234...abcd | | XMTP_DB_ENCRYPTION_KEY | Database encryption key | 0xabcd...1234 | | XMTP_ENV | Network environment | dev or production | | XMTP_DB_DIRECTORY | Database directory | ./data |

How to use

Read individual rule files for detailed explanations:

rules/setup-environment.md
rules/events-text.md
rules/middleware-basics.md