Skip to content

Build XMTP agents

This documentation provides examples of agents that use the XMTP network. These agents are built with the XMTP Agent SDK.

Installation

First, we will install @xmtp/agent-sdk as a dependency in our 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 } from '@xmtp/agent-sdk';
import { getTestUrl } from '@xmtp/agent-sdk/debug';
 
// 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.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();

Set environment variables

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

XMTP_WALLET_KEY= # the private key of the wallet
XMTP_DB_ENCRYPTION_KEY= # 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

See the examples for more agent examples.