createLilyAgent reference

createLilyAgent is the entry point of the SDK. It creates and initializes an agent and resolves to a LilyAgentHandle you drive from your code.

function createLilyAgent(opts?: CreateAgentOptions): Promise<LilyAgentHandle>

It is asynchronous — it initializes the engine (loading the WebAssembly module in the browser, or selecting a backend on Node) before resolving. apiKey is required at runtime; creating an agent without one throws createLilyAgent: apiKey required.

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

const agent = await createLilyAgent({
  apiKey: process.env.POOLOT_API_KEY,
  model: 'poolot-standard',
})

Options

Common (browser and Node)

Engine loading

Note on cdnFallback: the shipped type comment documents the default as true, while the package README lists it as false. Set it explicitly if it matters to you, and serve your own assets with assetBase in production.

Filesystem, storage & exec (both environments)

These work in the browser and on Node — see Browser vs Node for how each is backed in-page.

Node / harness-only

These are ignored in the browser.

The agent handle

createLilyAgent resolves to a LilyAgentHandle:

interface LilyAgentHandle {
  environment: LilyEnvironment
  runDetailed(messages: LilyMessage[], opts?: LilyRunOptions): Promise<LilyRunResult>
  continue(input?: string | LilyMessage, opts?: LilyRunOptions): Promise<LilyRunResult>
  run(messages: LilyMessage[], maxSteps?: number): Promise<string>
  runStreaming(
    messages: LilyMessage[],
    onToken: (text: string) => void,
    onEvent?: (event: LilyEvent) => void,
    maxSteps?: number,
  ): Promise<string>
  complete(messages: LilyMessage[]): Promise<string>
  snapshot(): { status: string; iterations: number; messages: LilyMessage[]; usage: LilyUsage }
  restore(messages: LilyMessage[]): number
  getMe(): Promise<{ userId: string; email?: string; name?: string; tier: string; balance: number; capabilities?: { byok: boolean; providers: 'any' | 'poolot' } }>
  abort(): void
}

Methods

• runDetailed(messages, opts?) — run the agent over a conversation and get the full LilyRunResult: text, status, usage, tool calls, and the resulting messages. This is the method to reach for when you want everything.
• run(messages, maxSteps?) — a convenience wrapper that resolves to just the output text.
• runStreaming(messages, onToken, onEvent?, maxSteps?) — like run, but streams generated text through onToken and lifecycle events through onEvent. Resolves to the final text.
• complete(messages) — a single completion with no tool loop.
• continue(input?, opts?) — run another turn, keeping the agent's accumulated history. Pass a string or a LilyMessage.
• snapshot() — capture the current status, iteration count, messages, and usage.
• restore(messages) — reset the conversation to a given message list; returns the count restored.
• getMe() — fetch the account identity, tier, credit balance, and capabilities.
• abort() — cancel the run in flight, including any tool work.

There is no sendMessage/getMessages method. You send by passing a messages array (or continue(input)), and you read the conversation from snapshot().messages or LilyRunResult.messages.

Run options

runDetailed, runStreaming, and continue accept a LilyRunOptions:

LilyRunResult

interface LilyRunResult {
  status: 'completed' | 'aborted' | 'max_steps' | 'failed'
        | 'budget_tokens' | 'budget_calls' | 'too_many_failures' | 'repeated_tool_call'
  outputText: string
  messages: LilyMessage[]
  toolCalls: LilyToolCall[]
  usage: LilyUsage | null
  iterations: number
  durationMs: number
  result?: unknown        // from a run-completing tool
  completedBy?: string | null
  reasoning?: string      // both backends, reasoning-capable routes only
  sessionId?: string | null // harness only
}

usage is LilyUsage — { inputTokens, outputTokens, cachedInputTokens, calls } — or null when the backend reported none (deliberately distinct from all-zeroes).

See also

• Events and messages — LilyMessage and the LilyEvent union.
• TypeScript types — the full exported surface.
• Examples — using these methods in real code.