Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt

Use this file to discover all available pages before exploring further.

Overview

By default, every Lua agent uses Google Gemini 2.5 Flash. The model property on LuaAgent lets you choose a different model or select one dynamically based on the request context.
export const agent = new LuaAgent({
  name: 'my-agent',
  persona: '...',
  model: 'openai/gpt-5.4',  // ← add this
  skills: [mySkill]
});
Lua manages the API credentials. You don’t need to configure any API keys or provider accounts — Lua handles all LLM infrastructure on your behalf.Support for user-provided API keys (Bring Your Own Key) is coming in a future release.

Available Models

Google (Vertex AI)

Model stringContext windowNotes
google/gemini-2.5-flash1M tokensDefault — fast reasoning, best price-performance
google/gemini-2.5-pro1M tokensAdvanced reasoning for complex analysis
google/gemini-2.5-flash-lite1M tokensBudget-friendly in the 2.5 family
google/gemini-3.1-pro-preview1M tokensMost capable Gemini (preview)
google/gemini-3-flash-preview1M tokensNext-gen frontier flash (preview)
google/gemini-3.1-flash-lite-preview1M tokensNext-gen lite (preview)

OpenAI

Model stringContext windowNotes
openai/gpt-5.41.1M tokensCurrent flagship
openai/gpt-5.4-mini400K tokensFast flagship variant
openai/gpt-5.4-nano400K tokensUltra-low-latency
openai/gpt-5400K tokensStrong general-purpose
openai/gpt-5-mini400K tokensCompact GPT-5
openai/gpt-4.11M tokensStable, previous gen
openai/gpt-4.1-mini1M tokensBudget variant of 4.1
openai/gpt-4.1-nano1M tokensFastest 4.1 variant
openai/o3200K tokensMost powerful reasoning
openai/o3-mini200K tokensFast reasoning
openai/o3-pro200K tokensPremium reasoning
openai/o4-mini200K tokensLatest cost-efficient reasoning

Anthropic

Model stringContext windowNotes
anthropic/claude-opus-4-61M tokensMost intelligent
anthropic/claude-sonnet-4-61M tokensBest speed/intelligence balance
anthropic/claude-haiku-4-5200K tokensFastest model
anthropic/claude-opus-4-5200K tokensPrevious gen, still active
anthropic/claude-sonnet-4-5200K tokensPrevious gen, still active
anthropic/claude-opus-4-1200K tokensOlder gen, still active

DeepSeek

Model stringContext windowNotes
deepseek/deepseek-chat131K tokensDeepSeek-V3, general purpose
deepseek/deepseek-reasoner128K tokensDeepSeek-R1, reasoning

Groq

Model stringContext windowNotes
groq/llama-3.3-70b-versatile131K tokensProduction, tool use capable
groq/meta-llama/llama-4-scout-17b-16e-instruct131K tokensLatest Llama 4
groq/openai/gpt-oss-120b131K tokensGPT-OSS on Groq LPU hardware
groq/groq/compound131K tokensGroq Compound agentic system
groq/llama-3.1-8b-instant131K tokensFast, budget-friendly

xAI (Grok)

Model stringContext windowNotes
xai/grok-4256K tokensCurrent flagship
xai/grok-4-fast2M tokensFast variant
xai/grok-3131K tokensPrevious gen, still active
xai/grok-3-mini131K tokensPrevious gen mini
xai/grok-3-mini-fast131K tokensPrevious gen fast

Alibaba (Qwen)

Model stringContext windowNotes
alibaba/qwen3.6-plus1M tokensLatest flagship (Apr 2026)
alibaba/qwen3-max262K tokensFlagship
alibaba/qwen3-235b-a22b131K tokensLarge MoE model
alibaba/qwen3-32b131K tokensMid-size, fast
alibaba/qwq-plus131K tokensReasoning model

ZhipuAI (GLM)

Model stringContext windowNotes
zhipuai/glm-5.1203K tokensLatest
zhipuai/glm-580K tokensFlagship (Feb 2026)
zhipuai/glm-5-turbo203K tokensFast variant
zhipuai/glm-4.7203K tokensPrevious gen
zhipuai/glm-4.7-flash203K tokensPrevious gen flash
zhipuai/glm-4.6205K tokensPrevious gen
zhipuai/glm-4.5131K tokensPrevious gen
zhipuai/glm-4.5-air131K tokensPrevious gen lite
Fallback routing. If a model is not in Lua’s approved list, the request is automatically routed through OpenRouter as a best-effort fallback. If that also isn’t available, the request falls back to the default model (google/gemini-2.5-flash).

Static Model

The simplest form — one model for all requests:
export const agent = new LuaAgent({
  name: 'support-agent',
  persona: '...',
  model: 'openai/gpt-5.4',
  skills: [supportSkill]
});
When to use: When you want a specific model across all users and channels.

Dynamic Model Resolver

Use a function to select the model per request. The resolver receives the full request with access to all platform APIs — User, Baskets, Products, Data, and more.
export const agent = new LuaAgent({
  name: 'smart-agent',
  persona: '...',
  model: async (request) => {
    const user = await User.get();
    return user.data?.isPremium ? 'openai/gpt-5.4' : 'google/gemini-2.5-flash';
  },
  skills: [mySkill]
});
The resolver must return a 'provider/model' string synchronously or asynchronously.

Common Patterns

Premium vs free users

model: async (request) => {
  const user = await User.get();
  const tier = user.data?.subscriptionTier;

  if (tier === 'pro') return 'openai/gpt-5.4';          // flagship
  if (tier === 'standard') return 'openai/gpt-4.1';     // 1M context, balanced
  return 'google/gemini-2.5-flash';                      // default
}

Channel-based selection

model: (request) => {
  // Use a faster/cheaper model for voice channels
  if (request.channel === 'voice') return 'google/gemini-2.5-flash-lite';
  // Use a more capable model for complex web requests
  return 'openai/gpt-5.4';
}

Content-based routing

model: async (request) => {
  // Use a model with large context for document-heavy workflows
  const basketCount = await Baskets.getCount();
  if (basketCount > 50) return 'openai/gpt-4.1';  // 1M context
  return 'openai/gpt-5.4-mini';
}

Environment-based

import { env } from 'lua-cli';

model: env('PREFERRED_MODEL') || 'google/gemini-2.5-flash'

Default Model

If you don’t set model, your agent uses google/gemini-2.5-flash. This is a fast, capable model with a 1M token context window — suitable for most use cases.

LuaAgent API

Full constructor reference including the model param

Platform APIs

APIs available inside a model resolver function