SDK overview

@poolot/lily-web is the Pathvela SDK. It embeds the same agent the CLI runs directly into your application — in the browser (via WebAssembly) or on Node. You create an agent with one function and drive it from your own code.

Install

npm install @poolot/lily-web

The package is ESM, written in TypeScript, and ships built bundles plus .d.ts type definitions. One import works everywhere:

import { createLilyAgent } from '@poolot/lily-web'

The shape of it

import { createLilyAgent } from '@poolot/lily-web'

// 1. Create an agent (async).
const agent = await createLilyAgent({
  apiKey,
  model: 'poolot-standard',
})

// 2. Run it. Pass a conversation, get a result back.
const result = await agent.runDetailed([
  { role: 'user', content: 'Summarize this page in three bullets.' },
])

result.outputText // the answer
result.usage      // token usage for metering
result.messages   // the full conversation, including tool steps

createLilyAgent returns a LilyAgentHandle — an object with methods to run the agent, stream tokens, continue a conversation, snapshot and restore state, and read your account. See the createLilyAgent reference and Events and messages.

Runs in the browser

The whole agentic loop — planning, tool calls, retries — can run client-side from a small WebAssembly engine bundled with the package. The only network call is to the Pathvela agent backend. That means no server of your own is required to run an agent in a web app; you just need a valid API key (typically a signed-in user token). See Browser vs Node.

Runs on Node

On the server, the SDK runs on a local harness when one is installed (a full tool set, real shell, disk-backed sessions), and otherwise falls back to the same WebAssembly engine. The same code works either way. See Browser vs Node.

What's in this section