What is XMTP Agent SDK?

A library for building event-driven messaging agents on XMTP, with support for middleware, commands, and environment-based setup.

How do I create an agent from environment variables?

Use Agent.createFromEnv() as shown in the quick start to bootstrap from XMTP_WALLET_KEY and other vars.

What events can I handle?

You can handle text, lifecycle, conversation, and various message types with the agent's event API.

XMTP

@humanagent

npx machina-cli add skill @humanagent/xmtp-agent --openclaw

Files (1)

SKILL.md

2.8 KB

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

Quick start

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

// 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

Source

git clone https://clawhub.ai/humanagent/xmtp-agentView on GitHub

Overview

Build event-driven XMTP agents with the @xmtp/agent-sdk. It covers creating and configuring agents, handling messages, and integrating middleware and environment variables. This approach leads to robust, scalable agents that respond to text, conversations, and actions.

How This Skill Works

You instantiate an Agent from the @xmtp/agent-sdk, then configure it via environment or manual setup (Agent.createFromEnv, setup-environment). The agent registers event handlers for text and lifecycle events, and you compose a middleware chain (including command routing and filters) to process messages.

When to Use It

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

Quick Start

Step 1: Create agent from environment variables (Agent.createFromEnv()).
Step 2: Register a text handler with agent.on('text', ctx => { ... }).
Step 3: Start the agent with agent.start() and monitor readiness (e.g., log the test URL).

Best Practices

Organize environment variables and keep secrets secure; document required vars like XMTP_WALLET_KEY, XMTP_ENV, and XMTP_DB_DIRECTORY.
Prefer Agent.createFromEnv() for quick bootstrap and predictable configuration.
Register text and lifecycle handlers early, then validate with test messages.
Build a middleware chain to handle errors, routing, and command processing (e.g., middleware-command-router).
Apply filters to constrain message types and sender to avoid self-messages and noise.

Example Use Cases

Create an agent from environment variables and respond to text messages with a greeting.
Log agent readiness using a test URL once the agent starts.
Add a middleware layer to catch and handle errors in the processing chain.
Filter inbound messages to process only text messages from external users.
Handle multiple message types (text, reaction, attachment) via dedicated event handlers.

Frequently Asked Questions

Add this skill to your agents