Skip to main content
Most agent code starts as a loop around a model call, and then production asks for more: a human has to approve the refund before it is sent, the process restarts halfway through a run, the conversation has to continue tomorrow from another server, and somebody wants a test that fails when the agent stops calling the right tool. lousho is that loop with those answers built in. It is a library, with no web framework and no hosted runtime: a typed tool-calling loop with approvals, sessions, streaming, sub-agents, skills, MCP and a CLI. The same agent runs in a script, a Node server, a Docker container or a Cloudflare Worker (a Worker supports a subset of the providers and tools).

What sets it apart

Record, replay and catch drift

lousho eval --record saves each case’s real provider run as a cassette, --replay runs it in CI with no network or key, and --drift re-records and reports how the tool-call trajectory changed. defineEval() asserts on which tools were called, in what order, with which arguments.

Durable approvals on your own stores

Sessions, checkpoints and approval pauses live in memory, files, one SQLite file or Cloudflare KV. A paused or interrupted run resumes from another request or another process, on a Worker too.

One agent, many surfaces

lousho build ships the agent to a Node server, Docker or a Worker; lousho acp serves it to editors and serveMcp to MCP clients. Runs emit OpenTelemetry GenAI spans with token usage and USD cost.

Self-hosted, across AI SDK majors

One package, no platform account or hosted control plane. The ai peer accepts v4, v6 and v7, and fromAiSdk() / fromAiSdkTools() reuse your existing AI SDK models and tools.

The building blocks

Each block is one function or one option on createAgent(). Use the ones you need; none of them requires the others.

Where an agent can live

The agent is the same object everywhere. What changes is the surface in front of it.

In a web app

useLoushoAgent() for React and Vue, a store for Svelte, the Vercel AI SDK’s useChat, or createRouteHandler(agent) in any Fetch-API framework.

In chat and on a schedule

Slack, Discord, webhooks and plain HTTP channels map messages to sessions and send approvals back. Cron schedules start runs on their own.

In an editor

lousho acp serves your agent to Zed and other Agent Client Protocol editors, with tool calls and permission prompts.

As a deployed service

lousho build produces a Node server, a Docker image or a Cloudflare Worker from one spec.

Compared to other libraries

lousho sits one layer above a model call: like the AI SDK 7 agents, eve, Mastra, LangGraph, the OpenAI Agents SDK or the Claude Agent SDK, it runs a full agent loop. It builds on the Vercel AI SDK rather than replacing it: the built-in providers use ai and @ai-sdk/*, and fromAiSdk() wraps any other AI SDK model. Durable approvals, evals, agent directories and coding-agent harnesses are no longer unique: AI SDK 7, eve and Mastra ship their own. What Lousho still does differently is record/replay with trajectory drift, durable approvals on Cloudflare Workers KV, serving the same agent over ACP and MCP, and running as one self-hosted package. It is weaker where it is young: it is in alpha, has no Postgres store, fewer native providers and no hosted dashboard. When something else fits better: if you only need to stream model text in a Next.js route, the AI SDK alone is less surface; if you deploy on Vercel and want its runtime, eve fits it natively; if you want Claude Code’s own harness, the Claude Agent SDK gives you exactly that; if your team is on Python or already runs LangGraph Platform, staying there avoids a second stack. Coming from the AI SDK? See Migrating from the AI SDK. For a feature-by-feature table against the AI SDK, the OpenAI Agents SDK, Mastra and LangGraph.js, see How Lousho compares.

Next steps

  • Quick start: scaffold a project, or run the five-line agent. The snippets run offline with the built-in mock provider.
  • Installation: requirements, peer dependencies, and which provider package pairs with which ai major.
  • Tools: define your first tool and see how arguments are validated.
  • Approvals: pause a run for a human decision and resume it.
  • Testing: write a deterministic test for an agent without an API key.
  • Migrating from the AI SDK: move a ToolLoopAgent or generateText loop, its models and its tools.
  • Lousho with coding agents: point Claude Code, Cursor or another coding agent at docs it can read.