home / skills / openclaw / skills / building-agents

building-agents skill

safe

/skills/humanagent/xmtp-agent/building-agents

This skill helps you build and configure XMTP agents with middleware, environment setup, and event handling to streamline messaging workflows.

npx playbooks add skill openclaw/skills --skill building-agents

Review the files below or copy the command above to add this skill to your agents.

Files (7)

SKILL.md

2.8 KB

---
name: building-agents
description: Core XMTP Agent SDK setup and patterns. Use when creating new agents, handling messages, setting up middleware, or configuring environment variables. Triggers on agent setup, XMTP configuration, message handling, or middleware implementation.
license: MIT
metadata:
  author: xmtp
  version: "1.0.0"
---

# 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

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

## Quick start

```typescript
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
```

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

FAQ

Which environment variables are required to start an agent?

At minimum set XMTP_WALLET_KEY and XMTP_ENV. Add XMTP_DB_DIRECTORY and XMTP_DB_ENCRYPTION_KEY for local DB persistence and encryption.

Should I create middleware or put logic directly in event handlers?

Use middleware for reusable, cross-cutting functionality like auth, error handling, and command routing. Keep event handlers focused on business logic.