AgentBuilder

Defined in: agent/builder.ts:65

Fluent builder for creating agents.

Provides a chainable API for configuring and creating agents, making the code more expressive and easier to read.

Constructors

Constructor

new AgentBuilder(client?): AgentBuilder

Defined in: agent/builder.ts:106

Parameters

client?

LLMist

Returns

AgentBuilder

Methods

addMessage()

addMessage(message): this

Defined in: agent/builder.ts:275

Add a single message to the conversation history.

Parameters

message

HistoryMessage

Single history message

Returns

this

This builder for chaining

Example

.addMessage({ user: "Hello" })
.addMessage({ assistant: "Hi there!" })

ask()

ask(userPrompt): Agent

Defined in: agent/builder.ts:1017

Parameters

userPrompt

string

Returns

Agent

askAndCollect()

askAndCollect(userPrompt): Promise<string>

Defined in: agent/builder.ts:1124

Build, run, and collect only the text response. Convenient for simple queries where you just want the final answer.

Parameters

userPrompt

string

User’s question or request

Returns

Promise<string>

Promise resolving to the complete text response

Example

const answer = await LLMist.createAgent()
  .withModel("gpt4-mini")
  .withGadgets(Calculator)
  .askAndCollect("What is 42 * 7?");

console.log(answer); // "294"

askWith()

askWith(userPrompt, handlers): Promise<void>

Defined in: agent/builder.ts:1147

Build and run with event handlers. Combines agent creation and event handling in one call.

Parameters

userPrompt

string

User’s question or request

handlers

EventHandlers

Event handlers

Returns

Promise<void>

Example

await LLMist.createAgent()
  .withModel("sonnet")
  .withGadgets(Calculator)
  .askWith("What is 2+2?", {
    onText: (text) => console.log("LLM:", text),
    onGadgetResult: (result) => console.log("Result:", result.result),
  });

askWithContent()

askWithContent(content): Agent

Defined in: agent/builder.ts:1102

Build and return an Agent configured with multimodal content. More flexible than askWithImage - accepts any combination of content parts.

Parameters

content

ContentPart[]

Array of content parts (text, images, audio)

Returns

Agent

A configured Agent ready for execution

Example

import { text, imageFromBuffer, audioFromBuffer } from "llmist";

const agent = LLMist.createAgent()
  .withModel("gemini:gemini-2.5-flash")
  .askWithContent([
    text("Describe this image and transcribe the audio:"),
    imageFromBuffer(imageData),
    audioFromBuffer(audioData),
  ]);

for await (const event of agent.run()) {
  // handle events
}

askWithImage()

askWithImage(textPrompt, imageData, mimeType?): Agent

Defined in: agent/builder.ts:1046

Build and create the agent with a multimodal user prompt (text + image). Returns the Agent instance ready to run.

Parameters

textPrompt

string

Text prompt describing what to do with the image

imageData

Image data (Buffer, Uint8Array, or base64 string)

string | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>

mimeType?

ImageMimeType

Optional MIME type (auto-detected if not provided)

Returns

Agent

Configured Agent instance

Example

const agent = LLMist.createAgent()
  .withModel("gpt-4o")
  .withSystem("You analyze images")
  .askWithImage(
    "What's in this image?",
    await fs.readFile("photo.jpg")
  );

for await (const event of agent.run()) {
  // handle events
}

build()

build(): Agent

Defined in: agent/builder.ts:1179

Build the agent without a user prompt.

Returns an Agent instance that can be inspected (e.g., check registered gadgets) but cannot be run without first calling .ask(prompt).

This is useful for:

Testing: Inspect the registry, configuration, etc.
Advanced use cases: Build agent configuration separately from execution

Returns

Agent

Configured Agent instance (without user prompt)

Example

// Build agent for inspection
const agent = new AgentBuilder()
  .withModel("sonnet")
  .withGadgets(Calculator, Weather)
  .build();

// Inspect registered gadgets
console.log(agent.getRegistry().getNames()); // ['Calculator', 'Weather']

// Note: Calling agent.run() will throw an error
// Use .ask(prompt) instead if you want to run the agent

clearHistory()

clearHistory(): this

Defined in: agent/builder.ts:291

Clear any previously set conversation history. Used before setting new cumulative history in REPL mode.

Returns

this

This builder for chaining

Example

// Reset history before setting new cumulative history
builder.clearHistory().withHistory(cumulativeHistory);

continueFrom()

continueFrom(agent): this

Defined in: agent/builder.ts:321

Continue conversation from a previous agent’s history. Extracts full conversation history and sets it as initial messages.

This is the recommended way to implement REPL session continuation. It automatically handles history extraction and format conversion.

Parameters

agent

Agent

The previous agent to continue from

Returns

this

This builder for chaining

Example

// REPL loop with session continuity
let previousAgent: Agent | null = null;

while (true) {
  if (previousAgent) {
    builder.continueFrom(previousAgent);
  }
  const agent = builder.ask(prompt);
  await runAgent(agent);
  previousAgent = agent;
}

onHumanInput()

onHumanInput(handler): this

Defined in: agent/builder.ts:351

Set the human input handler for interactive conversations.

Parameters

handler

(question) => Promise<string>

Function to handle human input requests

Returns

this

This builder for chaining

Example

.onHumanInput(async (question) => {
  return await promptUser(question);
})

withCompaction()

withCompaction(config): this

Defined in: agent/builder.ts:559

Configure context compaction.

Context compaction automatically manages conversation history to prevent context window overflow in long-running agent conversations.

Parameters

config

CompactionConfig

Compaction configuration options

Returns

this

This builder for chaining

Example

// Custom thresholds
.withCompaction({
  triggerThresholdPercent: 70,
  targetPercent: 40,
  preserveRecentTurns: 10,
})

// Different strategy
.withCompaction({
  strategy: 'sliding-window',
})

// With callback
.withCompaction({
  onCompaction: (event) => {
    console.log(`Saved ${event.tokensBefore - event.tokensAfter} tokens`);
  }
})

withDefaultGadgetTimeout()

withDefaultGadgetTimeout(timeoutMs): this

Defined in: agent/builder.ts:479

Set default timeout for gadget execution.

Parameters

timeoutMs

number

Timeout in milliseconds (must be non-negative)

Returns

this

This builder for chaining

Throws

If timeout is negative

Example

.withDefaultGadgetTimeout(5000) // 5 second timeout

withGadgetArgPrefix()

withGadgetArgPrefix(prefix): this

Defined in: agent/builder.ts:399

Set custom argument prefix for block format parameters.

Parameters

prefix

string

Custom prefix for argument markers (default: ”!!!ARG:“)

Returns

this

This builder for chaining

Example

.withGadgetArgPrefix("<<ARG>>")

withGadgetEndPrefix()

withGadgetEndPrefix(suffix): this

Defined in: agent/builder.ts:383

Set custom gadget marker suffix.

Parameters

suffix

string

Custom end suffix for gadget markers

Returns

this

This builder for chaining

Example

.withGadgetEndPrefix("<<GADGET_END>>")

withGadgetOutputLimit()

withGadgetOutputLimit(enabled): this

Defined in: agent/builder.ts:501

Enable or disable gadget output limiting.

When enabled, gadget outputs exceeding the configured limit are stored and can be browsed using the GadgetOutputViewer gadget.

Parameters

enabled

boolean

Whether to enable output limiting (default: true)

Returns

this

This builder for chaining

Example

.withGadgetOutputLimit(false) // Disable output limiting

withGadgetOutputLimitPercent()

withGadgetOutputLimitPercent(percent): this

Defined in: agent/builder.ts:520

Set the maximum gadget output as a percentage of the model’s context window.

Outputs exceeding this limit are stored for later browsing with GadgetOutputViewer.

Parameters

percent

number

Percentage of context window (1-100, default: 15)

Returns

this

This builder for chaining

Throws

If percent is not between 1 and 100

Example

.withGadgetOutputLimitPercent(25) // 25% of context window

withGadgets()

withGadgets(…gadgets): this

Defined in: agent/builder.ts:228

Add gadgets (classes or instances). Can be called multiple times to add more gadgets.

Parameters

gadgets

…GadgetOrClass[]

Gadget classes or instances

Returns

this

This builder for chaining

Example

.withGadgets(Calculator, Weather, Email)
.withGadgets(new Calculator(), new Weather())
.withGadgets(createGadget({ ... }))

withGadgetStartPrefix()

withGadgetStartPrefix(prefix): this

Defined in: agent/builder.ts:367

Set custom gadget marker prefix.

Parameters

prefix

string

Custom start prefix for gadget markers

Returns

this

This builder for chaining

Example

.withGadgetStartPrefix("<<GADGET_START>>")

withHistory()

withHistory(messages): this

Defined in: agent/builder.ts:250

Add conversation history messages. Useful for continuing previous conversations.

Parameters

messages

HistoryMessage[]

Array of history messages

Returns

this

This builder for chaining

Example

.withHistory([
  { user: "Hello" },
  { assistant: "Hi there!" },
  { user: "How are you?" },
  { assistant: "I'm doing well, thanks!" }
])

withHooks()

withHooks(hooks): this

Defined in: agent/builder.ts:190

Add hooks for agent lifecycle events.

Parameters

hooks

AgentHooks

Agent hooks configuration

Returns

this

This builder for chaining

Example

import { HookPresets } from 'llmist/hooks';

.withHooks(HookPresets.logging())
.withHooks(HookPresets.merge(
  HookPresets.logging(),
  HookPresets.timing()
))

withLogger()

withLogger(logger): this

Defined in: agent/builder.ts:168

Set logger instance.

Parameters

logger

Logger<ILogObj>

Logger instance

Returns

this

This builder for chaining

withMaxIterations()

withMaxIterations(max): this

Defined in: agent/builder.ts:157

Set maximum iterations.

Parameters

max

number

Maximum number of iterations

Returns

this

This builder for chaining

withModel()

withModel(model): this

Defined in: agent/builder.ts:124

Set the model to use. Supports aliases like “gpt4”, “sonnet”, “flash”.

Parameters

model

string

Model name or alias

Returns

this

This builder for chaining

Example

.withModel("sonnet")           // Alias
.withModel("gpt-5-nano")       // Auto-detects provider
.withModel("openai:gpt-5")     // Explicit provider

withoutCompaction()

withoutCompaction(): this

Defined in: agent/builder.ts:576

Disable context compaction.

By default, compaction is enabled. Use this method to explicitly disable it.

Returns

this

This builder for chaining

Example

.withoutCompaction() // Disable automatic compaction

withoutRetry()

withoutRetry(): this

Defined in: agent/builder.ts:632

Disable automatic retry for LLM API calls.

By default, retry is enabled. Use this method to explicitly disable it.

Returns

this

This builder for chaining

Example

.withoutRetry() // Disable automatic retry

withParentContext()

withParentContext(ctx, depth): this

Defined in: agent/builder.ts:762

Enable automatic subagent event forwarding to parent agent.

When building a subagent inside a gadget, call this method to automatically forward all LLM calls and gadget events to the parent agent. This enables hierarchical progress display without any manual event handling.

The method extracts invocationId and onSubagentEvent from the execution context and sets up automatic forwarding via hooks and event wrapping.

NEW: Shared Tree Model - When the parent provides an ExecutionTree via context, the subagent shares that tree instead of creating its own. This enables:

Unified cost tracking across all nesting levels
Automatic media aggregation via tree.getSubtreeMedia(nodeId)
Real-time visibility of nested execution in the parent

Signal Forwarding - When parent context includes a signal, it’s automatically forwarded to the subagent for proper cancellation propagation.

Parameters

ctx

ExecutionContext

ExecutionContext passed to the gadget’s execute() method

depth

number = 1

Nesting depth (default: 1 for direct child)

Returns

this

This builder for chaining

Example

// In a subagent gadget like BrowseWeb - ONE LINE enables auto-forwarding:
execute: async (params, ctx) => {
  const agent = new AgentBuilder(client)
    .withModel(model)
    .withGadgets(Navigate, Click, Screenshot)
    .withParentContext(ctx)  // <-- This is all you need!
    .ask(params.task);

  for await (const event of agent.run()) {
    // Events automatically forwarded - just process normally
    if (event.type === "text") {
      result = event.content;
    }
  }

  // After subagent completes, costs are automatically aggregated
  // No manual tracking needed - use tree methods:
  const totalCost = ctx.tree?.getSubtreeCost(ctx.nodeId!);
  const allMedia = ctx.tree?.getSubtreeMedia(ctx.nodeId!);
}

withPromptTemplateConfig()

withPromptTemplateConfig(config): this

Defined in: agent/builder.ts:209

Configure custom prompts for gadget system messages.

Parameters

config

PromptTemplateConfig

Prompt configuration object

Returns

this

This builder for chaining

Example

.withPromptTemplateConfig({
  mainInstruction: "Use the gadget markers below:",
  rules: ["Always use markers", "Never use function calling"]
})

withRetry()

withRetry(config): this

Defined in: agent/builder.ts:615

Configure retry behavior for LLM API calls.

Retry is enabled by default with conservative settings (3 retries, exponential backoff). Use this method to customize retry behavior for rate limits, timeouts, and transient errors.

Parameters

config

RetryConfig

Retry configuration options

Returns

this

This builder for chaining

Example

// Custom retry configuration
.withRetry({
  retries: 5,
  minTimeout: 2000,
  maxTimeout: 60000,
})

// With monitoring callbacks
.withRetry({
  onRetry: (error, attempt) => {
    console.log(`Retry ${attempt}: ${error.message}`);
  },
  onRetriesExhausted: (error, attempts) => {
    alerting.warn(`Failed after ${attempts} attempts`);
  }
})

// Custom retry logic
.withRetry({
  shouldRetry: (error) => error.message.includes('429'),
})

withSignal()

withSignal(signal): this

Defined in: agent/builder.ts:662

Set an abort signal for cancelling requests mid-flight.

When the signal is aborted, the current LLM request will be cancelled and the agent loop will exit gracefully.

Parameters

signal

AbortSignal

AbortSignal from an AbortController

Returns

this

This builder for chaining

Example

const controller = new AbortController();

// Cancel after 30 seconds
setTimeout(() => controller.abort(), 30000);

const agent = LLMist.createAgent()
  .withModel("sonnet")
  .withSignal(controller.signal)
  .ask("Write a long story");

// Or cancel on user action
document.getElementById("cancel").onclick = () => controller.abort();

withSubagentConfig()

withSubagentConfig(config): this

Defined in: agent/builder.ts:684

Set subagent configuration overrides.

Subagent gadgets (like BrowseWeb) can read these settings from ExecutionContext to inherit model and other options from the CLI configuration.

Parameters

config

SubagentConfigMap

Subagent configuration map keyed by gadget name

Returns

this

This builder for chaining

Example

.withSubagentConfig({
  BrowseWeb: { model: "inherit", maxIterations: 20, headless: true },
  CodeAnalyzer: { model: "sonnet", maxIterations: 10 }
})

withSubagentEventCallback()

withSubagentEventCallback(callback): this

Defined in: agent/builder.ts:710

Set the callback for subagent events.

Subagent gadgets (like BrowseWeb) can use ExecutionContext.onSubagentEvent to report their internal LLM calls and gadget executions in real-time. This callback receives those events, enabling hierarchical progress display.

Parameters

callback

(event) => void

Function to handle subagent events

Returns

this

This builder for chaining

Example

.withSubagentEventCallback((event) => {
  if (event.type === "llm_call_start") {
    console.log(`  Subagent LLM #${event.event.iteration} starting...`);
  } else if (event.type === "gadget_call") {
    console.log(`    ⏵ ${event.event.call.gadgetName}...`);
  }
})

withSyntheticGadgetCall()

withSyntheticGadgetCall(gadgetName, parameters, result, invocationId): this

Defined in: agent/builder.ts:836

Add a synthetic gadget call to the conversation history.

This is useful for in-context learning - showing the LLM what “past self” did correctly so it mimics the pattern. The call is formatted with proper markers and parameter format, including the invocation ID so the LLM can reference previous calls when building dependencies.

Parameters

gadgetName

string

Name of the gadget

parameters

Record<string, unknown>

Parameters passed to the gadget

result

string

Result returned by the gadget

invocationId

string

Invocation ID (shown to LLM so it can reference for dependencies)

Returns

this

This builder for chaining

Example

.withSyntheticGadgetCall(
  'TellUser',
  {
    message: '👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
    done: false,
    type: 'info'
  },
  'ℹ️  👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
  'gc_1'
)

withSystem()

withSystem(prompt): this

Defined in: agent/builder.ts:135

Set the system prompt.

Parameters

prompt

string

System prompt

Returns

this

This builder for chaining

withTemperature()

withTemperature(temperature): this

Defined in: agent/builder.ts:146

Set the temperature (0-1).

Parameters

temperature

number

Temperature value

Returns

this

This builder for chaining

withTextOnlyHandler()

withTextOnlyHandler(handler): this

Defined in: agent/builder.ts:433

Set the text-only handler strategy.

Controls what happens when the LLM returns text without calling any gadgets:

“terminate”: End the agent loop (default)
“acknowledge”: Continue the loop for another iteration
“wait_for_input”: Wait for human input
Custom handler: Provide a function for dynamic behavior

Parameters

handler

TextOnlyHandler

Text-only handler strategy or custom handler

Returns

this

This builder for chaining

Example

// Simple strategy
.withTextOnlyHandler("acknowledge")

// Custom handler
.withTextOnlyHandler({
  type: "custom",
  handler: async (context) => {
    if (context.text.includes("?")) {
      return { action: "wait_for_input", question: context.text };
    }
    return { action: "continue" };
  }
})

withTextWithGadgetsHandler()

withTextWithGadgetsHandler(handler): this

Defined in: agent/builder.ts:458

Set the handler for text content that appears alongside gadget calls.

When set, text accompanying gadget responses will be wrapped as a synthetic gadget call before the actual gadget results in the conversation history.

Parameters

handler

Configuration for wrapping text

gadgetName

string

parameterMapping

(text) => Record<string, unknown>

resultMapping?

(text) => string

Returns

this

This builder for chaining

Example

// Wrap text as TellUser gadget
.withTextWithGadgetsHandler({
  gadgetName: "TellUser",
  parameterMapping: (text) => ({ message: text, done: false, type: "info" }),
  resultMapping: (text) => `ℹ️  ${text}`,
})

withTrailingMessage()

withTrailingMessage(message): this

Defined in: agent/builder.ts:803

Add an ephemeral trailing message that appears at the end of each LLM request.

The message is NOT persisted to conversation history - it only appears in the current LLM call. This is useful for injecting context-specific instructions or reminders without polluting the conversation history.

Parameters

message

TrailingMessage

Static string or function that generates the message

Returns

this

This builder for chaining

Example

// Static message
.withTrailingMessage("Always respond in JSON format.")

// Dynamic message based on iteration
.withTrailingMessage((ctx) =>
  `[Iteration ${ctx.iteration}/${ctx.maxIterations}] Stay focused on the task.`
)