Build XMTP agents

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

Installation

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

npm i @xmtp/agent-sdk

Usage

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

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();

Local database

XMTP creates local database files in the dbPath (default is '/') directory. These files store your device identity and message history. To learn more, see Manage agent local database files and installations.

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.

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.