SDK quickstart

Get an agent running with @poolot/lily-web in a few lines.

1. Install

npm install @poolot/lily-web

2. Create an agent

createLilyAgent is async and resolves to an agent handle. apiKey is required — get one from platform.pathvela.com (see Your Pathvela account).

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

const agent = await createLilyAgent({
  apiKey: process.env.POOLOT_API_KEY,
  model: 'poolot-standard',
  systemPrompt: 'You are a concise assistant for the Acme app.',
})

3. Run it

Pass a conversation (an array of messages) and get a result:

const result = await agent.runDetailed([
  { role: 'user', content: 'What are three good names for a task tracker?' },
])

console.log(result.status)     // 'completed'
console.log(result.outputText) // the answer
console.log(result.usage)      // { inputTokens, outputTokens, cachedInputTokens, calls }

For just the text, run is a shortcut:

const text = await agent.run([{ role: 'user', content: 'Say hi.' }])

4. Stream tokens into your UI

For a chat experience, stream tokens as they're generated and react to events:

await agent.runStreaming(
  [{ role: 'user', content: 'Explain WebAssembly in a paragraph.' }],
  (token) => appendToUI(token),                 // each token
  (event) => {                                  // optional: lifecycle events
    if (event.type === 'tool_call') showToolBadge(event.name)
    if (event.type === 'done') markComplete()
  },
)

5. Continue the conversation

continue runs another turn on the same agent, keeping the accumulated history:

await agent.run([{ role: 'user', content: 'Draft a launch email.' }])
const follow = await agent.continue('Make it shorter and warmer.')
console.log(follow.outputText)

Browser note

In a server-rendered app, import the SDK on the client only so the WebAssembly engine never loads during SSR:

const { createLilyAgent } = await import('@poolot/lily-web')

Next