Theo Docs
TheoCodeTheoCreateTheoKitTheoKit-SDKTheoUITheo PaaS

Overview

A toolkit for building your own agents, with the primitives — not the opinions.

TheoKit-SDK is what you reach for when TheoKit feels too much like a framework. It exposes the same primitives — agents, tools, sessions, streams, artifacts — as a plain TypeScript package, so you can compose them inside any runtime: a Node service, a Cloudflare Worker, a Lambda, a CLI, a desktop app.

Inspired by the Claude SDK, the Cursor SDK, and Pi — but provider-agnostic and shaped for the usetheo ecosystem.

Install

npm install @usetheo/sdk

Works in Node 22+, Bun, Deno, and edge runtimes that support fetch + streaming responses.

Core primitives

Agent

A typed loop over a model, a tool set, and a session. Bring your own provider (OpenAI, Anthropic, Mistral, local).

Tool

A typed function the agent can call. Validation, error surfacing, and retry policy are all declarative.

Session

A persistent conversation with messages, tool calls, and artifacts. Plug your own storage.

Stream

A typed event stream from the agent — tokens, tool calls, artifacts, errors — that you forward to any UI.

Artifact

Files, snippets, and structured outputs the agent produces. Versioned and addressable by ID.

Middleware

Wrap any agent step with auth, observability, rate limiting, or custom transforms.

Quick start

src/agent.ts
import { Agent, tool } from '@usetheo/sdk';
import { z } from 'zod';

const search = tool({
  name: 'search',
  description: 'Search the knowledge base',
  input: z.object({ query: z.string() }),
  run: async ({ query }) => {
    return await db.search(query);
  },
});

export const supportAgent = new Agent({
  model: 'anthropic:claude-sonnet-4-6',
  tools: [search],
  system: 'You are a support agent. Cite sources.',
});

// In your handler
const stream = supportAgent.stream({ message: 'How do I deploy?' });
for await (const event of stream) {
  console.log(event);
}

Why use the SDK instead of TheoKit

Use caseReach for
You want a Next.js app with chat UI + auth + persistence done for youTheoKit
You are building a CLI, a Worker, a Lambda, a background job, or a non-React UITheoKit-SDK
You need to embed an agent inside an existing codebase that is not Next.jsTheoKit-SDK
You want full control over the runtime, the transport, and the persistenceTheoKit-SDK

TheoKit-SDK is a community auxiliary in the usetheo ecosystem. It does not require Theo PaaS, TheoCode, or TheoKit to be useful. Adopt it standalone in any project.

Where to go next

Compare with TheoKit

If you want the framework opinions baked in, TheoKit is a thin layer on top of these same primitives.

Need a UI to render the stream?

TheoUI ships agent components that consume the SDK's event stream out of the box.

Build it with TheoCode

TheoCode understands the SDK's primitives and can scaffold agent loops, tools, and middlewares for you.

On this page

InstallCore primitivesQuick startWhy use the SDK instead of TheoKitWhere to go next