Skip to content

Build XMTP agents

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

The following instructions walk you through setting up a project from scratch. If you'd prefer to skip the setup, you can start directly from the agent-sdk-starter template.

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

Environment variables

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

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

  • XMTP_ENV: The XMTP network your agent connects to. Use local for running against a local XMTP backend (i.e. Docker container), dev for using the XMTP test network, or production for making your agent discoverable on production apps like Base or World.

  • XMTP_WALLET_KEY: The private key of your EOA wallet address. If you don't have a wallet or simply want one for testing, you can generate keys using the generator below.

  • XMTP_DB_ENCRYPTION_KEY: A key used to encrypt your agent's local SQLite database. You can choose any value, but it must be exactly 64 hex characters (32 bytes).

Local key generator

The following keys are generated in your browser using the Web Crypto API and nothing is sent to any server. These keys work for both testing and production. For production agents, it's recommended to use an existing wallet, but for a quickstart these are perfectly fine.

Usage

This example shows how to create an agent based on your .env file 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();
 
// 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. Persist these files across restarts and deployments. Losing them means your agent will be registered as a new installation.

Vibe coding

To make it easier for you to build with XMTP using LLMs and coding assistants, we offer two AI-ready solutions:

  • A docs MCP server
  • Use case-based llms.txt files

To learn more, see Use XMTP documentation with AI coding assistants.

Talk to your agent

Try out your agents using xmtp.chat, the official playground for agents. Start a new conversation by entering your agent's address (agent.address) and send a message.

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.