Skip to main content

Interface: BaleybotConfig<TOutputSchema, TTools>

Defined in: packages/core/src/baleybot-config.ts:26

Baleybot configuration. Provider settings (apiKey, baseUrl) belong to the model's config; the answer's shape is output (Output.*).

Type Parameters​

TOutputSchema​

TOutputSchema = undefined

TTools​

TTools extends Tools = Record<string, never>

Properties​

activeTools?​

optional activeTools?: readonly string[]

Defined in: packages/core/src/baleybot-config.ts:217

AI SDK activeTools passthrough — restrict which of the declared tools the model may call. Thin passthrough, no baleybots semantics; overridable per-call via ProcessOptions.activeTools.


checkpointSteps?​

optional checkpointSteps?: boolean

Defined in: packages/core/src/baleybot-config.ts:375

Checkpoint every completed step of the tool loop when a call runs inside a durable execution (ProcessOptions.execution from ExecutionContext.durable), so a later call with the same execution continues after the last completed step — completed steps are not asked for again, and a tool call that already finished is not run again. Off by default; override per call with ProcessOptions.checkpointSteps.


codeExecution?​

optional codeExecution?: boolean

Defined in: packages/core/src/baleybot-config.ts:188

Enable Anthropic's programmatic code execution (tool calling). When true, the bot automatically gains a code execution tool and container IDs are forwarded between steps.

Requires @ai-sdk/anthropic to be installed.

Example​

const bot = new Baleybot({
name: 'analyst',
goal: 'Analyze data with code',
codeExecution: true,
tools: { queryDatabase },
});

compaction?​

optional compaction?: StepCompaction

Defined in: packages/core/src/baleybot-config.ts:382

With checkpointSteps: keep a long run's conversation inside a token budget by folding its older steps (see StepCompaction). Override per call with ProcessOptions.compaction.


completion?​

optional completion?: CompletionContract<InferSchemaOutput<TOutputSchema>>

Defined in: packages/core/src/baleybot-config.ts:392

The turn finishes when the agent calls a finish tool (default finish) with a value that fits the output schema and passes the host's verify, not when the model stops. The value is the turn's answer; a turn that ends without a verified finish stops with reason contract-unmet. In a durable run the verdict is journaled, so a resumed turn does not check again. See CompletionContract.


executor?​

optional executor?: ExecutionProvider

Defined in: packages/core/src/baleybot-config.ts:44

Optional external harness. It owns execution, including the tool loop.


fallbackModels?​

optional fallbackModels?: readonly (string | LanguageModelLike | ModelConfig)[]

Defined in: packages/core/src/baleybot-config.ts:362

Models to continue on, in order, when a model call fails with a provider or transport error (see isModelFallbackError). The next model resumes from the completed work — completed steps, and any tool call that already ran in the failed step — so nothing is replayed. Each fallback gets its own settings (reasoning, provider options, tool presentation). A model_fallback event marks each switch. Override per call with ProcessOptions.fallbackModels.


family?​

optional family?: object

Defined in: packages/core/src/baleybot-config.ts:57

Family membership, declared — normally set by baleybotFamily(), not by hand. The bot tells the dev registry its family; the registry never infers one from name similarity (ASK-DONT-SNIFF).

A member's instance id becomes ${id}-${memberKey} instead of a generated one, so it is stable across rebuilds — which is what lets a dev-panel override keep applying after a serverless container or a per-tenant factory reconstructs the bot. memberKey must therefore be label-grade and stable, never derived from a generated id.

id​

id: string

memberKey​

memberKey: string


goal?​

optional goal?: string

Defined in: packages/core/src/baleybot-config.ts:41

What the baleybot is trying to accomplish, woven into its instructions.

Omit it for a bot that adds no instructions of its own: no goal block and no tool note. The conversation's own system messages (modelMessages) are then its instructions, as a pass-through chat surface needs. What the bot is configured with (systemPromptBuilder, memory, skills) still joins.


isFallbackError?​

optional isFallbackError?: (error) => boolean

Defined in: packages/core/src/baleybot-config.ts:365

Decide which failures move to the next model. Default isModelFallbackError.

Parameters​

error​

unknown

Returns​

boolean


keepHistory?​

optional keepHistory?: boolean | History

Defined in: packages/core/src/baleybot-config.ts:129

Enable conversation history tracking (optional)

When enabled, the Baleybot will automatically track conversation history across multiple process() calls, maintaining context between interactions.

Options:

  • true: Creates in-memory history (lost when process exits)
  • History.inMemory(): Explicitly create in-memory history
  • History.file('path'): Persist history to a JSON file
  • Custom History instance: Use your own storage backend

Examples​

In-memory history

const bot = Baleybot.create({
name: 'assistant',
goal: 'Help the user',
keepHistory: true, // Auto-creates in-memory history
});

File-based history

import { History } from '@baleybots/core';

const bot = Baleybot.create({
name: 'assistant',
goal: 'Help the user',
keepHistory: History.file('./chat-history.json'),
});

maxTokens?​

optional maxTokens?: number

Defined in: packages/core/src/baleybot-config.ts:249


memory?​

optional memory?: MemoryBankLike

Defined in: packages/core/src/baleybot-config.ts:297

Persistent memory for this agent. When provided, the bot:

  • auto-adds the memory bank's tool (typically remember) to its tools
  • injects bank.buildContext() into the system prompt every turn

Structural typing keeps @baleybots/core from depending on @baleybots/memory (which itself depends on this package). Any object implementing MemoryBankLike works — including MemoryBank from @baleybots/memory.


model?​

optional model?: string | LanguageModelLike | ModelConfig

Defined in: packages/core/src/baleybot-config.ts:70

The model. Without one, the process-wide default (setDefaults()) applies, else the default model of the first built-in provider, in catalog order (OpenAI, then Anthropic, …), that has an API key in the environment.

Can be:

  • String: 'gpt-5.6-luna' (uses env vars for auth)
  • Object: { id: 'gpt-5.6-luna', config: { apiKey: '...' } }
  • A direct AI SDK LanguageModel instance (passthrough — covers the whole AI SDK catalog, community providers, and createOpenAICompatible)

name​

name: string

Defined in: packages/core/src/baleybot-config.ts:31

The bot's label in events and logs; a checkpointed run also keys its journaled steps by it.


onStepEnd?​

optional onStepEnd?: GenerateTextOnStepEndCallback<ToolSet>

Defined in: packages/core/src/baleybot-config.ts:231

AI SDK onStepEnd passthrough — called when each step (LLM call) ends, including intermediate tool-loop steps. Overridable per-call via ProcessOptions.onStepEnd.


output?​

optional output?: OutputConfig<TOutputSchema>

Defined in: packages/core/src/baleybot-config.ts:92

The answer's shape, built with Output.object(), Output.array() or Output.choice().

Example​

import { Output } from '@baleybots/core';

const bot = new Baleybot({
name: 'analyzer',
goal: 'Analyze sentiment',
output: Output.object({
schema: z.object({
sentiment: z.enum(['positive', 'negative', 'neutral']),
confidence: z.number(),
}),
}),
});

prepareStep?​

optional prepareStep?: PrepareStepFunction<ToolSet>

Defined in: packages/core/src/baleybot-config.ts:210

AI SDK prepareStep passthrough — inspect or adjust each step of the tool loop (messages, model, toolChoice, activeTools) before it runs, and return per-step overrides. Composed AFTER any internal hook (code-execution container forwarding), so container IDs are still forwarded when codeExecution is enabled. Override per call through ProcessOptions.prepareStep.

This is a thin passthrough of the AI SDK's own prepareStep — see the AI SDK docs for the argument shape and the override fields it accepts.

Example​

const bot = new Baleybot({
name: 'analyst',
goal: 'Analyze data',
prepareStep: ({ stepNumber }) =>
stepNumber === 0 ? { toolChoice: 'required' } : {},
});

repairToolCall?​

optional repairToolCall?: ToolCallRepairFunction<ToolSet>

Defined in: packages/core/src/baleybot-config.ts:238

AI SDK experimental_repairToolCall passthrough — repair a tool call the model produced with invalid input or an unknown name. Overridable per-call via ProcessOptions.repairToolCall.


runtimeContext?​

optional runtimeContext?: unknown

Defined in: packages/core/src/baleybot-config.ts:245

AI SDK runtimeContext passthrough — user-defined context threaded through the generation lifecycle (visible to tools, prepareStep, approval fns). Overridable per-call via ProcessOptions.runtimeContext.


skills?​

optional skills?: Skill[]

Defined in: packages/core/src/baleybot-config.ts:321

Skills available to this agent. A Skill is a keyword-triggered instruction sheet that bundles the tools it talks about. When provided, the bot:

  • hoists every skill's tools (plus a shared load_skill tool) into its tools map at construction — tools are declared up front, never removed
  • injects, every turn, an always-on skill index plus the full instructions of any skill whose keyword matches the input or that the model has activated via load_skill

Skills are inert guidance: they steer the agent toward tools that are already declared and already gated. They grant no capability of their own.

Scoping: keyword triggers are stateless (re-evaluated per turn). A skill the model activates via load_skill stays active — and is re-injected into every subsequent prompt — until the model calls unload_skill or the conversation is reset; it is also forgotten on clearHistory(). Like conversation history, this state is per-Baleybot-instance — treat one instance as one conversation rather than sharing it across concurrent, unrelated requests.

See​

docs/spikes/core-skill-primitive-plan.md


smoothStream?​

optional smoothStream?: boolean | { chunking?: RegExp | "word" | "line"; delayInMs?: number; }

Defined in: packages/core/src/baleybot-config.ts:272

Smooth streaming output for chat UIs — buffers tokens and releases them in configurable chunks (default: word-by-word, 10ms). Reduces flicker when models burst tokens.

  • true: enable with AI SDK defaults
  • object: configure delay and chunking strategy

Powered by AI SDK's smoothStream transform.


stopWhen?​

optional stopWhen?: StopCondition

Defined in: packages/core/src/baleybot-config.ts:158

Stop condition for the tool loop (AI SDK stopWhen).

Default: stepCountIs(50). When that default fires, the stream emits done with reason: 'out_of_iterations' and iteration_count set — not a silent normal finish. Raise the cap explicitly for long autonomous runs.

Examples​

Stop after 10 iterations

stopWhen: stepCountIs(10)

Stop when a specific tool is called

stopWhen: hasToolResult('submit_answer')

Combined conditions

stopWhen: combineConditions(
stepCountIs(50),
hasToolResult('done'),
)

Default​

stepCountIs(50)

systemPromptBuilder?​

optional systemPromptBuilder?: (input) => string | Promise<string>

Defined in: packages/core/src/baleybot-config.ts:285

Dynamic system-prompt builder invoked on every turn before tool/schema instructions are appended. Receives the current user input and returns additional markdown to splice into the system message.

Use this for per-turn injection (e.g. memory banks, freshly retrieved context). The returned string is appended after goal and before the tool/schema wrappers — so it sees no automatic decoration.

Returning an empty string is a no-op.

Parameters​

input​

string

Returns​

string | Promise<string>


temperature?​

optional temperature?: number

Defined in: packages/core/src/baleybot-config.ts:252

Temperature for response randomness (0–2, provider-dependent).


toolChoice?​

optional toolChoice?: "none" | "auto" | "required"

Defined in: packages/core/src/baleybot-config.ts:260

Controls whether the model must call tools.

  • 'auto' (default): Model decides whether to call tools
  • 'required': Model must call a tool on every step (prevents text-only exits from tool loop)
  • 'none': Model cannot call tools

toolFailMode?​

optional toolFailMode?: ToolFailMode

Defined in: packages/core/src/baleybot-config.ts:169

Controls what happens when a tool call fails during execution.

  • 'returnToAI' (default): Error becomes the tool's return value. The LLM continues and can retry/adapt.
  • 'returnToUser': Error becomes the tool result, then one more LLM call with toolChoice: 'none' — forces a text response about the error.
  • 'throw': Error is re-thrown from the tool's execute; AI SDK reports it to the model as a tool error (error-text) and the loop continues.

Default​

'returnToAI'

toolHooks?​

optional toolHooks?: readonly ToolHook[]

Defined in: packages/core/src/baleybot-config.ts:351

Middleware around every tool this bot executes — one place for gates, audit, result projection and circuit breakers instead of a wrapper per tool (see ToolHook). Outermost first. Per-call ProcessOptions.toolHooks run inside these.


toolOrder?​

optional toolOrder?: readonly string[]

Defined in: packages/core/src/baleybot-config.ts:224

AI SDK toolOrder passthrough — control the order tools are sent to the provider (partial lists allowed; unlisted tools are appended alphabetically). Overridable per-call via ProcessOptions.toolOrder.


tools?​

optional tools?: TTools

Defined in: packages/core/src/baleybot-config.ts:95

Tools available to the baleybot: tool definitions and Processables.


toolSearch?​

optional toolSearch?: ToolSearchOptions

Defined in: packages/core/src/baleybot-config.ts:343

Present a large tool set through search instead of sending every definition every step (see toolSearch()). Each call builds a fresh plan from that call's model: native Anthropic BM25 search over deferred definitions on direct Claude 4+, portable discovery everywhere else.

With skills, the loaders (load_skill / unload_skill) and the tools of every skill active when the call starts are loaded; other skills' tools load on demand. defer: 'skills' keeps every non-skill tool loaded, so only skill tools are deferred until their skill is active. A skill that becomes active mid-call (load_skill, or a restoreSkillState during the call) makes its tools callable on the very next step, on every transport: portable selects them; native puts an Anthropic tool_reference for each on that step's tool result, so no definition — and no cached prefix — is edited. unload_skill returns them to on-demand loading: from the next step on portable, from the next call on native (a reference already in the transcript cannot be withdrawn without re-reading the whole prompt).

Override or disable (false) per call with ProcessOptions.toolSearch.


verbose?​

optional verbose?: boolean

Defined in: packages/core/src/baleybot-config.ts:247