Quickstart

Connect to a model and get your first reply with a minimal example. This guide uses OpenAI and requires Node.js 22+ and a TypeScript project configured for ESM.

Install dependencies

npm install @yong_xie/lighter
npm install --save-dev tsx

These examples use tsx to run TypeScript. Skip it if your project already has a TypeScript runner.

Set your API key

In your terminal, set an API key and a model ID available to your account:

export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="your-model-id"

Create and run an agent

Create hello.ts:

import { Agent, Model, OpenAIProvider, UserMessage } from "@yong_xie/lighter";

// Connect to OpenAI with the API key and model ID configured above.
const provider = new OpenAIProvider(
  process.env.OPENAI_API_KEY!,
  process.env.OPENAI_MODEL!,
);

// Wrap the provider in a Model, then create an Agent.
const model = new Model(provider);
const agent = new Agent({ model });

// Represent user input with UserMessage. run() waits for the run to finish.
const result = await agent.run({
  messages: [new UserMessage("Name a bookstore on the moon. Return only the name.")],
});

if (result.status === "failed") {
  // Read error on failure and exit with a failure status.
  console.error("Run failed:", result.error);
  process.exitCode = 1;
} else {
  // There are no tools here, so the last new message is the assistant reply.
  const reply = result.messages.at(-1);
  if (reply?.role === "assistant") {
    console.log(reply.content);
  }
}

Provider connects to the model service, Model wraps model calls, and Agent accepts messages and runs the loop. Call run() to get the result.

Run it in the same terminal:

node --import tsx hello.ts

The output will look something like this. The actual name is generated by the model:

Moonlight Books

Understand the result

• status is "completed" when the run completes. When it is "failed", inspect error for the cause.
• messages contains only messages added during this run, not the input history.
• This example has no tools. On success, the last new message is the assistant reply, with its text in content.