Types Reference

Complete TypeScript types and interfaces reference for elizaOS

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_*

---

See Also

Core Runtime

Runtime interface and lifecycle

Events

Event system and payloads

Services

Service types and patterns

Plugin Reference

Plugin interface definitions