Introduction

In this document, you'll learn about the structure and components of an agent project. We'll cover the following sections:

• Project files: Understand the basic file structure of an agent project.
• Agent: Learn how to set up and run an agent using XMTP's message-kit.
• Context: Learn how to access the context of the agent.
• Groups: Learn how to create and manage groups.
• Skills: Discover how to define the actions your agent can perform.
• Plugins: Learn about plugins that can enhance the capabilities of your agent's skills.
• Vibes: Understand how to define the personality and style of your agent.

Project files

Each agent project consists of the following basic structure:

agent/
├── src/
│   └── index.ts
│   └── skills/
│       └── ...
├── tsconfig.json
├── package.json
└── .env

Agent

This is the main function that runs the listener.

import { agentReply, Context, createAgent } from "@xmtp/message-kit";
 
export const agent = createAgent({
  name: "GPT Bot",
  description: "Use GPT to generate text responses.",
  tag: "@bot",
  onMessage: async (context: Context) => {
    await agentReply(context);
  },
}).run();

Config

config: {
  /* Optional properties */
}

• encryptionKey: 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.
• agent: Custom agent 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

Context

The Context object is a core component that provides access to all XMTP messaging functionality. It handles conversations, groups, and messages.

import { Context } from "@xmtp/message-kit";
 
onMessage(async (context: Context) => {
  const {
    message, // Current message details
    client, //  XMTP client
    conversation, // Current conversation
    group, // Group details if in a group chat
  } = context;
 
  // Your message handling logic
});

Properties

Contains information about the current message:

• content: The message content
• sender: Address of message sender
• sent: Timestamp when message was sent
• typeId: Type of message
• client: XMTP client instance
• conversation: Current conversation object with messaging methods

Groups

MessageKit allows agents to interact inside XMTP groups. Make sure you follow the guidelines for building responsible group agents on XMTP.

Tag an agent

When a message includes a tag like @bot, it will be received by your agent.

export const agent: Agent = {
  name: "Web3 Domain Bot",
  tag: "@bot",
  /* Your agent definition */
};

Example:

@bot who owns vitalik.eth

Skills

Skills are the actions that the agent can perform. They are defined in the src/skills/your-skill.ts file.

import { Skill } from "@xmtp/message-kit";
 
export const skills: Skill[] = [
  {
    skill: // name of the skill
    handler: handler(context)
    examples: // examples of the skill
    description: // description of the skill
    params: // params of the skill
  },
];

Learn more about skills in the Skills section.

Plugins

Plugins are the plugins that the Skills can use. They are defined in the plugins/your-plugin.ts file.

import { createClient } from "@redis/client";
import type { RedisClientType } from "@redis/client";
 
export const getRedisClient = async () => {
  const client = createClient({
    url: process.env.REDIS_CONNECTION_STRING,
  });
 
  client.on("error", (err) => {
    console.error("Redis client error:", err);
  });
 
  await client.connect();
  return client as RedisClientType;
};

See Plugins for more information.

Vibes

Vibes are the personalities of the agent. They are defined in the src/vibes/your-vibe.ts file.

import { Vibe } from "@xmtp/message-kit";
 
export const chill: Vibe = {
  vibe: // name of the vibe
  description: // description of the vibe
  tone: // tone of the vibe
  style: // style of the vibe
};

See Vibes for more information.