llms.txt

# @lousho/build-ai-agent

> Open-source TypeScript SDK for agents that run in your own Node process: tool calling, MCP, sessions that survive a restart, human approvals, and OpenTelemetry. No hosted runtime.

## Docs

- [Lousho — TypeScript AI agent SDK](https://github.com/LinuxDevil/agent-sdk/blob/main/README.md): Open-source TypeScript SDK for agents that run in your own Node process: tool calling, MCP, sessions that survive a restart, human approvals, and OpenTelemetry. No hosted runtime.
- [Installation](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/installation.md): `ai` (the Vercel AI SDK: `^4.3.19`, `^6.0.0` or `^7.0.0`) and `zod` (`^3.25.76 || ^4.0.0`) are required peer dependencies. `ai` 5 is not supported.
- [Quick Start](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/quick-start.md): This page takes you from a one-line agent to tools, streaming, sessions, an approval and an offline test. Every snippet after the first runs as-is with no API key, on the SDK's built-in mock provider.
- [API Overview](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/api-overview.md): The package root (`@lousho/build-ai-agent`) exports everything below. For the complete, generated API reference (every export, signature and doc comment), build the TypeDoc site
- [Agent Client Protocol (ACP)](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/acp.md): The Agent Client Protocol lets an editor drive a coding agent that runs as a subprocess: the editor writes JSON-RPC 2.0 requests to the agent's stdin, one JSON message per line, and reads the agent's replies and streamed updates from its stdout. Zed and other editors speak it.
- [Agent directories](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/agent-directories.md): An agent can be defined as a directory. `loadAgentDir()` reads it and calls `createAgent()` with the options the files describe, so it returns exactly what `createAgent()` returns. The typed code API stays the source of truth: a directory is a different way to write the same options, and you can switch to code at any time without a rewrite.
- [Agent Forge](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/agent-forge.md): Agent Forge (`apps/agent-forge`, also called the Studio) is this SDK's companion dashboard: one app with a left navigation to build and run agents, try prompts, and read what your agents did from the observe daemon.
- [AI SDK UI (`useChat`)](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/ai-sdk-ui.md): If your front end already uses the Vercel AI SDK's UI hooks (`useChat` from `@ai-sdk/react`, and the Vue, Svelte and Angular equivalents), you can keep them and run a Lousho agent behind the route. Three functions, exported from the package root, do the translation. They import nothing from `ai`, use no `node:*` module, and work on Node, Workers and any Fetch-based runtime.
- [Approvals](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/approvals.md): Flag a tool `needsApproval` and the run pauses before calling it, until a human (or your code) approves or rejects the call. The pause is saved in an `ApprovalStore`, so the decision can come minutes or days later, from another request or another process, and the run then continues where it stopped.
- [Route auth and principals](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/auth.md): An agent served over HTTP needs to know two things about each request: may it call at all, and who is it. `@lousho/build-ai-agent/auth` answers both.
- [Build a coding agent](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/build-a-coding-agent.md): This page builds a terminal coding agent in the style of Claude Code: it reads and edits files in your project, runs commands, asks you before it writes a file or runs something risky, and keeps the conversation going for follow-up questions.
- [Channels](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/channels.md): A channel connects an agent to one surface: a JSON API, a webhook, a chat app. It says how an inbound request is authenticated, which conversation it belongs to, and how the agent's reply (or an approval it pauses on) goes back to the surface. `mountChannels()` serves your channels behind one `(req, res)` handler and runs every request the same way
- [Claude Code projects](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/claude-projects.md): A repository that already carries Claude Code's conventional files — `CLAUDE.md`, `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, `.claude/scratchpad/` — loads them with `claudeProject()`: the result spreads into `createAgent()`, so the same directory drives both harnesses. Nothing is copied or renamed; Lousho reads the files where they already are.
- [CLI](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/cli.md): Installing the package also installs the `lousho` command. It scaffolds projects, checks your setup, runs an agent locally, serves it over MCP, runs evals, shows saved traces, builds a deployable artifact and launches the Agent Forge dashboard. Run it with `npx lousho <command>` inside a project that has the SDK installed.
- [Cloudflare Workers](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/cloudflare-workers.md): `npx lousho build --target=cloudflare-worker --agent=agent.yaml` generates a module Worker (`worker.ts`), a `wrangler.toml` and a bundle, `dist/worker.js`, that the build checks for `node:` imports. It needs `tsup` and `wrangler` installed, and it takes an agent spec file or an agent directory (`npx lousho build ./my-agent --target=cloudflare-worker`).
- [Code mode](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/code-mode.md): With code mode the model gets one more tool, `run_code`. Instead of calling tools one at a time, with a model round trip after each, it writes a short JavaScript program that calls the agent's tools as async functions, loops, filters and combines their results, and returns one value.
- [Context compaction](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/compaction.md): A long agent run fills its context window mostly with tool results: file contents, search hits, API responses the model read once and no longer needs in full. Compaction keeps such a run under the model's limit in two phases: first it replaces old tool results with a short marker, and if that is not enough it replaces the oldest turns with a summary written by a (cheaper) model.
- [Comparison with other agent frameworks](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/comparison.md): As of October 2026. This page is a short orientation, not a benchmark. The TypeScript agent space moves fast: most of the projects below now ship durable approvals, evals and coding-agent harnesses of their own, so check their documentation before deciding. Rows about lousho describe this repository and link to the page that documents each claim.
- [Configuration](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/configuration.md): A declarative agent is a YAML (`.yaml`/`.yml`) or JSON (`.json`) file, validated with zod by `loadSpec()` (`src/spec/schema.ts`). It is the format `lousho dev` serves and `lousho build` deploys.
- [Connectors](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/connectors.md): Connectors are how the agent reaches external services — Google Docs, Slack, GitHub, Notion, a database — the way Claude's connectors do. In Lousho a connector is an MCP server: add it to `mcpServers` and its tools join the agent's registry namespaced as `<server>__<tool>`.
- [Decisions](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/decisions.md): `decide()` calls the OpenAI Decisions API (`POST /v1/decisions`): a purpose-built endpoint that evaluates shared input against typed questions and returns calibrated answers roughly 10x faster than a full model turn. It is the fast, deterministic shape for the typed-decision pattern — classify, route, gate, score — without spinning up an agent run.
- [Deployment](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/deployment.md): `lousho build` turns an agent spec file (see Configuration) into a deployable artifact for one target platform
- [Durable execution](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/durable-execution.md): Give `createAgent()` a `store` and pass a `sessionId` to `send()`, and the run survives a crash, a restart, an abort or a human approval that takes days. Nothing here depends on a particular host: any `CheckpointStore` (`memoryStore()`, `SqliteStore`, the Cloudflare KV store the `cloudflare-worker` build wires up, or your own three-method implementation) and any `ApprovalStore` work the same way.
- [Errors](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/errors.md): Every deliberate SDK error is an SDKError with a stable LOUSHO_* code, a hint and a link to its section here; this page lists each code with its cause and fix.
- [Evals](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/evals.md): Evals are regression tests for agent *behaviour*: which tools the agent called, in what order, with which arguments, how many steps it took, and what it said. They are written with `defineEval()`, live in `*.eval.ts` files, run under vitest, and are best run in CI with `lousho eval`, which prints a summary and writes JUnit and JSON reports.
- [The executor API](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/executor-api.md): `createAgent()` is the recommended entry point (see the Quick Start). This page is for code that needs the lower-level options it does not take. To move existing executor code over to `createAgent()`, see Migrating to createAgent().
- [Flows](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/flows.md): A flow is a fixed, multi-step workflow run by one agent: the steps and their order are written down up front instead of being left to the model's judgment. Describe the graph with `FlowBuilder` and run it with the static `FlowExecutor.execute(flow, context, onEvent?)`.
- [Guardrails and sandboxing](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/guardrails.md): Tools for running agents safely: input and output guardrails check what goes into and comes out of any run (and its tool arguments), patch checks are fail-closed checks over a proposed change before you act on it, and sandboxed tools run inside an isolated container instead of the host process. For per-call human decisions see Approvals; for hooks that inspect or veto each tool call see Hooks.
- [Handoffs](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/handoffs.md): A handoff passes the whole conversation to another agent. A triage agent reads the user's request and hands it to a specialist; the specialist answers the user directly, and in a session it keeps the conversation in later turns.
- [Hooks](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/hooks.md): A hook is an object `{ name, preToolCall?, postToolCall?, preGenerate?, postGenerate? }` that runs inside the agent loop, around every tool call and every model call. Use one to write an audit log, deny a tool, redact or truncate a result, inject context before the model call, or change the request (a header, `temperature`) it sends.
- [Hosted provider tools](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/hosted-tools.md): Some model providers run tools themselves, inside the model request: OpenAI's web search, code interpreter and file search are the common ones. Put them in `tools` next to your own tools; the provider runs them, and the run reports each call in its events, keeps it on the transcript and counts it in usage.
- [Deploying to a Hostinger VPS](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/hostinger-vps.md): The `docker` deployment target is a plain Dockerfile + bundled server, so it runs on any Docker host — including a Hostinger VPS. The hostinger-deploy example ships a complete, tested recipe: `deploy.mjs` verifies the VM through the Hostinger API, builds locally, ships the context over SSH, and runs the container — then proves the deploy with `/health` and one real `/chat` turn.
- [MCP (Model Context Protocol)](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/mcp.md): MCP works in two directions. Your agent can call the tools of MCP servers, or your agent can be an MCP server that Claude Code, Cursor and other MCP clients call. Both live in the `@lousho/build-ai-agent/mcp` subpath, and `@modelcontextprotocol/sdk` is an optional peer: install it to use either direction.
- [Memory](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/memory.md): A session remembers one conversation. Memory is what an agent keeps across conversations: a user's preferences, facts it was told, decisions made last week. You give an agent one or more named memory slots; each slot stores short text items through a provider and is keyed by a scope (one memory for everybody, one per session, or one per user).
- [Migrating from the Vercel AI SDK](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/migrating-from-ai-sdk.md): This page is for code built on the Vercel AI SDK's agent loop: `generateText({ tools })` or `streamText({ tools })` with a step limit, or `new ToolLoopAgent({ ... })`. You can keep your models, your tools and your `useChat` front end. Three adapters bring them over without a rewrite
- [Models, tokens and cost](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/models-and-cost.md): Dependency-free helpers for budgeting and context decisions.
- [Next.js and other Fetch-API frameworks](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/nextjs.md): `createRouteHandler(agent, options?)` serves an agent from a route file of any framework whose handlers take a Web `Request` and return a `Response`: the Next.js App Router, SvelteKit, Remix / React Router, Hono, Bun.serve. It is a thin wrapper over the same session API as `lousho dev` and the deployed server (Deployment), so the React, Vue and Svelte bindings work against it unchanged.
- [OAuth](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/oauth.md): Tools and MCP servers that call an API on someone's behalf need an OAuth access token, and usually a refresh token to get the next one.
- [Tracing and observability](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/observability.md): `AgentExecutor.execute()` and `FlowExecutor.execute()` emit spans through a `TraceExporter`. Span names and attributes follow the OpenTelemetry GenAI semantic conventions, so GenAI-aware observability backends can recognise them without custom mapping.
- [OpenAPI tools](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/openapi-tools.md): Most services publish an OpenAPI document and no MCP server. `openApiTools()` turns that document into one typed tool per API operation, so an agent can call the API without a hand-written `defineTool()` per endpoint and without the raw `http` tool. Operations that change data ask for approval by default.
- [Pause, restart, resume](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/pause-and-resume.md): A tutorial for one job: an agent that stops to ask a human before a risky tool call, survives a process restart while it waits, and carries on once someone decides. Then what happens when the process dies in the middle of a tool.
- [Permission modes](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/permission-modes.md): A permission mode puts an agent in a named state instead of writing rules: look but do not touch (`plan`), edit files without asking (`acceptEdits`), or never pause (`dontAsk`). Switch it in the middle of a session, the way you would work with a coding agent: plan first, then let it edit.
- [Providers](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/providers.md): An `LLMProvider` is what an agent generates with. The SDK ships OpenAI, Anthropic, Google (Gemini), OpenRouter, Ollama and `pi` providers (each backed by an optional peer package, see Installation) and a deterministic mock for tests. Name one with a `provider/model` string, or pass a provider instance.
- [Queued input and steering](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/queue-and-steer.md): Add input to a run that is still going, or redirect it. Both are methods of the run handle that `agent.stream()` returns; see Streaming.
- [React](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/react.md): `useLoushoAgent()` puts an agent behind a chat UI. It runs a turn, reads the typed event stream as it arrives and turns it into render-ready state: messages with their text and tool calls, a `status` for the composer, and the tool call waiting for approval, if any.
- [Reasoning](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/reasoning.md): Reasoning models think before they answer. The `reasoning` option sets how much, and the run reports what the model thought separately from its answer: as `reasoning.*` events in `agent.stream()`, and as `result.reasoning`. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/anthropic/claude-sonnet-4.5`).
- [Registry](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/registry.md): `lousho add` installs a tool, skill, channel, schedule, memory slot or kit into an agent directory from a registry. A `kit` item is a whole agent directory: installing it lays out `agent.*`, `instructions.md`, tools, skills and sub-agents so the target becomes (or grows into) an agent directory itself.
- [Runs: finish reasons, cancellation and parallel tools](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/runs.md): How a run ends, how to stop one, and how tool calls of one model turn run in parallel.
- [Schedules](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/schedules.md): A schedule runs the agent on a cron expression, with nobody asking: a morning summary, a nightly cleanup. `defineSchedule()` declares one, an agent directory picks them up from `schedules/`, and `startSchedules()` (or the node server) runs them in process. Schedules replaced `CronTriggerAdapter` (see Migrating from triggers).
- [Sessions](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/sessions.md): `agent.send(text)` is single-turn: every call starts from an empty history. A session is a multi-turn conversation: it keeps the transcript and passes it to the model on every `send()`.
- [Skills](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/skills.md): A skill is a named chunk of instructions (a markdown document) that the model loads only when it needs it. This is progressive disclosure: instead of pasting every playbook into the system prompt, you list skills by name and one-line description, and the model pulls in the full text on demand.
- [Stream events](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/stream-events.md): The events `agent.stream()` emits, their order and their versioning. For how to consume a stream, see Streaming.
- [Streaming](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/streaming.md): `agent.stream()` runs an agent exactly like `agent.send()` and reports the run as a stream of typed events: model text as it arrives, every tool call, step boundaries, approval requests, and a final `run.done`. Every event is a plain JSON object, so you can forward it to a browser over Server-Sent Events or a WebSocket without converting it.
- [Structured output](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/structured-output.md): Give an agent a zod schema as `output` and its final reply becomes a typed, validated object: `result.object`. The agent can still call tools first; only the final answer has to match the schema. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
- [Sub-agents](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/sub-agents.md): A sub-agent is a separate agent - its own instructions, model, tools and skills - that a lead agent hands a self-contained task to. The sub-agent starts with a clean context (it sees only the task prompt, never the lead's conversation), works through as many steps as it needs, and its final answer comes back to the lead as one tool result.
- [Svelte](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/svelte.md): `loushoAgent()` for Svelte is the React hook as a store: the same sources, the same state and the same actions, over the same typed event stream. Read React for what each field means, the two kinds of source, how approvals work and the server side; this page covers what differs.
- [Testing agents](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/testing.md): `@lousho/build-ai-agent/testing` ships `mockModel`: a scripted, deterministic `LLMProvider` for unit tests. You write down what the model should say on each turn, run your agent, and then assert on exactly what the agent sent to the model. No network, no API keys, no flakiness.
- [Tool search](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/tool-search.md): An agent with many tools (several MCP servers, a large internal toolkit) sends every tool definition on every model call. That costs input tokens and, past about 30 tools, makes the model worse at picking the right one. With tool search, tools marked `deferLoading` are left out of the request.
- [Tools](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/tools.md): A tool is a typed function the model can call. Define one with `defineTool()`: the argument and result types are inferred from its zod `input`, the arguments are validated before `execute` runs, and the result drops in anywhere tools are accepted (`createAgent({ tools: [...] })`, `ToolRegistry.register(tool)`, `AgentBuilder.addTool(tool)`).
- [Triggers](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/triggers.md): A trigger adapter turns one wake-up mechanism into an agent run. The `@lousho/build-ai-agent/triggers` subpath is the extension point for your own mechanism (`TriggerAdapter`, `TriggerRegistry`) plus a few helpers shared with channels and schedules: the `WebhookAuth` shapes, `verifySlackSignature()` and `parseCronExpression()`.
- [Troubleshooting](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/troubleshooting.md): This page starts from what you see and points to the cause, the fix and the page that explains it. First run `npx lousho doctor` (what it checks), then, if you have an error code (`LOUSHO_...`), look it up in Errors.
- [Upgrading to 1.0](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/upgrading.md): Anyone with code written against `1.0.0-alpha.8` or an earlier `1.0.0-alpha.*` release. Between those alphas and the 1.0 line (the changes listed under `1.0.0-alpha.19` in the changelog, first published in `1.0.0-alpha.15`) the package's public surface was reorganized: imports moved to subpaths, dead or superseded APIs were removed, and the patch guardrails were renamed patch checks.
- [Utilities](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/utilities.md): Supporting helpers exported from the `@lousho/build-ai-agent/utils` subpath: encryption and hashing, and file storage for attachments. None of them is needed to build an agent; they are here for the apps around one.
- [Vue](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/vue.md): `useLoushoAgent()` for Vue 3 is the React hook as a composable: the same sources, the same state and the same actions, over the same typed event stream. Read React for what each field means, the two kinds of source, how approvals work and the server side; this page covers what differs.
- [Workspace tools](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/workspace-tools.md): Workspace tools give an agent a file system and a shell, so you can build coding agents in the style of Claude Code. The tools never use `node:fs` or `node:child_process` themselves.

## Examples

- [agent-dir](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/agent-dir/README.md): An agent defined as a directory: `instructions.md` is the system prompt, `tools/word_count.ts` is a `defineTool()` tool, `skills/tone.md` is a skill and `agent.json` holds config. `index.ts` loads it with `loadAgentDir()` and swaps in a scripted `mockModel`, so it runs offline.
- [coding-agent-workflows](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/coding-agent-workflows/README.md): A coding agent driven by deterministic workflows whose routing is a typed decision (the "System One" pattern).
- [coding-harness](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/coding-harness/README.md): A small coding harness assembled from Lousho's building blocks in one `createCodingHarness()` function. It stacks the layers most open-source harnesses share (OpenCode, Codex, Pi, Crush) on one `createAgent()` call
- [connectors](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/connectors/README.md): Connect an agent to external services (Google Docs, Slack, GitHub, Notion, …) the way Claude's connectors do: over MCP.
- [data-analyst](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/data-analyst/README.md): The "chat with your database" archetype (Vanna, Databricks Genie, every text-to-SQL agent) assembled from one `createAgent()` call: a natural-language question comes in, `get_schema` lets the agent inspect the CREATE TABLEs and row counts, `run_query` executes the SELECT the agent writes, and the agent answers with real rows.
- [deep-research](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/deep-research/README.md): The "deep research" archetype Anthropic's multi-agent research system uses: one lead coordinator decomposes a question into subtopics, fans them out to researcher sub-agents called in parallel, then synthesizes their compressed, cited summaries into a report.
- [doc-qa](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/doc-qa/README.md): A question-answering agent scoped to a single fixed document (a short refund policy, inlined in the prompt), built with `createAgent()`.
- [evaluator-loop](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/evaluator-loop/README.md): The evaluator-optimizer pattern from Anthropic's agentic taxonomy ("Building effective agents"): a writer agent drafts, an evaluator scores the draft against a rubric, and a failing draft loops back to the writer - carrying the critic's feedback - until the score passes or the round budget runs out. This is the writer/critic shape CrewAI-style content pipelines use.
- [hostinger-deploy](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/hostinger-deploy/README.md): Deploy a Lousho agent to a real VPS: `agent/` is an agent directory for a small ops assistant (`vps-ops`), and `deploy.mjs` builds it with `lousho build --target=docker`, ships the context over SSH, and runs the container on a Hostinger virtual machine.
- [openrouter](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/openrouter/README.md): Runnable snippets showing `OpenRouterProvider` usage: basic and streaming generation, multi-model comparison, tool calling, `AgentBuilder` configuration, model listing, cost-aware model choice, error handling, multi-turn conversation, and capability checks.
- [ops-pipeline](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/ops-pipeline/README.md): An end-to-end "flagship pipeline" demo composing every primitive
- [phase-pipeline](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/phase-pipeline/README.md): Phase engineering — a deterministic phase pipeline where the model fills each phase but the *order*, the *gate*, and what counts as *done* belong to the harness. The shape behind agentic-workflow repos (phases-oss, leeovery/agentic-workflows)
- [plan-mode](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/plan-mode/README.md): Plan first, then let the agent edit: a coding agent over a `MemoryWorkspace` with `createFsTools()`. The first turn runs with `permissionMode: 'plan'`, so the agent may read files but every write is refused and it proposes the change instead. Then `session.setPermissionMode('acceptEdits')`, and the second turn applies the plan: file edits run without asking for approval.
- [research-assistant](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/research-assistant/README.md): An agent with the built-in `http` tool wired up so it can fetch sources while researching a question, built with `createAgent()`.
- [slack-notifier](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/slack-notifier/README.md): Turns a raw event description into a short, Slack-ready notification message, built with `createAgent()`.
- [support-bot](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/support-bot/README.md): A minimal customer-support agent built with `createAgent()`. Empathetic, concise, and always asks for an order number when a customer reports a problem.
- [support-desk](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/support-desk/README.md): The production support archetype (OpenAI Swarm's shape) built on `createAgent({ handoffs })`: a triage agent classifies the request and hands the *whole conversation* to a specialist, which replies to the customer itself and owns every later turn until it hands back.
- [waves](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/waves/README.md): Waves — Workers · Aggregate · Verify · Extend — the bounded-parallel pattern from the community "waves" workflows (rayfernando-skills, Wave-Engineering/claudecode-workflow).
- [workflow-router](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/workflow-router/README.md): An agent that classifies an incoming request into one of a fixed set of categories (`billing`/`technical`/`sales`), built with `createAgent()`.

## Optional

- [Migrating to createAgent()](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/migrating-to-create-agent.md): This page is for code that uses `AgentBuilder`, `AgentExecutor`, `ToolRegistry` and `resumeAfterApproval()`: the lower-level API the SDK started with. Those exports now live at `@lousho/build-ai-agent/executor` and are not going away; if you stay on them, see The executor API.
- [Prompting and context techniques](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/prompting-techniques.md): Agent quality comes from three layers, and it is worth knowing which layer a technique lives at, because the fix for a misbehaving agent is different at each one