Runtime

The SDK exports a broad runtime surface, but the pieces follow a consistent shape: providers supply model calls, agents orchestrate runs, registries and managers own definitions plus lifecycle, and stores persist mutable state.

1. Runtime Map

Area	Main exports	Use it when you need...
Providers	`ProviderRegistry`, `LLMProvider` types	A vendor-neutral model boundary
Agents	`ReactiveAgent`, `PipelineAgent`, `RouterAgent`, `SupervisorAgent`	Different execution patterns over the same runtime
Low-level kernel	`query`, `drainQuery`	Direct control over event streaming, verification, sandboxing, and runtime-only features
Lifecycle	`AgentManager`, `RunPersistence`, `EmergencySaveManager`, `PlanManager`	Run orchestration, persistence, and review hooks
Stores	`RunDiskStore`, `DiskTaskStore`, conversation and memory stores	Local durability for runtime data
Session hierarchy	`InMemorySessionStore`, `DiskSessionStore`, handoff, summary, workspace, retention exports	Tenant-scoped project and delegation state
Sandboxing	`LocalSandboxProvider`, `SandboxProviderFactory`	Isolated command execution
Persona and skills	`SkillRegistry`, `assembleSystemPrompt`, `mergePersonas`, `withSessionContext`	Stable prompt composition and reusable instructions
Retrieval	`DefaultKnowledgeBase`, `DefaultRetriever`, `createRAGTool`	Retrieval-augmented context
Plugins and registries	`PluginRegistry`, `ToolRegistry`, `AgentRegistry`, `PluginLifecycleManager`	Extensibility and catalog-style registration
Connectors and MCP	`ConnectorRegistry`, `ConnectorManager`, `MCPClient`, `MCPToolDiscovery`, `MCPConnectorBridge`, `MCPServer`	External system integration and MCP interoperability
Wire bridges	`mapRunToStreamEvent`, A2A helpers	Observability ships from `@namzu/telemetry` as of 0.4.0
Plugin runtime	`PluginLifecycleManager`, `discoverPlugins`, `loadPluginManifest`, `PluginResolver`	Namespaced extensions, hook execution, and plugin-managed MCP tools

2. Agent Families

The public agent classes are distinct runtime shapes rather than separate products:

Agent class	Intended role
`ReactiveAgent`	General-purpose tool-using loop
`PipelineAgent`	Sequential staged execution
`RouterAgent`	Route to a target path or downstream agent based on input
`SupervisorAgent`	Coordinate or delegate across sub-agents

If you are starting fresh, begin with ReactiveAgent unless you already know you need routing or supervision.

3. Provider Boundary

Every provider package plugs into the same LLMProvider contract:

chat(params) returns a normalized completion result.
chatStream(params) yields normalized stream chunks.
listModels() and healthCheck() are optional.

This is why you can swap provider packages without rewriting agent setup code.

Read Provider Operations if you want direct provider-call patterns instead of the agent loop.

4. Persistence and Local State

The SDK exports both in-memory and disk-backed implementations so you can start simple and add durability later:

Surface	Examples
Generic store	`InMemoryStore`
Runs and checkpoints	`RunDiskStore`
Tasks	`InMemoryTaskStore`, `DiskTaskStore`
Conversation state	`InMemoryConversationStore`
Memory	`InMemoryMemoryIndex`, `InMemoryMemoryStore`, `DiskMemoryStore`

5. When to Add Optional Capability Packages

The SDK is intentionally not the only published package in the system:

Add a provider package when you need a real model backend.
Add @namzu/computer-use when your tool registry needs screenshots or desktop input.
Stay on the SDK alone if you are building mocks, tests, or package-level abstractions first.

6. Architecture Deep Dives

If you are implementing against the SDK rather than only consuming the public API, use the architecture set alongside this runtime page:

If you need to understand...	Read
Why each top-level folder exists	Folder Reference
Provider registration and provider creation	Provider Registry
Direct provider calls and preflight methods	Provider Operations
Agent class selection and delegation boundaries	SDK Agents
Personas, skill files, and prompt layering	SDK Prompting
Knowledge-base ingestion and retrieval tools	SDK Retrieval
Project-session-sub-session persistence and archival	SDK Sessions
Required IDs and identity mapping	Runtime Identities
Agent config and runtime limits	Runtime Configuration
`query()` and `drainQuery()` wiring	Low-Level Runtime
Plugin manifests, namespacing, and hook order	Plugins and MCP Servers
The shipped tool set	Built-In Tools
Verification, plan mode, and sandbox behavior	Tool Safety
Connector lifecycle and MCP bridging	Connectors and MCP
SSE and A2A wire mapping	Event Bridges
Telemetry startup and metrics	SDK Observability
Foundation modules such as `types/` and `constants/`	Foundation Folders
Agent execution, `runtime/`, `manager/`, and `compaction/`	Execution Folders
`session/`, `store/`, and `gateway/` boundaries	Session and Store Folders
Providers, connectors, bridges, tools, plugins, personas, and RAG	Integration Folders