AI - Lua CLI

AI.generate runs one model call with a prompt you supply and returns the text or the full result. The call skips the agent’s persona, skills, and processors; to run a whole turn of an agent, use Agents.invoke. Available in tools, jobs, webhooks, triggers, processors, and workflow code steps. Verified against lua-cli 3.33.0.

import { AI } from 'lua-cli';

Quick example

The short form returns text; the options form returns the full result.

import { AI } from 'lua-cli';

const ticketBody = 'Login fails after the password reset email arrives.';
const summary = await AI.generate('Reply in one sentence.', [{ type: 'text', text: ticketBody }]);

const result = await AI.generate({
  model: 'google/gemini-3.8-flash',
  system: 'You are concise.',
  prompt: 'What is the weather in London today?',
});

Methods

generate(prompt, content?)

Generates text and returns it as a string.

AI.generate(prompt: string, content?: UserContent): Promise<string>

string

required

The user prompt when called alone. When content is given, the system instruction instead.

UserContent

The user message: a string, or an array of AI SDK v5 parts. Parts are { type: 'text', text }, { type: 'image', image, mediaType? }, and { type: 'file', data, mediaType, filename? }, where image and data are a URL string, a base64 string, or a Buffer.

Returns — the generated text, the same value as text on the options form. Example

import { AI } from 'lua-cli';

const description = await AI.generate('Describe the photo in two sentences.', [
  { type: 'text', text: 'What is in this photo?' },
  { type: 'image', image: 'https://example.com/photo.jpg', mediaType: 'image/jpeg' },
]);

Errors — the same as generate(options).

generate(options)

Generates text with explicit model settings and returns the full result.

AI.generate(options: AiGenerateInput): Promise<AiGenerateOutput>

string

default:"alibaba/qwen3.8-flash"

A model code in provider/model form, as listed by lua models list. Defaults to the platform default model, not to the agent’s model. A code the platform doesn’t approve falls back to the default.

string

System instruction.

string

Plain user prompt. Pass prompt or messages, not both.

ModelMessage[]

AI SDK v5 messages, { role, content }, with the same part shapes as content on the short form. The server validates them; a malformed part is rejected with a 400 that names its path, such as messages[0].content[1].

number

Sampling temperature. The accepted range is the provider’s.

number

Maximum number of tokens to generate.

{ schema: AiGenerateJsonSchema }

A JSON Schema the response must match; the parsed object lands on output. The schema needs a top-level type: "object". On Google models, setting it turns Google Search grounding off for that call.

Returns

AiGenerateOutput

Optional fields are omitted when empty.

Show properties

string

The generated text.

FinishReason

One of stop, length, content-filter, tool-calls, error, other, unknown.

LanguageModelUsage

inputTokens, outputTokens, totalTokens, and optionally reasoningTokens and cachedInputTokens. Each is undefined when the provider doesn’t report it.

unknown

The parsed JSON when structuredOutput was set and finishReason is stop. It is parsed, not validated against the schema; validate it yourself.

AiGenerateSource[]

Google Search grounding sources, Google models only: { sourceType: 'url', id, url, title? }.

ReasoningOutput[]

Reasoning steps when the model exposes them; reasoningText is their concatenation.

AiGenerateToolCall[]

Tool calls the model made, { type: 'tool-call', toolCallId, toolName, input }. toolResults holds the matching { type: 'tool-result', toolCallId, toolName, output, isError? } entries.

CallWarning[]

Provider warnings, for example an unsupported setting.

Example

import { AI } from 'lua-cli';
import { z } from 'zod';

const ticketBody = 'Login fails after the password reset email arrives.';
const SentimentSchema = z.object({
  sentiment: z.enum(['positive', 'negative', 'neutral']),
  score: z.number().min(0).max(1),
});

const result = await AI.generate({
  system: 'Classify the sentiment of the message.',
  prompt: ticketBody,
  temperature: 0,
  structuredOutput: {
    schema: {
      type: 'object',
      properties: {
        sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
        score: { type: 'number', minimum: 0, maximum: 1 },
      },
      required: ['sentiment', 'score'],
    },
  },
});

const parsed = SentimentSchema.safeParse(result.output);

Errors — the call throws an Error:

Invalid input: structuredOutput.schema must be a JSON Schema with top-level type "object", or a malformed messages part. Fix the request; retrying doesn’t help.
The provider refused the request as sent (a model the provider doesn’t serve, a refused prompt): the platform reports it as PROVIDER_REJECTED with transient: false. Retrying unchanged fails the same way.
The provider is unavailable (408, 429, 5xx, or no answer): the platform retries on the next model in its fallback chain. When every model fails, a deployed agent sees Every model in the fallback chain failed; lua test sees the platform’s UPSTREAM_UNAVAILABLE error, … is temporarily unavailable — retry in a moment.
No message from the server: AI generation failed.

Types

AiGenerateInput, AiGenerateOutput, AiGenerateStructuredOutput, AiGenerateJsonSchema (a Record<string, unknown>), AiGenerateSource, AiGenerateToolCall, and AiGenerateToolResult are exported from lua-cli. UserContent, ModelMessage, FinishReason, LanguageModelUsage, ReasoningOutput, and CallWarning are the AI SDK v5 types of the same names; you don’t need to import them to call AI.generate.

SDK

CLI

REST API

AI

Quick example

Methods

generate(prompt, content?)

generate(options)

Types

See also

​Quick example

​Methods

​generate(prompt, content?)

​generate(options)

​Types

​See also

Quick example

Methods

generate(prompt, content?)

generate(options)

Types

See also