Structure

File structure

Each app consists of the following files:

app-project/              # Optional middleware files
├── src/
│   └── index.ts          # Entry point for your agent.
│   └── prompt.ts         # Prompt for your agent.
├── tsconfig.json
├── package.json
└── .env                  # Environment variables

Runner

This is the main function that runs the listener.

import {
  run,
  XMTPContext,
} from "@xmtp/message-kit";
 
run(
  async (context: XMTPContext) => {
    // your logic here
  },
  { skills,
    /*optional parameters*/
   },
);

Optional parameters

• privateKey: the private key of the agent wallet, like any normal wallet private key.
• experimental: experimental features like logging all group messages. Default is false.
• attachments: to receive attachments. Default is false.
• gptModel: model to be used. Default is gpt-4o.
• client: Optional parameters to pass to the XMTP client.
• skills: Custom skills to be used. Default is to create the skills in the src/skills.ts file.
• hideInitLogMessage: hide the init log message with messagekit logo and stuff
• memberChange: if true, member changes will be enabled, like adding members to the group

XMTPContext

XMTPContext bridges the skills to the XMTP protocol. It's aware of conversations, groups and users.

import { XMTPContext } from "@xmtp/message-kit";
 
run(async (context: XMTPContext) => {
  const {
    message,
    group,
    conversation,
    client,
    version,
    v2client,
    members,
    admins,
    runConfig,
    superAdmins,
  } = context;
});

Context properties

• message: the message object
• group: the group object
• conversation: the conversation object
• client: the client object
• version: the version of the client
• v2client: the v2 client object
• members: the members of the group
• admins: the admins of the group
• superAdmins: the super admins of the group
• runConfig: the config of the Runner
• sender: the sender of the message

Clients

Use this instead of XMTP sdks for compatibility with MessageKit

import { V2Client, V3Client } from "@xmtp/message-kit";

You can export other clients on run time by importing the xmtpClient function.

import { xmtpClient } from "@xmtp/message-kit";
 
const { v2client: newClient } = await xmtpClient({
  {
    privateKey: /*Your private key*/,
    /*optional parameters*/
  },
);

This is used in the Cron middleware to send updates to the users.

Manual Installation

You can also install the package manually using your preferred package manager.

bun i @xmtp/message-kit