Skip to main content

Patterns Overview

The @codebolt/agent package provides two exports:

ExportWhen to use
@codebolt/agent/unifiedUse the default agentic loop as-is — CodeboltAgent
@codebolt/agent/processor-piecesCustomize the loop by adding/swapping processors — Processor Pattern

Picking one​

  • Don't need to change the loop? → Use CodeboltAgent. Provide instructions, call processMessage, done.
  • Need to add processors, swap modifiers, or hook into specific phases? → Use the Processor Pattern. Same CodeboltAgent class, but you configure the processors slots.
  • Need full control with no defaults? → Use Agent (the bare class, see below).

The two classes​

CodeboltAgent — use the loop as-is​

CodeboltAgent is the batteries-included agent class. Use it when you don't need to change any logic in the agentic loop. You provide instructions, the framework handles everything else — context assembly, LLM calls, tool execution, compaction, error recovery.

import { CodeboltAgent } from '@codebolt/agent/unified';

const agent = new CodeboltAgent({
  instructions: 'You are a helpful coding assistant.',
});

Use CodeboltAgent when:

  • The default loop is exactly what you need.
  • You just want to set a system prompt and go.
  • You don't need custom processors, modifiers, or hooks.

Agent — the bare class​

Agent implements the same loop but with no default message modifiers. You supply everything yourself through the processors config.

import { Agent } from '@codebolt/agent/unified';
import {
  DirectoryContextModifier,
  CoreSystemPromptModifier,
  ToolInjectionModifier,
} from '@codebolt/agent/processor-pieces';

const agent = new Agent({
  instructions: 'You are a specialist agent.',
  processors: {
    messageModifiers: [
      new DirectoryContextModifier(),
      new CoreSystemPromptModifier({ customSystemPrompt: 'Custom prompt here.' }),
      new ToolInjectionModifier({ includeToolDescriptions: true }),
    ],
  },
});

Use Agent when:

  • You need full control over which modifiers run.
  • You're building infrastructure that assembles agents from config.
  • The default CodeboltAgent pipeline includes modifiers you don't want.

Building blocks​

Both classes are built from lower-level components you can also use directly:

ComponentWhat it does
InitialPromptGeneratorRuns message modifiers to build the initial prompt
AgentStepExecutes one LLM inference step with pre/post-inference processors
ResponseExecutorHandles tool execution with pre/post-tool-call processors
ToolWraps a function with Zod input/output validation
WorkflowOrchestrates multi-step processes with input/output schemas
LoopDetectionServiceDetects and breaks infinite loops
CompactionOrchestratorMulti-layer conversation compaction (snip, micro, context collapse, auto, reactive)

Use these directly when CodeboltAgent's loop shape doesn't match your needs but you still want framework components instead of raw @codebolt/codeboltjs.

const prompt = await promptGenerator.processMessage(reqMessage);
const stepResult = await agentStep.executeStep(reqMessage, prompt);
const execution = await responseExecutor.executeResponse({
  initialUserMessage: reqMessage,
  actualMessageSentToLLM: stepResult.actualMessageSentToLLM,
  rawLLMOutput: stepResult.rawLLMResponse,
  nextMessage: stepResult.nextMessage,
});

See also​