Introduction

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/build-ai-agent 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.

import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are a helpful assistant.' });
const { text } = await agent.send('Hello!');
console.log(text);

What sets it apart

Durable on any host

Sessions, checkpoints and approval pauses live in pluggable stores: memory, files, one SQLite file, or Cloudflare KV. A paused or interrupted run resumes from another request or another process.

Tested like code

mockModel scripts the model, recordReplay cassettes replay real runs offline, and defineEval() asserts on which tools were called, in what order, with which arguments.

Node and Workers, traced

lousho build ships one agent spec to a Node server, Docker or a Worker. Runs emit OpenTelemetry GenAI spans, and every result reports token usage and USD cost.

The building blocks

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

Block	What you write	What you get
Tools	`defineTool()` with a zod `input`	Arguments typed and validated, calls run in parallel
Approvals	`needsApproval`, or `permissions` rules	A run that pauses for a human, then continues with `agent.approvals.resolve()`
Sessions	`agent.session({ id })`	A multi-turn conversation kept in memory, files or SQLite
Memory	`defineMemory()` slots	Facts recalled into the prompt across sessions, per user or globally
Structured output	`output: zodSchema`	A typed, validated `result.object`, with one repair step
Streaming	`agent.stream()`	Typed, versioned JSON events, ready for SSE
Sub-agents	`subagents: { researcher, writer }`	One `task` tool for the lead; sub-agents run in parallel, locally or remotely
Skills	`loadSkills()`	Instructions the agent loads only when a task needs them
Providers	a `provider/model` string	OpenAI, Anthropic, OpenRouter, Ollama or a mock, with retry and fallback

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.

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.
Lousho with coding agents: point Claude Code, Cursor or another coding agent at docs it can read.

Get started

Build an agent

Compose agents

Run it reliably

Put it in front of people

Test and observe

Ship

What sets it apart

Durable on any host

Tested like code

Node and Workers, traced

The building blocks

Where an agent can live

In a web app

In chat and on a schedule

In an editor

As a deployed service

Next steps

​What sets it apart

Durable on any host

Tested like code

Node and Workers, traced

​The building blocks

​Where an agent can live

In a web app

In chat and on a schedule

In an editor

As a deployed service

​Next steps

What sets it apart

The building blocks

Where an agent can live

Next steps