packages/typescript/README.md
The @elizaos/core package provides a robust foundation for building AI agents with dynamic interaction capabilities. It enables agents to manage entities, memories, and context, and to interact with external systems, going beyond simple message responses to handle complex scenarios and execute tasks effectively.
Add @elizaos/core to your agent/package.json dependencies:
{
"dependencies": {
"@elizaos/core": "workspace:*"
}
}
Navigate to your agent/ directory.
Install dependencies:
bun install
Build your project:
bun run build
The @elizaos/core package features a dual build system that provides optimized builds for both Node.js and browser environments:
The correct build is automatically selected based on your environment through package.json conditional exports. For browser usage, ensure you have the necessary polyfills installed:
npm install buffer crypto-browserify stream-browserify events
The dual build system uses conditional exports in package.json to automatically select the appropriate build based on the runtime environment.
The following environment variables are used by @elizaos/core. Configure them in a .env file at your project root.
LOG_LEVEL: Logging verbosity (e.g., 'debug', 'info', 'error').LOG_DIAGNOSTIC: Enable/disable diagnostic logging (true/false).LOG_JSON_FORMAT: Output logs in JSON format (true/false).DEFAULT_LOG_LEVEL: Default log level if not in debug mode.SECRET_SALT: Secret salt for encryption purposes.ALLOW_NO_DATABASE: Allow running without a persistent database adapter. When true, AgentRuntime.initialize() will fall back to an in-memory adapter (useful for benchmarks/tests).USE_MULTI_STEP: Enable the iterative multi-step workflow (true/false). When enabled, the runtime may run multiple provider/action steps before producing a final response.MAX_MULTISTEP_ITERATIONS: Maximum number of iterations for multi-step mode (default: 6).SENTRY_DSN: Sentry DSN for error reporting.SENTRY_ENVIRONMENT: Sentry deployment environment (e.g., 'production', 'staging').SENTRY_TRACES_SAMPLE_RATE: Sentry performance tracing sample rate (0.0 - 1.0).SENTRY_SEND_DEFAULT_PII: Send Personally Identifiable Information to Sentry (true/false).LOG_FILE: When set to true/1 or a path, enables file logging: output.log, prompts.log, and chat.log (in cwd or at the given path). Why: Lets you inspect full prompts and chat flow without scraping console; ANSI is stripped so files stay grep-friendly.BOOTSTRAP_KEEP_RESP: When true, the message service does not discard a response when a newer message is being processed (avoids "stale reply" race). Why: Some deployments want to keep or display every response; this is the config equivalent of passing keepExistingResponses: true in options.SHOULD_RESPOND_MODEL: Which model size to use for the "should I respond?" decision (small or large). Defaults from runtime settings if not set in options.DISABLE_MEMORY_CREATION / ALLOW_MEMORY_SOURCE_IDS: Bootstrap-related; see plugin docs. Shown in the basic-capabilities banner when set.Example .env:
LOG_LEVEL=debug
LOG_DIAGNOSTIC=true
LOG_JSON_FORMAT=false
DEFAULT_LOG_LEVEL=info
SECRET_SALT=yourSecretSaltHere
ALLOW_NO_DATABASE=true
USE_MULTI_STEP=false
MAX_MULTISTEP_ITERATIONS=6
SENTRY_DSN=yourSentryDsnHere
SENTRY_ENVIRONMENT=development
SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_SEND_DEFAULT_PII=true
Note: Add your .env file to .gitignore to protect sensitive information.
Key behaviors and APIs are documented with their reasons so future changes stay consistent with intent:
When adding or changing behavior, update these docs so the WHY stays accurate.
@elizaos/core now exports a small config-loading helper layer for the repeated setup work that many plugins need:
resolveSettingRaw()collectSettings()getStringSetting()getBooleanSetting()getNumberSetting()getEnumSetting()getCsvSetting()formatConfigErrors()loadPluginConfig()These helpers live in src/utils/plugin-config.ts and are re-exported from @elizaos/core.
Why this exists: many plugins need the same boring plumbing:
runtime.getSetting(key)process.envPutting that plumbing in core reduces copy-paste drift without forcing all plugins into one config framework.
What it intentionally does not do yet:
Why those are excluded: those behaviors vary too much by plugin, so lifting them into core too early would create a helper that is harder to reason about than the duplication it replaces.
Example:
import {
collectSettings,
loadPluginConfig,
type SettingSourceOptions,
} from "@elizaos/core";
import { z } from "zod";
const schema = z.object({
EXAMPLE_ENABLED: z.boolean().default(false),
EXAMPLE_TIMEOUT_MS: z.coerce.number().min(0).default(1000),
});
const sourceOptions: SettingSourceOptions = {
runtime,
envFallback: true,
};
const raw = collectSettings(
["EXAMPLE_ENABLED", "EXAMPLE_TIMEOUT_MS"],
sourceOptions,
);
const config = loadPluginConfig({
schema,
raw,
scope: "Example",
});
Why the API is split into collectSettings() and loadPluginConfig(): callers can still override or derive a few fields locally before validation, while the shared precedence and error formatting stay centralized.
Benchmarks and harnesses can attach metadata to inbound messages:
message.metadata.trajectoryStepId: when present, provider access + model calls are captured for that step.message.metadata.benchmarkContext: when present, the CONTEXT_BENCH provider sets state.values.benchmark_has_context=true, and the message loop forces action-based execution (so the full Provider → Model → Action → Evaluator loop is exercised).The canonical message loop expects model outputs in the <response>...</response> XML format (with <actions>, <providers>, and <text> fields).
Some deterministic/offline backends may return plain text instead. In that case, the runtime will treat the raw output as a simple REPLY so the system remains usable even when strict XML formatting is unavailable.
The core can pass prompt segments to model providers so they can use prompt-caching APIs when supported. Each segment has content (string) and stable (boolean). Stable means the content is the same across calls for the same schema/character (e.g. instructions, format, examples); unstable means it changes every call (e.g. state, validation codes).
Why this exists: Repeated calls (e.g. message handling, batched evaluators) often send the same instructions and format while only the context/state changes. Provider caching (Anthropic ephemeral cache, OpenAI/Gemini prefix cache) can reuse tokens for the stable prefix, reducing cost and latency. The core describes which parts are stable so providers can opt in without parsing the prompt.
promptSegments is set on generation params, prompt MUST equal promptSegments.map(s => s.content).join(""). Why: Providers that ignore segments still get correct behavior by using prompt; those that use segments must send the same total text so model behavior is unchanged.cache_control: { type: "ephemeral" } on stable blocks so the API can cache those blocks. OpenAI and Gemini use prefix ordering: when segments are present, the prompt sent to the API is built with stable segments first, then unstable. Why: OpenAI and Gemini cache by prefix (e.g. OpenAI ≥1024 tokens); putting stable content first maximizes cache hits.Pitfalls for operators:
Pitfalls for implementers:
{ content, stable } objects. Why: Params may be passed to multiple handlers or stored; mutation can cause cross-request bugs.prompt === promptSegments.map(s => s.content).join(""). Why: Wrong order breaks the invariant and can send the wrong prompt to the model.params.prompt or the stable-first concatenation).stable: true if it is identical across calls for the same schema/character. Why: Content that includes per-call UUIDs or changing state will never cache; mislabeling it as stable wastes cache capacity and can confuse operators.For more detail, implementer pitfalls, and rollback, see docs/PROMPT_CACHE_HINTS.md.
@elizaos/core is built around a few key concepts that work together within the AgentRuntime.
@elizaos/core now includes a unified prompt batching subsystem on runtime.promptBatcher.
Why this exists:
What it does:
askOnce() batches startup questions into a single post-init drain when possible. Returns a promise of the extracted fields (unwrapped). Why: callers get a thenable so they can await or .then() without a callback.onDrain(id, opts) registers a section that runs on the next drain for that affinity and returns a promise that resolves with { fields, meta } (or null if the section ID was already registered). Why: evaluators can use linear await + if (result) { ... } instead of a large onResult callback; same batching benefits. You can still pass optional onResult for fire-and-forget or recurring use (e.g. logging).think() is used by autonomy: when enableAutonomy is true, the autonomy service registers one recurring section; a BATCHER_DRAIN task in the task system drives when that affinity drains (task system owns WHEN, batcher owns HOW). Why: one register for "what to ask" and the same orchestration path as evaluators and startup, with the same cache and packing benefits. Autonomy keeps using onResult because it is fire-and-forget per drain.askNow() supports blocking audits without creating a second subsystem. Returns a promise of the fields (unwrapped). Why: same thenable style as askOnce; fallback is required so the caller always gets an object.Result shape and errors:
addSection / onDrain) resolve with BatcherResult<T> | null: { fields: T, meta: DrainMeta }. Why: callers get both the extracted data and drain metadata (e.g. meta.fallbackUsed, meta.durationMs) in one object; null means duplicate section ID so the caller can branch..catch() or try/catch for real failures; fallback-used still resolves (with meta.fallbackUsed: true) so "soft" failure is not an exception.onDrain<T>(...): pass a type param so result.fields is typed (e.g. onDrain<ReflectionFields>(...)). Why: avoids casting at call sites; the runtime still returns Record<string, unknown> from the model—the generic is for developer convenience.Important behavior:
onDrain (or addSection) resolves once—on the first delivery for that registration. Why: per-drain sections run on every drain, but the thenable is for "give me the result of this registration"; subsequent drains do not resolve the same promise again. For recurring delivery (e.g. every drain), use the optional onResult callback.providers, contextBuilder, and contextResolvers can be mixed.Relevant runtime knobs:
PROMPT_BATCH_SIZEPROMPT_MAX_DRAIN_INTERVAL_MSPROMPT_MAX_SECTIONS_PER_CALLPROMPT_PACKING_DENSITYPROMPT_MAX_TOKENS_PER_CALLPROMPT_MAX_PARALLEL_CALLSPROMPT_MODEL_SEPARATIONFor the deeper design rationale and rollout details, see DESIGN.md, ROADMAP.md, and CHANGELOG.md in this package.
The task system is the single place for when scheduled work runs. Only tasks with tag queue are polled by the scheduler (TaskService); other tasks (e.g. approval, follow-up) are stored and executed only when explicitly triggered (e.g. choice action, or executeTaskById).
Why one scheduler:
getTaskStatus, nextRunAt, lastError). Retry and backoff (exponential backoff, auto-pause after maxFailures) live in one place so we avoid infinite retry storms.Why queue + repeat:
tags: ["queue"] are fetched every tick. Non-repeat tasks run when now >= dueAt (or metadata.scheduledAt) then are deleted; repeat tasks use updateInterval/baseInterval and metadata.updatedAt as last-run time. Why: One-shot "run at time X" (e.g. follow-up) uses dueAt; interval-based scheduling covers batcher drains and recurring use.Cross-runtime scheduling (three modes):
setInterval per TaskService; each runtime fetches its own queue tasks every tick. Why: Zero config for single-process apps.startTaskScheduler(adapter); one shared timer runs, one batched getTasks(agentIds) per tick for all registered runtimes, then tasks are dispatched to each runtime’s runTick(tasks). Why: Multi-agent daemons avoid N DB queries per second.{ serverless: true }; no timer. Host calls taskService.runDueTasks() from cron or on each request to run due queue tasks once. Why: No long-lived process; host controls when tasks run.Public API (TaskService): executeTaskById, pauseTask, resumeTask, getTaskStatus, markDirty, runDueTasks() (serverless). Why: Operators and UIs can run, pause, resume, and inspect tasks without touching the DB directly.
See docs/TASK_SCHEDULER.md for full architecture, WHYs, and daemon/serverless usage. See DESIGN.md (§ Task system upgrades and batcher-on-tasks) for full rationale and consumer fit.
The autonomy service lets the agent "think" and act on a schedule without user messages. It uses the prompt batcher with the task system for scheduling: when enableAutonomy is true, a recurring section is registered with think("autonomy", ...). A BATCHER_DRAIN task for the autonomy affinity determines when the section drains; results are delivered to onResult, which runs the same post-LLM steps as the message pipeline (actions, memory, evaluators) via an execution facade.
Why batcher-only:
The AgentRuntime is the heart of the system. It manages the agent's lifecycle, loads plugins, orchestrates interactions, and provides a central point for actions, providers, and evaluators to operate. It's typically initialized with a set of plugins, including the corePlugin which provides foundational capabilities.
Actions define specific tasks or capabilities the agent can perform. Each action typically includes:
name.description explaining its purpose and when it should be triggered.validate function to determine if the action is applicable in a given context.handler function that executes the action's logic.Actions enable the agent to respond intelligently and perform operations based on user input or internal triggers.
Providers are responsible for supplying data and context to the AgentRuntime and its components. They can:
This allows the agent to operate with up-to-date and relevant information.
Evaluators analyze conversation data and other inputs to extract meaningful information, build the agent's memory, and maintain contextual awareness. They help the agent:
The runtime talks to persistence through the IDatabaseAdapter interface. Adapters (e.g. plugin-sql, plugin-localdb, InMemory) implement this contract so the same runtime code works with different backends.
Why mutation methods return Promise<boolean>: Methods such as updateAgents, deleteAgents, and deleteParticipants return a boolean so callers can tell success from failure. That supports error handling, retries, and UX (e.g. "Agent removed" vs "Failed to remove"). All adapters use this convention for consistency. See packages/typescript/src/types/database.ts for full JSDoc and design notes.
corePluginThe corePlugin bundles essential actions, providers, and evaluators from @elizaos/core. To use it, add it to the AgentRuntime during initialization:
import { AgentRuntime, corePlugin } from "@elizaos/core";
const agentRuntime = new AgentRuntime({
plugins: [
corePlugin,
// You can add other custom or third-party plugins here
],
// Other AgentRuntime configurations can be specified here
});
// After initialization, agentRuntime is ready to be used.
// You should see console messages like "✓ Registering action: <plugin actions>"
// indicating successful plugin registration.
While corePlugin provides many actions, you might need to define custom actions for specific agent behaviors. Here's a conceptual outline:
// myCustomAction.ts
// (This is a simplified conceptual example)
export const myCustomAction = {
name: "customGreet",
description: "Greets a user in a special way.",
validate: async ({ context }) => {
// Logic to determine if this action should run
// e.g., return context.message.text.includes('special hello');
return true; // Placeholder
},
handler: async ({ runtime, context }) => {
// Logic to execute the action
// e.g., runtime.sendMessage(context.roomId, "A very special hello to you!");
console.log("Custom Greet action executed!");
return { success: true, message: "Custom greeting sent." };
},
};
// Then, this action would be registered with the AgentRuntime, typically via a custom plugin.
For detailed instructions on creating and registering plugins and actions, refer to the specific documentation or examples within the codebase.
The @elizaos/core package uses vitest for testing.
Prerequisites:
bun is installed (npm install -g bun)..env (as described in Configuration) are generally not required for most core tests but might be for specific integration tests if any.Setup:
packages/typescript directory: cd packages/typescriptbun installExecute Tests:
npx vitest
Test results will be displayed in the terminal.
The following improvements and features are planned for @elizaos/core:
sendMessageAction).ensureConnection approach (Context: Sending messages to room participants).AgentRuntime not responding to triggers:
validate functions or handlers. Trigger conditions might not be met.validate functions correctly identify trigger conditions. Ensure handler functions execute as intended. Check console logs for errors during validation/handling.Provider data is outdated/incorrect:
Evaluator fails to maintain context:
AgentRuntime and is updated with the latest configuration for accurate context.Q: How do I define and use a new Action?
name, description, validate, and handler functions. Integrate it into AgentRuntime usually by creating a plugin that registers the action. Ensure the action's name and description clearly align with its task for proper triggering.Q: My action is registered, but the agent is not calling it.
name and description for clarity and relevance to the triggering conditions. Verify that the validate function correctly returns true (or a truthy value indicating applicability) under the desired conditions. Inspect logs for any errors or warnings related to your action.Q: Can Providers access external API data?
Q: How do I extend the agent's evaluation capabilities?
AgentRuntime (typically via a plugin). These can be tailored to extract specific information, enhancing the agent's memory and contextual understanding.Q: How can I create a mock environment for testing?
MockDatabaseAdapter if it's part of core utilities) that simulate interactions (like database connections) without actual external dependencies, facilitating controlled testing.LOG_LEVEL=debug) for detailed error messages and execution flow during action validation and handler execution.AgentRuntime is loaded with the correct configurations and plugins.