Build an agent

Use the XMTP Agent SDK to build a Node.js agent that listens for messages and responds.

Install

npm i @xmtp/agent-sdk

Configure

Create a .env file:

XMTP_BACKEND_URL=https://your-backend.example.com
XMTP_WALLET_KEY=0x...
XMTP_DB_ENCRYPTION_KEY=0x...
XMTP_ENV=my-app

XMTP_BACKEND_URL is required and must include its scheme. XMTP_ENV is only a label for the default database file name. The wallet key must use 0x hex format. The database encryption key is 32 bytes.

Start the agent

import { 
class Agent<ContentTypes = unknown>
Event-driven XMTP agent that routes conversations and messages to middleware.
Agent } from "@xmtp/agent-sdk";

const 
const agent: Agent<BuiltInContentTypes>
agent = await 
class Agent<ContentTypes = unknown>
Event-driven XMTP agent that routes conversations and messages to middleware.
Agent.
Agent<ContentTypes = unknown>.createFromEnv<[]>(options?: Partial<AgentCreateOptions<[]>> | undefined): Promise<Agent<BuiltInContentTypes>>
Create an agent from XMTP_* variables. XMTP_BACKEND_URL overrides options.backendUrl; one must be supplied.
createFromEnv();

const agent: Agent<BuiltInContentTypes>
agent.
NodeJS.EventEmitter<EventHandlerMap<BuiltInContentTypes>>.on<"text">(eventName: keyof EventHandlerMap<BuiltInContentTypes>, listener: (ctx: MessageContext<string, BuiltInContentTypes>) => void): Agent<BuiltInContentTypes>
Adds the listener function to the end of the listeners array for the event
named eventName. No checks are made to see if the listener has already
been added. Multiple calls passing the same combination of eventName and
listener will result in the listener being added, and called, multiple times.
server.on('connection', (stream) => {
  console.log('someone connected!');
});
Returns a reference to the EventEmitter, so that calls can be chained.
By default, event listeners are invoked in the order they are added. The emitter.prependListener() method can be used as an alternative to add the
event listener to the beginning of the listeners array.
import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
@since ― v0.1.101
@param ― eventName The name of the event.
@param ― listener The callback function
on("text", async (
ctx: MessageContext<string, BuiltInContentTypes>
ctx) => {
  await 
ctx: MessageContext<string, BuiltInContentTypes>
ctx.
ConversationContext<BuiltInContentTypes, Conversation<unknown>>.conversation: Conversation<unknown>
Return the conversation that triggered this context.
conversation.
Conversation<unknown>.sendText(text: string, opts?: SendOpts): Promise<string>
Sends a text message
@param ― text - The text to send
@param ― opts - Send options (optimistic delivery, idempotency key)
@returns ― Promise that resolves with the message ID after it has been sent
sendText("Hello from my XMTP agent!");
});

const agent: Agent<BuiltInContentTypes>
agent.
NodeJS.EventEmitter<EventHandlerMap<BuiltInContentTypes>>.on<"start">(eventName: keyof EventHandlerMap<BuiltInContentTypes>, listener: (ctx: ClientContext<BuiltInContentTypes>) => void): Agent<BuiltInContentTypes>
Adds the listener function to the end of the listeners array for the event
named eventName. No checks are made to see if the listener has already
been added. Multiple calls passing the same combination of eventName and
listener will result in the listener being added, and called, multiple times.
server.on('connection', (stream) => {
  console.log('someone connected!');
});
Returns a reference to the EventEmitter, so that calls can be chained.
By default, event listeners are invoked in the order they are added. The emitter.prependListener() method can be used as an alternative to add the
event listener to the beginning of the listeners array.
import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
@since ― v0.1.101
@param ― eventName The name of the event.
@param ― listener The callback function
on("start", () => {
  
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log(`Agent address: ${
const agent: Agent<BuiltInContentTypes>
agent.
Agent<BuiltInContentTypes>.address: string | undefined
Return the agent account address, when the client has one.
address}`);
});

await 
const agent: Agent<BuiltInContentTypes>
agent.
Agent<BuiltInContentTypes>.start(options?: AgentStreamingOptions): Promise<void>
Start conversation and message streams. Calling this while running is a no-op.
start();

An agent must start once before another client can find and message it.

Use Node 22 or another supported Node.js LTS release. A minimal container image must include CA certificates for an HTTPS backend.