xmtplabs/xmtp-agent-examples/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

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

How to use

Read individual rule files for detailed explanations:

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