Get started with TypeScript

Zhivex keeps the application contract separate from each model provider. Your code imports portable primitives from @zhivex-ai/sdk and installs only the provider adapters it actually uses.

Before you begin

Use the SDK from a trusted server runtime such as Bun, Node.js, a route handler, an API server, or a background worker. Provider keys and effectful tools must not be shipped to the browser.

You need:

• a server-side TypeScript project;
• Node.js 18.18+ or Bun 1.3.7+ (published package requirements);
• credentials for at least one provider.

1. Install the SDK

Install the high-level package and one provider adapter:

bun init -y
bun add @zhivex-ai/sdk@1.35.0 @zhivex-ai/openai@0.17.0

For Node, start in an empty project directory and install a TypeScript runner:

npm init -y
npm install @zhivex-ai/sdk@1.35.0 @zhivex-ai/openai@0.17.0
npm install --save-dev tsx

Verify installation without a model call

Save verify.mjs:

import { generateText } from "@zhivex-ai/sdk";
import { createOpenAI } from "@zhivex-ai/openai";
if (typeof generateText !== "function" || typeof createOpenAI !== "function") {
  throw new Error("SDK imports unavailable");
}
console.log("SDK_READY");

Run node verify.mjs or bun run verify.mjs. Expected output: SDK_READY. This only imports packages locally and does not need a key or make a model call.

Add zod when your application defines tools or structured outputs:

bun add zod

Use @zhivex-ai/sdk@next only when deliberately validating a prerelease.

For ordinary application code, keep using the package root. Focused public entrypoints are available when the boundary itself is useful:

• @zhivex-ai/sdk/catalog for the release-managed model inventory;
• @zhivex-ai/sdk/mcp-server for the experimental MCP server that exposes local tools and agents, with @zhivex-ai/sdk/mcp-server-stdio for process stdio;
• @zhivex-ai/sdk/beta and @zhivex-ai/sdk/experimental for explicit risk opt-in;
• @zhivex-ai/sandbox-docker for the reference Docker execution environment;
• @zhivex-ai/trace-viewer for the local read-only ledger and span viewer;
• @zhivex-ai/ag-ui for the opt-in AG-UI 1.0 adapter, which is not re-exported from @zhivex-ai/sdk;
• @zhivex-ai/core/contracts, /runtime, /workflows, /ui, /node, /testing, /agents, /generation, /provider, and /catalog for adapter, framework, or infrastructure authors.

Existing root imports remain compatible. Do not replace them mechanically; use a focused entrypoint when it makes the runtime or stability boundary clearer.

2. Configure credentials

Keep the provider key in your server environment:

export OPENAI_API_KEY="replace-with-your-provider-key"
export ZHIVEX_MODEL="replace-with-a-model-available-to-your-account"

Do not prefix provider credentials with a public framework namespace such as PUBLIC_ or NEXT_PUBLIC_.

3. Generate text

This next step makes a billable provider call. API keys and credentials explains setup and authentication errors.

Create quickstart.mts (ES module for Node and Bun):

import { generateText } from "@zhivex-ai/sdk";
import { createOpenAI } from "@zhivex-ai/openai";

if (!process.env.OPENAI_API_KEY || !process.env.ZHIVEX_MODEL) {
  throw new Error("Set OPENAI_API_KEY and ZHIVEX_MODEL first");
}

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

const result = await generateText({
  model: openai(process.env.ZHIVEX_MODEL),
  maxTokens: 64,
  timeoutMs: 30_000,
  system: "Be concise and technical.",
  prompt: "Explain this product architecture in three bullets."
});

console.log(result.text);
console.log(result.finishReason);
console.log(result.usage);

Run it with:

bun run quickstart.mts
# Node alternative
npx tsx quickstart.mts

Expected output: model-generated text, then a finish reason and usage object. Text varies by model. A missing key fails before the request; 401 means authentication failed, 404 can mean an inaccessible model, and 429 can mean quota or rate limits. See credentials troubleshooting.

The response normalizes the text, finish reason, usage, tool results, messages, and execution steps so the surrounding application does not depend on a provider-specific response shape.

Resolve a provider/model string

TypeScript 1.35.0 also accepts a provider/model string. This is the hello world from the SDK repository at the published commit. register: true makes the string resolve. Unknown providers and a missing apiKey throw ModelResolutionError before any request.

import { generateText, openaiCompatible } from "@zhivex-ai/sdk";

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) throw new Error("Set OPENAI_API_KEY.");

openaiCompatible({
  name: "openai",
  baseURL: "https://api.openai.com/v1",
  apiKey,
  register: true
});

const { text } = await generateText({
  model: "openai/gpt-4o-mini",
  prompt: "Hello"
});

console.log(text);

createMistralCompatible and createGroqCompatible are presets of the same factory, with base URLs https://api.mistral.ai/v1 and https://api.groq.com/openai/v1. They are not native adapters and they are not separate npm packages. A model object from createOpenAI() still works.

4. Choose the next primitive

Need	Start with
One response	generateText()
Progressive text	streamText()
Validated JSON	generateObject()
Model-selected tools	Agent
Multi-turn product chat	Runner + SessionService
Known sequence of steps	createWorkflow()

Continue with generation and tools, build a stateful experience with agents and sessions, or implement a known process with workflows.

Source reference

The runnable examples and the complete API-oriented guide live in the TypeScript SDK repository.