Skip to main content

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:
To try a locally packed 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):
That is the current 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).
Leave 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 with defineTool(): 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.
Names must be 1-64 characters of letters, digits, _ 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.
See Streaming for the full event list, cancellation and sending the events to a browser.

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().
Pass a store to keep sessions across restarts; see Sessions.

5. Ask before a risky action

Flag a tool needsApproval 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.
Pass 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.
In a real project, put the same assertions in a vitest or Jest test. See Testing for tool-call flows, error turns and 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 - an AgentSpec - and turned into a live agent with specToAgent(). The same shape can be written as a YAML or JSON file and loaded with loadSpec().
Saved as agent.yaml:
the same spec runs in the local dev server (chat UI at /, 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 build targets (Node server, Docker, Cloudflare Workers).
  • API Overview - the main exports and where to find full API reference.
  • Examples - runnable example agents.