Skip to main content

​
What is AgentRuntime?

The AgentRuntime is the central orchestrator that manages agent lifecycle, processes messages, and coordinates all system components.

​
Key Responsibilities

​
1. Action Processing

async processActions(message: Memory, responses: Memory[], state?: State): Promise<void> {
  // Select and execute actions based on context
  const actions = await this.selectActions(message, state);
  
  for (const action of actions) {
    await action.handler(this, message, state);
  }
  
  // Run evaluators on results
  await this.evaluate(message, state);
}

​
2. State Composition

The runtime builds context by aggregating data from all providers: 
async composeState(message: Memory): Promise<State> {
  const state = {};
  
  for (const provider of this.providers) {
    const data = await provider.get(this, message, state);
    Object.assign(state, data);
  }
  
  return state;
}

​
3. Plugin Management

async registerPlugin(plugin: Plugin) {
  // Register components
  plugin.actions?.forEach(a => this.registerAction(a));
  plugin.providers?.forEach(p => this.registerProvider(p));
  plugin.evaluators?.forEach(e => this.registerEvaluator(e));
  plugin.services?.forEach(s => this.registerService(s));
  
  // Initialize plugin
  await plugin.init?.(this.config, this);
}

​
Runtime Interface

interface IAgentRuntime extends IDatabaseAdapter {
  // Core properties
  agentId: UUID;
  character: Character;
  providers: Provider[];
  actions: Action[];
  evaluators: Evaluator[];
  services: Service[];
  
  // Action processing
  processActions(message: Memory, responses: Memory[], state?: State): Promise<void>;
  composeState(message: Memory, state?: State): Promise<State>;
  evaluate(message: Memory, state?: State): Promise<void>;
  
  // Component registration
  registerAction(action: Action): void;
  registerProvider(provider: Provider): void;
  registerEvaluator(evaluator: Evaluator): void;
  registerService(service: Service): void;
  
  // Service management
  getService<T>(name: ServiceType): T;
  stop(): Promise<void>;
  
  // Model management
  useModel<T extends ModelTypeName>(modelType: T, params: ModelParamsMap[T], provider?: string): Promise<ModelResultMap[T]>;
  registerModel(modelType: ModelTypeName, handler: ModelHandler, provider?: string, priority?: number): void;
  getModel(modelType: ModelTypeName, provider?: string): ModelHandler | undefined;
  
  // Event system
  emit(eventType: EventType, data: any): Promise<void>;
  on(eventType: EventType, handler: EventHandler): void;
}

​
Lifecycle

​
Model Management

The runtime manages AI model selection through a priority system: 
// Plugins register model handlers
runtime.registerModel(
  ModelType.TEXT_LARGE,
  async (runtime, params) => {
    // Call OpenAI API, Anthropic, etc.
    return generatedText;
  },
  'openai',  // provider name
  100        // priority
);

// Use models with type safety
const result = await runtime.useModel(
  ModelType.TEXT_LARGE,
  {
    prompt: "Generate a response",
    temperature: 0.7
  }
);

// Get embeddings
const embedding = await runtime.useModel(
  ModelType.TEXT_EMBEDDING,
  { input: "Text to embed" }
);

​
Memory Management

// Store memories
await runtime.databaseAdapter.createMemory({
  type: MemoryType.MESSAGE,
  content: { text: "User message" },
  roomId: message.roomId
});

// Search memories
const memories = await runtime.databaseAdapter.searchMemories({
  query: "previous conversation",
  limit: 10
});

​
Best Practices

  • Initialize plugins in dependency order
  • Start services after all plugins loaded
  • Clean up resources on shutdown
  • Handle errors gracefully
  • Use appropriate model sizes

​
Next Steps

Services

Learn about background services