Types Reference - ElizaOS Documentation

Overview

This page documents the core TypeScript types and interfaces used throughout elizaOS. For usage examples, see the relevant feature documentation.

All types are exported from @elizaos/core. Import what you need:

import { Memory, Action, State, UUID } from '@elizaos/core';

Streaming Types

IStreamExtractor

Interface for extracting content from LLM response streams:

interface IStreamExtractor {
  // True when stream processing is complete
  readonly done: boolean;

  // Process a chunk and return streamable text
  push(chunk: string): string;
}

Built-in Extractors:

Extractor	Use Case
`PassthroughExtractor`	Stream everything as-is
`XmlTagExtractor`	Extract content from XML tags
`ResponseStreamExtractor`	Action-aware extraction

Example:

import { XmlTagExtractor } from '@elizaos/core';

const extractor = new XmlTagExtractor('response');
const streamable = extractor.push('<response>Hello');
// streamable = 'Hello'

Task System

TaskWorker

Interface for background task handlers:

interface TaskWorker {
  // Task type identifier
  name: string;

  // Execution logic
  execute(
    runtime: IAgentRuntime,
    options: Record<string, unknown>,
    task: Task
  ): Promise<void>;

  // Optional validation before execution
  validate?(
    runtime: IAgentRuntime,
    message: Memory,
    state?: State
  ): Promise<boolean>;
}

Task

interface Task {
  id: UUID;
  name: string;
  description?: string;
  roomId?: UUID;
  worldId?: UUID;
  entityId?: UUID;
  tags?: string[];
  updatedAt?: number;
  metadata?: TaskMetadata;
}

TaskMetadata

interface TaskMetadata {
  // Recurring task interval in milliseconds
  updateInterval?: number;

  // UI configuration options
  options?: Record<string, unknown>;
}

Example - Recurring Task:

const cleanupWorker: TaskWorker = {
  name: 'CLEANUP_OLD_MESSAGES',

  async execute(runtime, options, task) {
    const threshold = Date.now() - (24 * 60 * 60 * 1000);
    await runtime.deleteOldMessages(threshold);
  }
};

// Register worker
runtime.registerTaskWorker(cleanupWorker);

// Create recurring task (runs every hour)
await runtime.createTask({
  name: 'CLEANUP_OLD_MESSAGES',
  metadata: { updateInterval: 3600000 }
});

State & Context

State

interface State {
  // General state variables
  values: Record<string, unknown>;

  // Structured cache for common properties
  data: StateData;

  // Text summary of context
  text: string;

  // Dynamic properties
  [key: string]: unknown;
}

StateData

Typed cache for frequently accessed data:

interface StateData {
  room?: Room;
  world?: World;
  entity?: Entity;
  providers?: Record<string, ProviderResult>;
  actionPlan?: ActionPlan;
  actionResults?: ActionResult[];
}

ActionPlan

For multi-step action execution:

interface ActionPlan {
  thought: string;
  totalSteps: number;
  currentStep: number;
  steps: ActionPlanStep[];
}

interface ActionPlanStep {
  action: string;
  status: 'pending' | 'completed' | 'failed';
  error?: string;
  result?: ActionResult;
}

Example - Multi-step Action:

// The runtime creates action plans automatically
const state = await runtime.composeState(message);

if (state.data.actionPlan) {
  console.log(`Step ${state.data.actionPlan.currentStep} of ${state.data.actionPlan.totalSteps}`);
  console.log(`Current action: ${state.data.actionPlan.steps[0].action}`);
}

Messaging Types

ControlMessage

Backend-to-frontend control messages:

interface ControlMessage {
  type: 'control';
  payload: {
    action: 'disable_input' | 'enable_input';
    target?: string;
    [key: string]: unknown;
  };
  roomId: UUID;
}

Use Case: Disable user input while agent is processing:

// Emit control message to disable input
await runtime.emit(EventType.CONTROL_MESSAGE, {
  type: 'control',
  payload: {
    action: 'disable_input',
  },
  roomId: currentRoomId
});

// ... do work ...

// Re-enable input
await runtime.emit(EventType.CONTROL_MESSAGE, {
  type: 'control',
  payload: {
    action: 'enable_input'
  },
  roomId: currentRoomId
});

MessageStreamChunkPayload

Streaming response chunk data:

interface MessageStreamChunkPayload {
  messageId: UUID;
  chunk: string;
  index: number;
  channelId: string;
  agentId: UUID;
}

TargetInfo

Message routing target:

interface TargetInfo {
  source: string;           // Platform (discord, telegram, etc.)
  roomId: UUID;
  channelId?: string;
  serverId?: string;
  entityId?: UUID;
  threadId?: string;
}

SOCKET_MESSAGE_TYPE

WebSocket message type enum:

enum SOCKET_MESSAGE_TYPE {
  ROOM_JOINING = 1,
  SEND_MESSAGE = 2,
  MESSAGE = 3,
  ACK = 4,
  THINKING = 5,
  CONTROL = 6,
}

Event Payloads

RunEventPayload

Emitted on run start/end:

interface RunEventPayload extends EventPayload {
  runId: UUID;
  agentId: UUID;
  roomId?: UUID;
  startTime: number;
  endTime?: number;
  status: 'started' | 'completed' | 'failed' | 'timeout';
  error?: string;
}

ActionEventPayload

Emitted on action start/complete:

interface ActionEventPayload extends EventPayload {
  action: string;
  content: Content;
  roomId: UUID;
  messageId: UUID;
  status: 'started' | 'completed' | 'failed';
  result?: ActionResult;
  error?: string;
  duration?: number;
}

EvaluatorEventPayload

interface EvaluatorEventPayload extends EventPayload {
  evaluator: string;
  roomId: UUID;
  messageId: UUID;
  status: 'started' | 'completed' | 'failed';
  result?: unknown;
  duration?: number;
}

ModelEventPayload

Emitted on model usage:

interface ModelEventPayload extends EventPayload {
  modelType: ModelTypeName;
  provider: string;
  model: string;
  tokens?: TokenUsage;
  duration?: number;
  cached?: boolean;
}

EmbeddingGenerationPayload

interface EmbeddingGenerationPayload extends EventPayload {
  memoryId: UUID;
  priority: 'high' | 'normal' | 'low';
  status: 'requested' | 'completed' | 'failed';
  error?: string;
}

Database Types

Log & LogBody

interface Log {
  id: UUID;
  agentId: UUID;
  roomId?: UUID;
  entityId?: UUID;
  type: 'action' | 'evaluator' | 'model' | 'embedding';
  body: LogBody;
  createdAt: number;
}

// Discriminated union for log body types
type LogBody = ActionLogBody | EvaluatorLogBody | ModelLogBody | EmbeddingLogBody;

interface ActionLogBody {
  type: 'action';
  action: string;
  input: Content;
  output?: ActionResult;
  duration: number;
  success: boolean;
  error?: string;
}

interface ModelLogBody {
  type: 'model';
  modelType: ModelTypeName;
  provider: string;
  model: string;
  tokens: TokenUsage;
  duration: number;
  cached: boolean;
}

AgentRunSummary

Analytics for agent runs:

interface AgentRunSummary {
  runId: UUID;
  agentId: UUID;
  roomId?: UUID;
  startTime: number;
  endTime: number;
  status: RunStatus;
  actionsExecuted: number;
  messagesProcessed: number;
  tokensUsed: TokenUsage;
  errors: string[];
}

type RunStatus = 'completed' | 'failed' | 'timeout' | 'cancelled';

Memory Options

interface MemoryRetrievalOptions {
  roomId?: UUID;
  entityId?: UUID;
  limit?: number;
  before?: number;
  after?: number;
  types?: MemoryType[];
}

interface MemorySearchOptions extends MemoryRetrievalOptions {
  query: string;
  threshold?: number;  // Similarity threshold (0-1)
  embedding?: number[];
}

interface EmbeddingSearchResult {
  memory: Memory;
  similarity: number;
}

Vector Dimensions

const VECTOR_DIMS = {
  SMALL: 384,    // MiniLM
  MEDIUM: 512,
  LARGE: 768,    // BERT-base
  XL: 1024,
  XXL: 1536,     // OpenAI ada-002
  XXXL: 3072,    // OpenAI text-embedding-3-large
} as const;

TEE Types

TEEMode

Trusted Execution Environment modes:

enum TEEMode {
  OFF = 'OFF',               // No TEE
  LOCAL = 'LOCAL',           // Local simulation
  DOCKER = 'DOCKER',         // Docker-based TEE
  PRODUCTION = 'PRODUCTION', // Real hardware TEE
}

TeeAgent

TEE agent registration:

interface TeeAgent {
  id: string;
  agentId: string;
  agentName: string;
  createdAt: number;
  publicKey: string;
  attestation: string;  // Attestation document as string
}

RemoteAttestationQuote

interface RemoteAttestationQuote {
  quote: string;
  timestamp: number;
  mrEnclave?: string;
  mrSigner?: string;
}

TeePluginConfig

interface TeePluginConfig {
  mode: TEEMode;
  vendor?: string;
  vendorConfig?: Record<string, unknown>;
}

ElizaOS Orchestrator

IElizaOS

Multi-agent orchestrator interface:

interface IElizaOS {
  // Handle single message (sync or async mode)
  handleMessage(
    agentId: UUID | IAgentRuntime,
    message: Message,
    options?: HandleMessageOptions
  ): Promise<HandleMessageResult>;

  // Handle messages to multiple agents
  handleMessages(
    messages: Array<{ agentId: UUID; message: Message }>
  ): Promise<HandleMessageResult[]>;

  // Get agent runtime by ID
  getAgent(agentId: UUID): IAgentRuntime | undefined;

  // Get all agents
  getAgents(): Map<UUID, IAgentRuntime>;
}

HandleMessageOptions

interface HandleMessageOptions {
  // Callbacks for async mode
  onResponse?: (content: Content) => Promise<void>;
  onStreamChunk?: (chunk: string, messageId: UUID) => Promise<void>;
  onError?: (error: Error) => Promise<void>;
  onComplete?: () => Promise<void>;

  // Processing options
  skipEvaluators?: boolean;
  skipActions?: boolean;
}

HandleMessageResult

interface HandleMessageResult {
  messageId: UUID;
  userMessage: Memory;
  processing?: {
    text: string;
    actions?: ActionResult[];
    evaluations?: unknown[];
  };
  error?: Error;
}

HealthStatus

interface HealthStatus {
  alive: boolean;
  responsive: boolean;
  memoryUsage?: number;
  uptime?: number;
  lastActivity?: number;
}

Model Types

TokenUsage

interface TokenUsage {
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
  cachedTokens?: number;
}

TextStreamResult

interface TextStreamResult {
  text: string;
  usage?: TokenUsage;

  // Async iterator for streaming
  [Symbol.asyncIterator](): AsyncIterator<TextStreamChunk>;
}

interface TextStreamChunk {
  text: string;
  isFirst?: boolean;
  isLast?: boolean;
}

Model Settings

const MODEL_SETTINGS = {
  TEXT_SMALL: {
    maxTokens: 4096,
    temperature: 0.7,
  },
  TEXT_LARGE: {
    maxTokens: 8192,
    temperature: 0.7,
  },
  TEXT_REASONING: {
    maxTokens: 16384,
    temperature: 0.3,
  },
  // ...
} as const;

isStreamableModelType

Type guard for streaming-capable models:

function isStreamableModelType(type: ModelTypeName): boolean;
// Returns true for: TEXT_SMALL, TEXT_LARGE, TEXT_REASONING_*

Core Runtime

Runtime interface and lifecycle

Events

Event system and payloads

Services

Service types and patterns

Plugin Reference

Plugin interface definitions

Documentation Index

​Overview

​Streaming Types

​IStreamExtractor

​Task System

​TaskWorker

​Task

​TaskMetadata

​State & Context

​State

​StateData

​ActionPlan

​Messaging Types

​ControlMessage

​MessageStreamChunkPayload

​TargetInfo

​SOCKET_MESSAGE_TYPE

​Event Payloads

​RunEventPayload

​ActionEventPayload

​EvaluatorEventPayload

​ModelEventPayload

​EmbeddingGenerationPayload

​Database Types

​Log & LogBody

​AgentRunSummary

​Memory Options

​Vector Dimensions

​TEE Types

​TEEMode

​TeeAgent

​RemoteAttestationQuote

​TeePluginConfig

​ElizaOS Orchestrator

​IElizaOS

​HandleMessageOptions

​HandleMessageResult

​HealthStatus

​Model Types

​TokenUsage

​TextStreamResult

​Model Settings

​isStreamableModelType

​See Also

Core Runtime

Events

Services

Plugin Reference

Overview

Streaming Types

IStreamExtractor

Task System

TaskWorker

Task

TaskMetadata

State & Context

State

StateData

ActionPlan

Messaging Types

ControlMessage

MessageStreamChunkPayload

TargetInfo

SOCKET_MESSAGE_TYPE

Event Payloads

RunEventPayload

ActionEventPayload

EvaluatorEventPayload

ModelEventPayload

EmbeddingGenerationPayload

Database Types

Log & LogBody

AgentRunSummary

Memory Options

Vector Dimensions

TEE Types

TEEMode

TeeAgent

RemoteAttestationQuote

TeePluginConfig

ElizaOS Orchestrator

IElizaOS

HandleMessageOptions

HandleMessageResult

HealthStatus

Model Types

TokenUsage

TextStreamResult

Model Settings

isStreamableModelType

See Also