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?
optionalactiveTools?: readonlystring[]
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?
optionalcheckpointSteps?: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?
optionalcodeExecution?: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?
optionalcompaction?: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?
optionalcompletion?: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?
optionalexecutor?:ExecutionProvider
Defined in: packages/core/src/baleybot-config.ts:44
Optional external harness. It owns execution, including the tool loop.
fallbackModels?
optionalfallbackModels?: 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?
optionalfamily?: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?
optionalgoal?: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?
optionalisFallbackError?: (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?
optionalkeepHistory?: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 historyHistory.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?
optionalmaxTokens?:number
Defined in: packages/core/src/baleybot-config.ts:249
memory?
optionalmemory?: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 itstools - 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?
optionalmodel?: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
LanguageModelinstance (passthrough — covers the whole AI SDK catalog, community providers, andcreateOpenAICompatible)
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?
optionalonStepEnd?: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?
optionaloutput?: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?
optionalprepareStep?: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?
optionalrepairToolCall?: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?
optionalruntimeContext?: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?
optionalskills?: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_skilltool) into itstoolsmap 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?
optionalsmoothStream?: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?
optionalstopWhen?: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?
optionalsystemPromptBuilder?: (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?
optionaltemperature?:number
Defined in: packages/core/src/baleybot-config.ts:252
Temperature for response randomness (0–2, provider-dependent).
toolChoice?
optionaltoolChoice?:"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?
optionaltoolFailMode?: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 withtoolChoice: 'none'— forces a text response about the error.'throw': Error is re-thrown from the tool'sexecute; AI SDK reports it to the model as a tool error (error-text) and the loop continues.
Default
'returnToAI'
toolHooks?
optionaltoolHooks?: readonlyToolHook[]
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?
optionaltoolOrder?: readonlystring[]
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?
optionaltools?:TTools
Defined in: packages/core/src/baleybot-config.ts:95
Tools available to the baleybot: tool definitions and Processables.
toolSearch?
optionaltoolSearch?: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?
optionalverbose?:boolean
Defined in: packages/core/src/baleybot-config.ts:247