All configuration options for LLMist client and agents.
const client = new LLMist (options);
Option
Type
Default
Description
adapters
ProviderAdapter[]
[]
Manual provider adapters
defaultProvider
string
First adapter
Default provider prefix
autoDiscoverProviders
boolean
true
Auto-discover from env vars
customModels
ModelSpec[]
[]
Custom model specifications
const client = new LLMist ( {
autoDiscoverProviders: true ,
defaultProvider: ' anthropic ' ,
modelId: ' ft:gpt-5:my-org ' ,
pricing: { input: 5.0 , output: 15.0 },
knowledgeCutoff: ' 2024-08 ' ,
features: { streaming: true , functionCalling: true , vision: true },
Method
Type
Default
Description
.withModel(model)
string
openai:gpt-5-nano
Model name or alias
.withSystem(prompt)
string
none
System prompt
.withTemperature(temp)
number
Provider default
Temperature (0-1)
.withMaxIterations(n)
number
10
Max agent loop iterations
Method
Type
Description
.withGadgets(...gadgets)
GadgetOrClass[]
Register gadgets (classes or instances)
.withDefaultGadgetTimeout(ms)
number
Default timeout for all gadgets
Method
Type
Description
.withSkills(registry)
SkillRegistry
Register all skills from a registry
.withSkill(name, args?)
string, string?
Pre-activate a specific skill by name
.withSkillsFrom(dir)
string
Scan a directory and register all skills found (can be called multiple times)
Method
Type
Default
Description
.withStopOnGadgetError(stop)
boolean
true
Stop on first gadget error
.withErrorHandler(handler)
Function
none
Custom error handling
.withRetry(config)
RetryConfig
Enabled, 3 retries
Configure retry with exponential backoff
.withoutRetry()
-
-
Disable automatic retry
. withErrorHandler ( ( ctx ) => {
// Return true to continue, false to stop
return ctx . errorType !== ' execution ' ;
// Configure retry behavior for rate limits and transient errors
retries: 5 , // Max retry attempts
minTimeout: 2000 , // Initial delay (ms)
maxTimeout: 60000 , // Max delay (ms)
onRetry : ( error , attempt ) => console . log ( ` Retry ${ attempt } ` ),
// Disable retry entirely
Method
Type
Description
.withHistory(messages)
HistoryMessage[]
Add conversation history
.addMessage(message)
HistoryMessage
Add single message
.withSyntheticGadgetCall(...)
See below
Pre-seed gadget results
{ assistant: ' Hi there! ' },
Inject synthetic gadget calls into conversation history so the agent starts with context already visible. This is useful for:
Codebase context : Show directory structure before the agent starts
In-context learning : Demonstrate expected gadget call patterns
Workflow bootstrapping : Pre-populate known data
// SDK: Pre-seed a ListDirectory result
. withGadgets (ListDirectory, ReadFile)
. withSyntheticGadgetCall (
' ListDirectory ' , // Gadget name
{ directoryPath: ' . ' , maxDepth: 2 }, // Parameters "used"
' ./src \n ./package.json \n ./README.md ' , // Pre-filled result
' gc_init_1 ' // Invocation ID
. ask ( ' Analyze this project ' );
Or in CLI config (~/.llmist/cli.toml):
system = " You are a code analyst. "
{ gadget = " ListDirectory " , parameters = { directoryPath = " . " , maxDepth = 2 }, result = """
The agent will see this as if it already called ListDirectory and received the result, providing immediate context without using an iteration.
Method
Type
Description
.withHooks(hooks)
AgentHooks
Lifecycle hooks
.withLogger(logger)
Logger
Custom tslog logger
.onHumanInput(handler)
Function
Human input handler
.withTrailingMessage(message)
string | Function
Ephemeral message appended to each request
Add an ephemeral message that appears at the end of each LLM request but is not persisted to conversation history. This is useful for:
Reminders : Instructions that need to be reinforced on every turn
Context injection : Current state or status that changes independently
Format enforcement : “Always respond in JSON format”
. withTrailingMessage ( " Always respond in JSON format. " )
// Dynamic message based on iteration
. withTrailingMessage ( ( ctx ) =>
` [Iteration ${ ctx . iteration } / ${ ctx . maxIterations } ] Focus on completing the current task. `
// Inject current status/state
let taskStatus = " pending " ;
. withTrailingMessage ( () =>
` [Current task status: ${ taskStatus } ] Adjust your approach based on this status. `
Key behavior:
Message is ephemeral - only appears in the current LLM request
Not persisted to conversation history
Composes with existing beforeLLMCall hooks
Respects “skip” action from existing controllers
Method
Type
Description
.withPromptConfig(config)
PromptTemplateConfig
Custom prompt templates
.withGadgetStartPrefix(prefix)
string
Custom gadget marker start (default: !!!GADGET_START:)
.withGadgetEndPrefix(prefix)
string
Custom gadget marker end (default: !!!GADGET_END)
.withGadgetArgPrefix(prefix)
string
Custom argument prefix for block format (default: !!!ARG:)
.withTextOnlyHandler(handler)
TextOnlyHandler
Handle text-only responses
.withTextWithGadgetsHandler(handler)
object
Wrap text alongside gadget calls
All three marker prefixes can be customized if you need to avoid conflicts with your content or match existing systems:
. withGadgetStartPrefix ( " <<GADGET_START>> " )
. withGadgetEndPrefix ( " <<GADGET_END>> " )
. withGadgetArgPrefix ( " <<ARG>> " )
Or in CLI config (~/.llmist/cli.toml):
gadget-start-prefix = " <<GADGET_START>> "
gadget-end-prefix = " <<GADGET_END>> "
gadget-arg-prefix = " <<ARG>> "
Control how text responses are handled in the agent loop:
// Handle text-only responses (when LLM doesn't call any gadgets)
. withTextOnlyHandler ( " acknowledge " ) // Continue loop
. withTextOnlyHandler ( " terminate " ) // End loop (default)
. withTextOnlyHandler ( " wait_for_input " ) // Ask for human input
// Wrap text that accompanies gadget calls as synthetic gadget calls
// This keeps conversation history consistent and gadget-oriented
. withTextWithGadgetsHandler ({
parameterMapping : ( text ) => ({ message: text, done: false , type: " info " }),
resultMapping : ( text ) => ` ℹ️ ${ text } ` , // Optional: format the result
The textWithGadgetsHandler is useful when you want text that appears alongside gadget calls to also appear in the conversation history as an explicit gadget call. This helps LLMs maintain a consistent “gadget invocation” mindset.
Variable
Provider
Description
OPENAI_API_KEY
OpenAI
OpenAI API key
ANTHROPIC_API_KEY
Anthropic
Anthropic API key
GEMINI_API_KEY
Gemini
Google Gemini API key
LLMist . complete (prompt, options);
LLMist . stream (prompt, options);
Option
Type
Default
Description
model
string
gpt-5-nano
Model name or alias
temperature
number
Provider default
Temperature (0-1)
systemPrompt
string
none
System prompt
maxTokens
number
Provider default
Max tokens to generate
Method
Returns
Description
.ask(prompt)
Agent
Create agent (don’t run)
.askAndCollect(prompt)
Promise<string>
Run and collect text
.askWith(prompt, handlers)
Promise<void>
Run with event handlers