Overview
Overview of the public surfaces exported by @namzu/sdk and how they fit together.
@namzu/sdk is the core Namzu package. It exposes the runtime primitives that stay stable across provider choices: agents, tools, stores, registries, sandboxes, RAG helpers, identifiers, and type contracts.
1. What Lives in the SDK
The SDK package is the place to start if you want to run agents without binding your application to a single model vendor.
| Capability | Main public surfaces |
|---|---|
| Agent execution | ReactiveAgent, PipelineAgent, RouterAgent, SupervisorAgent, AgentManager |
| Provider integration | ProviderRegistry, LLMProvider, provider-facing type contracts |
| Tool system | defineTool, ToolRegistry, getBuiltinTools, built-in filesystem and shell tools |
| Safety and isolation | LocalSandboxProvider, verification and permission-related types |
| State and persistence | RunDiskStore, DiskTaskStore, conversation and memory stores |
| Session lifecycle | InMemorySessionStore, DiskSessionStore, session hierarchy, handoff, retention |
| Prompt composition | SkillRegistry, assembleSystemPrompt, mergePersonas, withSessionContext |
| Retrieval | TextChunker, DefaultRetriever, DefaultKnowledgeBase, createRAGTool |
| Desktop integration point | createComputerUseTool, ComputerUseHost types |
| Connectors and MCP | ConnectorRegistry, ConnectorManager, MCPClient, MCPToolDiscovery, MCPConnectorBridge |
| Wire bridges | mapRunToStreamEvent, A2A helpers (telemetry ships from @namzu/telemetry as of 0.4.0) |
2. What Does Not Live in the SDK
The SDK intentionally leaves vendor-specific integrations and optional capability packages outside core:
- Provider implementations live in their own packages under
@namzu/*. - Desktop control lives in
@namzu/computer-use. - Local-only workspace packages that are not published are not part of this docs surface.
This separation keeps the SDK install surface smaller and lets you compose only the pieces you actually deploy.
3. Core Concepts
The public package surface is easiest to understand through four concepts:
| Concept | Role |
|---|---|
| Provider | Supplies chat() and chatStream() through the LLMProvider contract |
| Agent | Owns the runtime behavior for a run and produces a result from messages plus config |
| Tool registry | Holds callable tools and controls their availability state |
| Run context | Carries model settings, IDs, working directory, and optional runtime overrides |
Three IDs are operationally important in 0.2.x runtime usage:
projectIdidentifies the long-lived project scope.sessionIdidentifies the immediate run session.tenantIdidentifies the isolation boundary.
4. SDK Docs Structure
The SDK docs are grouped by domain instead of a flat file list:
| Folder | Purpose |
|---|---|
| agents/ | agent classes, orchestration, delegation, and manager-facing behavior |
| runtime/ | runtime overview, IDs, configuration, and low-level query entrypoints |
| tools/ | tool definitions, built-ins, and safety policy |
| provider-integration/ | SDK-level provider registry and direct provider operations |
| integrations/ | connectors, MCP, plugins, and event bridges |
| prompting/ | skills, personas, and prompt composition |
| retrieval/ | knowledge bases, retrieval, and RAG surfaces |
| sessions/ | session hierarchy, workspaces, summaries, and retention |
| observability/ | telemetry and instrumentation |
| architecture/ | deeper source-tree and pattern-level architecture docs |
5. Recommended Entry Pages
Read these pages next depending on what you are doing:
| If you want to... | Read |
|---|---|
| Run a first agent | SDK Quickstart |
| Understand runtime components | SDK Runtime |
| Understand provider registration and creation | SDK Provider Integration |
| Choose the right agent class and delegation boundary | SDK Agents |
| Build system prompts from persona and skill files | SDK Prompting |
| Add knowledge-base retrieval | SDK Retrieval |
| Persist project-session-sub-session state | SDK Sessions |
| Define custom tools | SDK Tools |
| Integrate connectors, plugins, or MCP servers | SDK Integrations |
| Configure tracing and metrics | SDK Observability |
| Understand folder boundaries and architecture patterns | SDK Architecture |
| Pick a model integration | Providers Overview |
| Add desktop control | Computer Use |