Message Service

Overview

The DefaultMessageService implements the IMessageService interface and provides the complete message processing pipeline for elizaOS. This is the standard message handler used by the framework and can be replaced with custom implementations.

Key Features

Message validation and memory creation: Stores incoming messages in the memory system
Smart response decision: Uses shouldRespond logic to determine when to reply
Multi-step processing: Supports both single-shot and multi-step reasoning workflows
Action execution: Processes and executes actions based on message context
Attachment processing: Handles images, documents, audio, and video with automatic transcription and description
Pre-evaluator middleware: Security gates for blocking or rewriting messages
Streaming support: Real-time response streaming with voice synthesis

Service Lifecycle

Instantiation

The message service is automatically instantiated by the runtime and registered as the default message handler:

import { DefaultMessageService } from "@elizaos/core";

const messageService = new DefaultMessageService();

Message Flow

Receive Message: Message enters through handleMessage()
Pre-evaluation: Security checks via evaluatePre()
Memory Storage: Message saved to memory system
Response Decision: shouldRespond() determines if agent should reply
Processing Strategy: Single-shot or multi-step based on configuration
Action Execution: Execute actions if needed
Response Generation: Generate and send response
Post-evaluation: Run evaluators on the response

Main Method

handleMessage

Main entry point for message processing.

async handleMessage(
  runtime: IAgentRuntime,
  message: Memory,
  callback?: HandlerCallback,
  options?: MessageProcessingOptions,
): Promise<MessageProcessingResult>

runtime

IAgentRuntime

required

The agent runtime instance

message

Memory

required

The incoming message to process

callback

HandlerCallback

Optional callback for streaming responses and action results

options

MessageProcessingOptions

Optional processing configuration

Show MessageProcessingOptions

maxRetries

number

default:"3"

Maximum number of retry attempts for failed operations

timeoutDuration

number

default:"3600000"

Timeout in milliseconds (default: 1 hour)

useMultiStep

boolean

Enable multi-step reasoning workflow. If not provided, reads from USE_MULTI_STEP setting

maxMultiStepIterations

number

default:"6"

Maximum iterations for multi-step processing

onStreamChunk

(chunk: string, messageId?: string) => Promise<void>

Callback for streaming response chunks in real-time

shouldRespondModel

'small' | 'large'

default:"'small'"

Model size for shouldRespond evaluation. ‘large’ enables better context analysis and planning

result

MessageProcessingResult

The processing result

Show MessageProcessingResult

didRespond

boolean

Whether the agent responded to the message

responseContent

Content | null

The generated response content

responseMessages

Memory[]

Array of response messages created

state

State

The final state after processing

mode

'simple' | 'actions' | 'none'

The processing strategy used

Example Usage

import { DefaultMessageService } from "@elizaos/core";

const messageService = new DefaultMessageService();

// Basic message handling
const result = await messageService.handleMessage(
  runtime,
  incomingMessage,
  async (content) => {
    console.log("Response:", content.text);
  },
  {
    useMultiStep: true,
    maxMultiStepIterations: 5,
  }
);

if (result.didRespond) {
  console.log("Agent responded:", result.responseContent?.text);
}

Streaming Responses

const result = await messageService.handleMessage(
  runtime,
  message,
  undefined,
  {
    onStreamChunk: async (chunk, messageId) => {
      // Stream chunk to client
      process.stdout.write(chunk);
    },
  }
);

Response Decision Logic

shouldRespond

Determines whether the agent should respond to a message using rule-based and LLM evaluation.

shouldRespond(
  runtime: IAgentRuntime,
  message: Memory,
  room?: Room,
  mentionContext?: MentionContext,
): ResponseDecision

runtime

IAgentRuntime

required

The agent runtime instance

message

Memory

required

The message to evaluate

room

Room

The room/channel context

mentionContext

MentionContext

Information about mentions and replies

decision

ResponseDecision

Show ResponseDecision

shouldRespond

boolean

Whether the agent should respond

skipEvaluation

boolean

Whether LLM evaluation was skipped (rule-based decision)

reason

string

Explanation for the decision

Decision Flow

Private Channels: Always respond in DMs, voice DMs, and API channels
Whitelisted Sources: Always respond to sources like client_chat
Platform Mentions: Always respond to @mentions and replies
LLM Evaluation: For all other cases, use LLM to decide

Configuration

// Disable shouldRespond checks (ChatGPT mode)
runtime.setSetting("CHECK_SHOULD_RESPOND", "false");

// Add custom channels that always trigger responses
runtime.setSetting("ALWAYS_RESPOND_CHANNELS", "[FORUM, ANNOUNCEMENT]");

// Add custom sources
runtime.setSetting("ALWAYS_RESPOND_SOURCES", "[webhook, api]");

// Use large model for shouldRespond evaluation
runtime.setSetting("SHOULD_RESPOND_MODEL", "large");

Attachment Processing

processAttachments

Processes message attachments by generating descriptions, transcriptions, and extracting content.

async processAttachments(
  runtime: IAgentRuntime,
  attachments: Media[],
): Promise<Media[]>

runtime

IAgentRuntime

required

The agent runtime instance

attachments

Media[]

required

Array of media attachments to process

processedAttachments

Media[]

Array of processed attachments with descriptions and transcriptions

Supported Types

Images

Generates descriptions using vision models:

Extracts visual content and context
Creates accessible descriptions
Adds title and text fields

Disable with: runtime.setSetting("DISABLE_IMAGE_DESCRIPTION", "true")

Audio

Transcribes audio to text:

Supports remote and local URLs
Uses speech-to-text models
Adds transcript to text field

Video

Transcribes video audio track:

Extracts audio for transcription
Generates text transcript
Preserves video metadata

Documents

Extracts text content:

Supports plain text documents
Extracts file content
Skips binary formats

Example

const message = {
  content: {
    text: "Check out this image",
    attachments: [
      {
        id: "img1",
        url: "https://example.com/photo.jpg",
        contentType: ContentType.IMAGE,
      },
      {
        id: "aud1",
        url: "https://example.com/audio.mp3",
        contentType: ContentType.AUDIO,
      },
    ],
  },
};

const service = new DefaultMessageService();
const processed = await service.processAttachments(
  runtime,
  message.content.attachments
);

// Processed attachments now have descriptions/transcripts
console.log(processed[0].description); // "A sunset over mountains"
console.log(processed[1].text); // "Hello, this is a test recording..."

Processing Strategies

Single-Shot Mode

Direct response generation with optional action execution. Use cases:

Quick responses
Simple queries
Conversational replies

Configuration:

const result = await messageService.handleMessage(
  runtime,
  message,
  callback,
  { useMultiStep: false }
);

Multi-Step Mode

Iterative reasoning with action execution and state management. Use cases:

Complex tasks requiring planning
Multi-action workflows
Tasks needing decision trees

Configuration:

const result = await messageService.handleMessage(
  runtime,
  message,
  callback,
  {
    useMultiStep: true,
    maxMultiStepIterations: 10,
  }
);

Environment variable:

USE_MULTI_STEP=true
MAX_MULTISTEP_ITERATIONS=6

Pre-Evaluator Middleware

Pre-evaluators act as security gates that can block or rewrite messages before processing.

Use Cases

Prompt injection detection: Block malicious inputs
Credential redaction: Remove sensitive information
Content filtering: Block inappropriate content
Message sanitization: Clean and normalize inputs

Example

// Register a pre-evaluator
runtime.registerEvaluator({
  name: "SECURITY_CHECK",
  phase: "pre",
  similes: ["security", "prompt-injection"],
  handler: async (runtime, message) => {
    const text = message.content.text || "";
    
    // Block prompt injection attempts
    if (text.includes("ignore previous instructions")) {
      return {
        blocked: true,
        reason: "Potential prompt injection detected",
      };
    }
    
    // Redact API keys
    if (text.match(/sk-[a-zA-Z0-9]{32}/)) {
      return {
        blocked: false,
        rewrittenText: text.replace(/sk-[a-zA-Z0-9]{32}/g, "[REDACTED]"),
        reason: "API key redacted",
      };
    }
    
    return { blocked: false };
  },
});

Voice Synthesis

The message service includes built-in voice synthesis for audio responses.

Features

First sentence streaming: Sends voice for the first sentence immediately
Voice caching: Caches generated audio to avoid regeneration
Background processing: Voice generation doesn’t block response
Configurable voices: Supports custom voice models and IDs

Configuration

// In character file
{
  "name": "MyAgent",
  "settings": {
    "voice": {
      "model": "en_US-male-medium",
      "voiceId": "custom-voice-id"
    }
  }
}

How It Works

Response text is streamed
When first sentence completes, it’s sent to TTS
Audio is generated and cached
Audio attachment is sent via callback
Remaining text is processed similarly

Events

The message service emits several events during processing:

RUN_STARTED

Emitted when message processing begins.

{
  runtime: IAgentRuntime,
  source: "messageHandler",
  runId: UUID,
  messageId: UUID,
  roomId: UUID,
  entityId: UUID,
  startTime: number,
  status: "started"
}

RUN_ENDED

Emitted when message processing completes.

{
  runtime: IAgentRuntime,
  source: "messageHandler",
  runId: UUID,
  messageId: UUID,
  roomId: UUID,
  entityId: UUID,
  startTime: number,
  endTime: number,
  duration: number,
  status: "completed"
}

RUN_TIMEOUT

Emitted when processing exceeds timeout duration.

{
  runtime: IAgentRuntime,
  source: "messageHandler",
  runId: UUID,
  messageId: UUID,
  roomId: UUID,
  entityId: UUID,
  startTime: number,
  endTime: number,
  duration: number,
  status: "timeout",
  error: "Run exceeded timeout"
}

MESSAGE_SENT

Emitted after response is saved to memory.

{
  runtime: IAgentRuntime,
  message: Memory,
  source: string
}

Advanced Configuration

Bootstrap Settings

// Start with LLM off by default (requires explicit activation)
runtime.setSetting("BOOTSTRAP_DEFLLMOFF", "true");

// Keep ignore responses in race conditions
runtime.setSetting("BOOTSTRAP_KEEP_RESP", "true");

// Disable image descriptions
runtime.setSetting("DISABLE_IMAGE_DESCRIPTION", "true");

Custom Message Service

You can implement a custom message service by implementing the IMessageService interface:

import { IMessageService } from "@elizaos/core";

class CustomMessageService implements IMessageService {
  async handleMessage(
    runtime: IAgentRuntime,
    message: Memory,
    callback?: HandlerCallback,
    options?: MessageProcessingOptions,
  ): Promise<MessageProcessingResult> {
    // Your custom implementation
    return {
      didRespond: true,
      responseContent: { text: "Custom response" },
      responseMessages: [],
      state: {},
      mode: "simple",
    };
  }
}

// Register custom service
runtime.registerService(new CustomMessageService());

Best Practices

Error Handling

Use timeout configuration to prevent hung processes
Implement retry logic for transient failures
Monitor RUN_TIMEOUT events for performance issues

Performance

Enable streaming for better UX in long responses
Use multi-step mode only when needed (adds overhead)
Cache voice synthesis results
Set appropriate timeout values

Security

Always use pre-evaluators for security checks
Redact sensitive information before processing
Validate user roles for privileged operations
Monitor for prompt injection attempts

Memory Management

Clean up old messages periodically
Use appropriate embedding generation priority
Monitor memory growth in long conversations

Troubleshooting

Agent Not Responding

Check shouldRespond configuration
Verify room is not muted
Check if BOOTSTRAP_DEFLLMOFF is enabled
Review logs for pre-evaluator blocks

Timeout Issues

Increase timeoutDuration in options
Monitor RUN_TIMEOUT events
Check for slow model responses
Review multi-step iteration count

Streaming Not Working

Ensure onStreamChunk callback is provided
Verify model supports streaming
Check for XML parsing issues
Review network connectivity

Core API

Services

Plugin System

Types

​Overview

​Key Features

​Service Lifecycle

​Instantiation

​Message Flow

​Main Method

​handleMessage

​Example Usage

​Streaming Responses

​Response Decision Logic

​shouldRespond

​Decision Flow

​Configuration

​Attachment Processing

​processAttachments

​Supported Types

​Example

​Processing Strategies

​Single-Shot Mode

​Multi-Step Mode

​Pre-Evaluator Middleware

​Use Cases

​Example

​Voice Synthesis

​Features

​Configuration

​How It Works

​Events

​RUN_STARTED

​RUN_ENDED

​RUN_TIMEOUT

​MESSAGE_SENT

​Advanced Configuration

​Bootstrap Settings

​Custom Message Service

​Best Practices

​Error Handling

​Performance

​Security

​Memory Management

​Troubleshooting

​Agent Not Responding

​Timeout Issues

​Streaming Not Working

​Related

Build docs developers (and LLMs) love

Overview

Key Features

Service Lifecycle

Instantiation

Message Flow

Main Method

handleMessage

Example Usage

Streaming Responses

Response Decision Logic

shouldRespond

Decision Flow

Configuration

Attachment Processing

processAttachments

Supported Types

Example

Processing Strategies

Single-Shot Mode

Multi-Step Mode

Pre-Evaluator Middleware

Use Cases

Example

Voice Synthesis

Features

Configuration

How It Works

Events

RUN_STARTED

RUN_ENDED

RUN_TIMEOUT

MESSAGE_SENT

Advanced Configuration

Bootstrap Settings

Custom Message Service

Best Practices

Error Handling

Performance

Security

Memory Management

Troubleshooting

Agent Not Responding

Timeout Issues

Streaming Not Working

Related