Start a new project
The fastest way in is one command, which creates a runnable project (an agent, an example tool, an offline test, a.env.example for your provider),
installs its dependencies and runs git init:
create-lousho (npm pack), pass the tarball’s absolute path with --package: npx --package=/abs/path/create-lousho-x.y.z.tgz create-lousho my-agent. A bare npx ../x.tgz fails on Windows.
npx lousho init my-agent is equivalent (pass --provider
and --template, since it runs without the interactive prompts). Inside a
project that already has the SDK installed, npx lousho init works too: the
lousho command comes from the SDK package, so a bare npx lousho outside such
a project finds nothing to run. Without arguments, init asks for the
directory, provider and template; npx lousho init --help
lists every flag.
Prefer to add the SDK to an existing project? Install it by hand (see
Installation):
ai major; for Ollama, use ai@^7.0.0 with
ollama-ai-provider-v2@^4.0.0 and zod 4 (see the pairings).
1. Hello world
createAgent() is the zero-config entry point: a provider/model string and
instructions in, a { send } agent out. The API key is read from the
provider’s conventional environment variable (OPENAI_API_KEY here;
ANTHROPIC_API_KEY, OPENROUTER_API_KEY or OLLAMA_BASE_URL for the other
providers). The vendor/ model prefix chooses the provider; with OpenRouter
use openrouter/<vendor>/<model> (e.g. openrouter/openai/gpt-4.1-mini).
model out to let the environment decide: LOUSHO_MODEL (a
provider/model string) if set, otherwise the first of OPENAI_API_KEY,
ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OLLAMA_BASE_URL that is present.
If a key is missing or the prefix is misspelled, the error tells you exactly
what to set or fix. instructions is optional; prompt is accepted as an
alias for it.
2. Add a tool
Define a tool withdefineTool(): the execute and needsApproval arguments
are typed from the zod input, and the result goes straight into
createAgent({ tools: [...] }). The mock provider simulates a tool call
whenever the user message mentions a tool’s name, so this snippet exercises a
real tool round trip without an LLM.
_ or -. See
Tools for validation, errors and the built-in tools.
3. Stream the answer
agent.stream() runs the agent like send() and returns an AgentRun: iterate
it for typed events (model text as it arrives, tool calls, step boundaries),
and await run.result for the same result send() returns.
4. Remember the conversation
agent.send() starts from an empty history on every call. agent.session()
keeps the transcript and passes it to the model on each send().
5. Ask before a risky action
Flag a toolneedsApproval and the run pauses before calling it. send()
resolves with finishReason: 'awaiting-approval' and an approvalId; your code
(or a human) then approves or rejects the call and the run continues. Here
mockModel from lousho/testing scripts the model’s turns
exactly, so the tool call is certain.
approved: false (and a note) to reject the call instead. See
Approvals for predicates, stores and deciding from another
process.
6. Test it offline
The agent from the last step is already testable:mockModel records every
request the agent made, so you can assert on what the model was sent as well as
on the result. No network, no key.
recordReplay.
7. Custom provider
model: 'provider/model' is the shortcut; pass provider instead when you
have your own LLMProvider or want the mock for tests.
resolveProvider('<provider>/<model>') is the function model uses under the
hood. This snippet uses OpenAI when OPENAI_API_KEY is set and falls back to
the mock provider otherwise - the same pattern the runnable
examples use.
8. Declarative agents: spec files
An agent can also be described as plain data - anAgentSpec - and turned
into a live agent with specToAgent(). The same shape can be written as a
YAML or JSON file and loaded with loadSpec().
agent.yaml:
/, POST /chat,
hot reload on save) and builds into a deployable server:
Advanced: the executor API
createAgent() is the recommended entry point. It sits on top of
AgentBuilder and the static AgentExecutor.execute(), which take a few
lower-level options createAgent() does not, such as temperature and
maxTokens. See The executor API.
Next steps
- Configuration - every spec field, provider env var and CLI flag.
- Deployment -
lousho buildtargets (Node server, Docker, Cloudflare Workers). - API Overview - the main exports and where to find full API reference.
- Examples - runnable example agents.