SDK Quickstart

This page is the smallest complete runtime setup that still reflects how the public SDK actually works today. It starts from provider registration, adds one typed tool, and runs a ReactiveAgent with the required ID fields.

1. Install

pnpm add @namzu/sdk @namzu/openai zod

2. Prerequisite Environment

For the example below, set:

export OPENAI_API_KEY=your_key_here

3. Minimal End-to-End Example

import {
  ProviderRegistry,
  ReactiveAgent,
  ToolRegistry,
  defineTool,
  generateProjectId,
  generateSessionId,
  generateTenantId,
} from '@namzu/sdk'
import { registerOpenAI } from '@namzu/openai'
import { z } from 'zod'
 
registerOpenAI()
 
const { provider } = ProviderRegistry.create({
  type: 'openai',
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini',
})
 
const tools = new ToolRegistry()
 
tools.register(
  defineTool({
    name: 'echo_text',
    description: 'Return the provided text for wiring and prompt checks.',
    inputSchema: z.object({ text: z.string() }),
    category: 'analysis',
    permissions: [],
    readOnly: true,
    destructive: false,
    concurrencySafe: true,
    async execute({ text }) {
      return { success: true, output: text }
    },
  }),
)
 
const agent = new ReactiveAgent({
  id: 'quickstart-agent',
  name: 'Quickstart Agent',
  version: '1.0.0',
  category: 'example',
  description: 'Minimal reactive agent used in docs.',
})
 
const result = await agent.run(
  {
    messages: [
      {
        role: 'user',
        content: 'Say hello, then call echo_text with the phrase tool ok.',
      },
    ],
    workingDirectory: process.cwd(),
  },
  {
    provider,
    tools,
    model: 'gpt-4o-mini',
    tokenBudget: 8_192,
    timeoutMs: 60_000,
    projectId: generateProjectId(),
    sessionId: generateSessionId(),
    tenantId: generateTenantId(),
  },
)
 
console.log(result.result)
console.log(result.toolCallCount)

4. Why These Pieces Matter

Each part in the example maps to a stable SDK boundary:

Piece	Why it is required
`registerOpenAI()`	Adds the provider package to `ProviderRegistry`
`ProviderRegistry.create()`	Returns the `LLMProvider` instance the agent will use
`ToolRegistry`	Holds callable tools and converts them into model-facing schemas
`ReactiveAgent`	Runs the agent loop over messages, tools, and provider calls
`projectId`, `sessionId`, `tenantId`	Required runtime identity fields for current session-hierarchy rules

5. What the Tool Is Doing

The custom echo_text tool is intentionally simple because it proves four things at once:

the tool schema is valid
the tool registry is working
the model can see and choose the tool
tool results return into the runtime loop correctly

For a first integration, that is more useful than jumping straight to filesystem or shell tools.

6. What the Result Gives You

ReactiveAgent.run() returns a structured result object with fields such as:

runId
status
stopReason
usage
cost
iterations
messages
result
toolCallCount

That means you can use the same result both for user-facing output and for runtime instrumentation or debugging.

7. Common First Errors

Error shape	Usual cause
`Unsupported provider type`	The provider package was not registered before `ProviderRegistry.create()`
`DuplicateProviderError`	The same provider was registered twice without `{ replace: true }`
`requires sessionId, projectId, and tenantId`	One of the runtime IDs was omitted from agent config
Tool returns `success: false`	The tool threw; `defineTool()` converts the throw into a structured tool failure

8. Recommended Next Step After This Example

Once this exact quickstart works:

replace echo_text with real tool surfaces
decide which built-in tools should be active by default
choose whether you need verification or plan mode
keep projectId, sessionId, and tenantId stable according to your app's identity model

9. Where to Go Next

Read SDK Tools if you are adding real tool surfaces.
Read Built-In Tools if you want to start from the shipped tool set.
Read Provider Operations if you want a direct provider preflight before adding more runtime structure.
Read Agents and Orchestration if the runtime is outgrowing a single ReactiveAgent.
Read Skills and Personas if you want repeatable behavior without hardcoding one giant systemPrompt.
Read Retrieval and RAG if you need knowledge-base-backed answers.
Read Sessions, Workspaces, and Retention if you need durable session or delegation state.
Read Run Identities if you need a durable ID strategy.
Read Run Configuration if you need to tune limits and policy.
Read Low-Level Runtime if you need verification, sandboxing, or raw event streaming.
Read Connectors and MCP if your runtime needs external-system integrations or MCP interoperability.
Read Providers Overview if you need a different model backend.
Read Computer Use if the agent needs screenshots or desktop input.

On this page