Skip to content

Build XMTP agents

Use the XMTP Agent SDK to build agents that interact with the XMTP network.

Prerequisites

Install a Node.js LTS release and run the following commands to get started:

# Create a folder for your agent code
mkdir my-agent
cd my-agent
 
# Initialize a new project with ES module support
npm init --init-type=module -y
 
# Install TypeScript as development dependency (-D)
npm i -D typescript
 
# Install tsx to run TypeScript files directly
# without a separate build step
npm i -D tsx
 
# Install Node.js type definitions
# to enable TypeScript support for built-in APIs
npm i -D @types/node

Once complete, you can run your TypeScript code using tsx src/your-code.ts.

Installation

Install @xmtp/agent-sdk as a dependency in your project.

npm
npm i @xmtp/agent-sdk

Usage

This example shows how to create an agent that sends a message when it receives a text message.

Node
import { Agent, getTestUrl } from '@xmtp/agent-sdk';
 
// 2. Spin up the agent
const agent = await Agent.createFromEnv({
  env: 'dev', // or 'production'
});
 
// 3. Respond to text messages
agent.on('text', async (ctx) => {
  await ctx.conversation.sendText('Hello from my XMTP Agent! 👋');
});
 
// 4. Log when we're ready
agent.on('start', () => {
  console.log(`Waiting for messages...`);
  console.log(`Address: ${agent.address}`);
  console.log(`🔗 ${getTestUrl(agent.client)}`);
});
 
await agent.start();

Local database

XMTP creates local database files in the dbPath (default is '/') directory. These files store your device identity and message history.

Set environment variables

To run an example XMTP agent, you must create a .env file with the following variables:

XMTP_WALLET_KEY=0x # the private key of the wallet
XMTP_DB_ENCRYPTION_KEY=0x # encryption key for the local database
XMTP_ENV=dev # local, dev, production

Vibe coding

See these Cursor rules for vibe coding agents with XMTP using best practices.

Prompt: lets create an example that gets a number and returns its 2x multiple (use claude max)

Talk to your agent

Try out the example agents using xmtp.chat, the official playground for agents.

xmtp.chat DM screenshot

Debug an agent

To learn more, see Debug an agent

Deploy an agent

To learn more, see Deploy an agent.

Agent examples

Visit the examples repository for more agent examples.