SDK Overview

Seepient Agent is a headless AI agent framework for building LLM-powered applications. The SDK provides a functional, composable API -- no class hierarchies, no boilerplate. Import a function, pass a prompt, get a result.

Architecture

Seepient Agent is organized in three layers of increasing statefulness:

askSeepient()    -- One-shot. Stateless. No memory between calls.
createChat()     -- Multi-turn session object. The session owns its history.
createSeepient() -- Stateful. Multi-turn with session persistence.
Server           -- Remote. REST + WebSocket for distributed deployments.

Every layer delegates to the same core agent loop, so tool execution, hook lifecycle, abort handling, and usage tracking behave identically regardless of which entry point you use.

Functional API philosophy

The SDK is built around plain functions and plain objects, not class instances:

• askSeepient(prompt, options?) -- returns a Promise<AskSeepientResult>, or a Promise<AskSeepientStreamResult> with async iterables when { stream: true }
• createChat(options?) -- returns a Promise<ChatSession> with .send(), .stream(), and the session-owned messages history (ships in seepient-core)
• createSeepient(options?) -- returns a Promise<Seepient> with .chat(), .chatStream(), and lifecycle methods

Configuration is passed as options objects. Return types are plain interfaces. There are no base classes to extend.

Installation

Prerequisites

Seepient Agent requires Node.js >= 22.19.0.

npm

npm install seepient

pnpm

pnpm add seepient

yarn

yarn add seepient

Serverless or SDK-only?

Install seepient-core instead — the same chat/agent engine without the full agent's built-in tools, sandbox, and gateway (a ~102 MB closure vs ~301 MB).

Import patterns

ESM -- recommended

import { askSeepient, createSeepient } from "seepient";

SDK types only

import type {
  AskSeepientOptions,
  AskSeepientResult,
  AskSeepientStreamResult,
  Seepient,
} from "seepient";

Tools and factories

import { trustedHostTool, preparedTool, brokerConnector, CORE_TOOLS, COMM_TOOLS, ADVANCED_TOOLS, ALL_TOOLS } from "seepient";

Settings and Gateway

import { settings, gateway, createProviderManagerApi } from "seepient";

Server

import { runSeepientServer } from "seepient/server";

Quick examples

One-shot text generation

import { askSeepient } from "seepient";

const result = await askSeepient("Explain recursion in one paragraph");
console.log(result.text);
console.log(result.usage.totalTokens);

When called without options, Seepient resolves the provider and model automatically from your persisted provider-management configuration (setup wizard, TUI dock, seepient auth login, or an injected credential store) at ~/.seepient/providers-overlay.json. It never reads provider API keys from the environment. It also registers all 15 built-in tools.

To run pure text completions without tool execution, pass tools: []. To specify a model or restrict tools, pass configuration options. See askSeepient for the complete resolution order and reference.

Streaming

import { askSeepient } from "seepient";

const stream = await askSeepient("Write a haiku about programming", {
  stream: true,
  onText: (delta) => process.stdout.write(delta),
});

const finalText = await stream.fullText;

Multi-turn agent

import { createSeepient } from "seepient";

const agent = await createSeepient({
  model: "gpt-5.4",
  systemPrompt: "You are a concise coding assistant.",
});

const reply = await agent.chat("What is a closure in JavaScript?");
console.log(reply.text);

// Context is preserved -- follow-up questions work naturally
const followUp = await agent.chat("Show me an example");
console.log(followUp.text);

Custom tools

import { askSeepient, trustedHostTool } from "seepient";

const weatherTool = trustedHostTool({
  definition: {
    type: "function",
    function: {
      name: "get_weather",
      description: "Get the current weather for a city",
      parameters: {
        type: "object",
        properties: {
          city: { type: "string", description: "City name" },
        },
        required: ["city"],
      },
    },
  },
  execute: async (args) => {
    const { city } = (args ?? {}) as { city: string };
    return `Weather in ${city}: 72F, sunny`;
  },
});

const result = await askSeepient("What is the weather in Tokyo?", {
  tools: [weatherTool],
});

Migration Note: Permission Pipeline & Pre-Grants

Starting in v0.6.1, the permission pipeline is mandatory and active by default across all SDK entry points (createSeepient, askSeepient).

• The legacy permissionPipeline flag has been removed.
• The legacy grants option has been removed. Instead, use consentMode: "autonomous" to permit safe unattended execution within policy boundaries, or define explicit scoped capability sets via principalPolicy or deploymentCeiling.

HTTP SSE endpoint

import { askSeepient } from "seepient";

app.get("/chat", async (req, res) => {
  const stream = await askSeepient(req.query.prompt as string, { stream: true });
  return stream.toResponse();
});

Provider support

Seepient Agent supports multiple LLM providers out of the box:

Provider	provider value	Default model
OpenAI	"openai"	gpt-5.4
Anthropic	"anthropic"	claude-sonnet-4-6-20260320
GLM	"glm"	opus
OpenAI-compatible	"openai-compatible"	gpt-5.4 (configurable baseUrl)

Configure providers with the seepient setup CLI wizard, provider management, or — from the SDK — a providers record with a credential store. Seepient reads no provider API keys from the environment.

Built-in tools

Seepient Agent ships with a set of built-in tools organized into groups:

Group	Tools
Core	execute_shell_command, read_file, write_file, edit_file, get_current_datetime, manage_todos, render_widget
Comm	send_email, web_search, send_notification
Advanced	read_website, take_screenshot, generate_image, optimize_prompt, use_skill

Pass tool names as strings, or use group names ("core", "comm", "advanced", "all") to include entire groups.

API reference pages

Page	Description
createChat()	Multi-turn chat session owning its history — the slimmest shape, shipped in seepient-core
createSeepient()	Stateful multi-turn agent with session persistence and provider management
askSeepient()	One-shot agent execution (streaming via stream: true) with automatic tool loops and security boundaries
Settings API	Programmatic configuration facade for reading, updating, and watching settings
Provider Management	Catalog querying, accounts, assignments, and resolution preview
Custom Tools	Explicit trust models: preparedTool, brokerConnector, trustedHostTool
MCP Gateway	Connect Model Context Protocol servers and REST endpoints
Providers	Multi-provider LLM support and model routing
Skills	Reusable skill packages with automatic catalog injection
Hooks and Middleware	Lifecycle callbacks and request/response pipelines
Session Persistence	Built-in atomic files, in-memory, and custom storage backends
Stateless Workers	Zero-disk multi-tenant embedding and storage contracts
Multi-Tenant Isolation	Fail-closed multi-tenancy, store injection, and per-agent tool registries
Types Reference	Complete TypeScript types reference