Skip to main content

AgentOS

AgentOS documentation: getting started guides, full API reference, runtime recipes, extension catalog, and benchmark results for the open-source TypeScript AI agent runtime.

GitHub stars: 677npm versionTypeScriptLicense
Wilds AI
Join the Wilds AI Discord
Real-time community for AgentOS and Paracosm support and developer onboarding.
Contact the AgentOS team
Partnerships, investment, press, security, hiring — written inquiries to team@frame.dev.

Runtime agent spawning

Watch an agent spawn a specialist at runtime

A manager with a researcher and a writer gets a task neither of them covers. It callsspawn_specialist, the LLM judge approves the new agent's spec, and the specialist joins the roster as a delegate_to_<role> tool for the manager's next turn.

Captured from a run of node examples/emergent-hierarchical-spawning.mjs with a security-audit promptView source on GitHub →

How emergent capabilities work →

npm install @framers/agentos

Quick Start

import { agent } from '@framers/agentos';

// Personality is six 0-1 trait values. Each trait above 0.65 or below 0.35
// adds one line of direction to the system prompt; a trait in between, or
// one left out (0.5), adds none.
const tutor = agent({
provider: 'openai',
model: 'gpt-4o',
instructions: 'You are a patient programming tutor.',
personality: {
honesty: 0.85, // direct, transparent, no flattery
emotionality: 0.70, // tone-aware without being clinical
extraversion: 0.50, // in between: adds no line
agreeableness: 0.75, // warm, encouraging
conscientiousness: 0.90, // structured, thorough, follow-through
openness: 0.85, // creative, exploratory framing
},
});

// Each session keeps its own conversation history in process memory
// (bounded to about 120,000 tokens), so two session ids share nothing.
const session = tutor.session('user-42');

// Every send() passes the session's earlier turns to the model.
await session.send('My exam is on distributed systems next Thursday.');
await session.send('I struggle with consensus algorithms.');
const reply = await session.send('What should I focus on this week?');
console.log(reply.text);

// The transcript the session holds, and the tokens it has used.
console.log(session.messages());
const usage = await session.usage();
console.log(`Total tokens: ${usage.totalTokens}`);

System Architecture

Seven cooperating layers. API surface at the top, channels and providers at the floor, cognition and memory in the middle. Click to zoom.

AgentOS layered architecture: 7 cooperating layers from API surface (generateText, streamText, agent, agency, mission) through cognitive substrate (GMI coordinator, PersonaOverlayManager, SentimentTracker, MetapromptExecutor), memory and RAG pipeline (working / episodic / semantic / observational memory, 8 cognitive mechanisms, HyDE, GraphRAG, 7 vector backends), tools and capabilities (ToolOrchestrator, 100+ extension packs, 88 SKILL.md modules, CapabilityDiscovery, ForgeToolMetaTool), guardrails and HITL (GuardrailDispatcher, 4-tier PII redaction, ML classifiers, Grounding Guard, HumanInteract), orchestration (workflow, mission, AgentGraph, CompiledExecutionGraph, CheckpointStore), down to I/O and providers (voice pipeline, channels, media generation, 13 LLM providers, OpenRouter fanout).AgentOS layered architecture: 7 cooperating layers from API surface (generateText, streamText, agent, agency, mission) through cognitive substrate (GMI coordinator, PersonaOverlayManager, SentimentTracker, MetapromptExecutor), memory and RAG pipeline (working / episodic / semantic / observational memory, 8 cognitive mechanisms, HyDE, GraphRAG, 7 vector backends), tools and capabilities (ToolOrchestrator, 100+ extension packs, 88 SKILL.md modules, CapabilityDiscovery, ForgeToolMetaTool), guardrails and HITL (GuardrailDispatcher, 4-tier PII redaction, ML classifiers, Grounding Guard, HumanInteract), orchestration (workflow, mission, AgentGraph, CompiledExecutionGraph, CheckpointStore), down to I/O and providers (voice pipeline, channels, media generation, 13 LLM providers, OpenRouter fanout).

Full architecture guide →

Core Features

Multimodal Provider API

Text, images, video, music, SFX, embeddings, and speech from one API. Cloud and local backends share the same surface, with fallback chains and provider preferences that order, filter or weight them.

Deep Research Agents

mission() compiles a goal into a linear step graph from a plan template (research, Q&A or creative), with anchor nodes for verification and human review spliced into its phases.

Emergent Capabilities

Agents forge new tools at runtime — compose (chain existing tools) or sandbox (generated JavaScript in node:vm or QuickJS, with allowlists; off by default). LLM-as-judge review, tiered promotion, portable YAML export.

Voice & IVR Pipeline

Voice pipeline with VAD, STT, endpoint detection and TTS, and Twilio, Telnyx and Plivo call providers with a media-stream transport for phone calls.

Graph Orchestration

Three authoring APIs — AgentGraph, workflow() DSL, mission() — compile to one IR. judgeNode for evaluation, checkpoints to resume from, streaming events.

Cognitive Memory

Ebbinghaus decay, spreading activation, Baddeley-style working memory, GraphRAG retrieval and consolidation, plus 8 neuroscience-grounded mechanisms that run with a cognitiveMechanisms config and that HEXACO traits modulate.

Streaming Guardrails

Five guardrail packs: PII redaction (regex, NLP, NER and an LLM judge), ML classifiers (ONNX toxic-bert, an LLM judge or keywords), topicality (embedding similarity to allowed and blocked topics), code safety (OWASP-style rules) and grounding (NLI against the retrieved sources).

Evaluation Framework

Test cases scored by built-in or custom scorers and an LLM judge with criteria presets. Two runs compared side by side; reports in JSON, Markdown or HTML.

Capability Discovery

Three tiers held to token budgets: category summaries (200 tokens) → the top 5 matches (800) → full schemas for the top 2 (2,000), plus a discover_capabilities tool for active search.

Provenance & Audit

Signed event ledger (Ed25519 signatures over a SHA-256 hash chain), revision snapshots, tombstones for deletes, an autonomy guard, and Merkle roots anchored outside the database.

Channels & Social

Telegram, Discord, Slack, WhatsApp, Twitter/X, LinkedIn, Bluesky, Mastodon, and custom adapters. Multi-channel routing, social publishing, browser automation, and adapter APIs.

Immutable Agents

Sealed storage policy with the signed ledger, revisions, tombstones and anchors, and a design guide for toolset pinning, secret rotation and forgetting. A sealed agent's changes are tamper-evident.

Video & Audio Generation

generateVideo(), analyzeVideo(), detectScenes(), generateMusic(), generateSFX() APIs. 3 video providers (Runway, Replicate, Fal) + 8 audio providers. Fallback chains and scene detection.

Curated Skills

SKILL.md prompt modules for research, developer tools, communication, productivity, security, media, and creative workflows. Semantic discovery finds the right skill per turn.

Self-Improving Agents

Bounded self-modification: adapt_personality (HEXACO mutation with per-session budgets), manage_skills, create_workflow, self_evaluate. Recorded mutations decay when adapt_personality runs; the live trait keeps its change.