Interface: AgentConfig

Defined in: agent.ts:182

Agent configuration options

Properties

anchors? 

optional anchors?: AnchorManagerOptions;

Defined in: agent.ts:425

Deprecated

Use pins instead

autoCheckpoint? 

optional autoCheckpoint?: boolean;

Defined in: agent.ts:385

Automatically save state after each run() call. Requires checkpointer to be set. Default: false.

autoContextManagement? 

optional autoContextManagement?: boolean;

Defined in: agent.ts:303

Enable automatic context management (compaction, summarization). Requires contextManager to be set. Default: true when contextManager is provided.

chatOptions? 

optional chatOptions?: ChatOptions;

Defined in: agent.ts:279

Chat options (model, temperature, etc.)

checkpointer? 

optional checkpointer?: Checkpointer;

Defined in: agent.ts:373

Checkpointer for persisting agent state. If provided, enables checkpoint() and resume() functionality.

checkpointOnAbort? 

optional checkpointOnAbort?: boolean;

Defined in: agent.ts:395

Save a partial checkpoint when run is aborted or encounters an error. This allows recovery from interrupted runs. Requires checkpointer to be set. Default: false.

Inspired by LangGraph issue #5672: Cancellation causes loss of streamed state not yet persisted as checkpoint.

compactToolResults? 

optional compactToolResults?: boolean;

Defined in: agent.ts:324

Use compact text format for tool results in LLM messages. Strips JSON wrappers and metadata, reducing token usage. Enabled by default when contextManager is provided. Set to false to disable.

contextManager? 

optional contextManager?: ContextManager;

Defined in: agent.ts:297

Context manager for tracking and managing context window usage. If not provided, context management is disabled.

deadMessagePruning? 

optional deadMessagePruning?: false | Partial<PruneConfig>;

Defined in: agent.ts:330

Dead message pruning configuration. Prunes superseded errors and permission exchanges. Enabled by default when contextManager is provided. Set to false to disable.

delegation? 

optional delegation?: DelegationConfig;

Defined in: agent.ts:656

Tool result delegation config. When set and enabled, large tool results are automatically summarized to conserve context tokens. Full results are stored in-memory for optional recall via recall_full_result.

Example 

const agent = new Agent({
  provider,
  delegation: {
    enabled: true,
    delegationThreshold: 8000, // tokens above which to delegate
    strategy: 'auto',         // try LLM, fall back to extractive
    toolOverrides: {
      bash: { threshold: 12000 },
      grep: { threshold: 4000 },
    },
  },
});

enableFileTracking? 

optional enableFileTracking?: boolean;

Defined in: agent.ts:686

Enable file access tracking for context restoration hints.

When enabled, the agent tracks which files were read, referenced (grep/glob), and modified during execution. After context compaction, these hints are injected to help the LLM understand what files it previously accessed.

Requires contextManager to be set (hints are injected after compaction).

Default 

false

Example 

const agent = new Agent({
  provider,
  contextManager: new ContextManager({ provider }),
  enableFileTracking: true, // Automatically track file accesses
});

// After compaction, the agent will inject hints like:
// [Context compacted. Previously accessed files:]
// Read (3 files): file1.ts (100 lines), file2.ts (50 lines)...

fileRestoration? 

optional fileRestoration?: {
  maxInlineTokens?: number;
};

Defined in: agent.ts:697

Options for file context restoration after compaction.

Controls how file contents are re-injected into the context after compaction. Small files get their content inlined; large files get reference-only hints.

Only applies when enableFileTracking is true.

maxInlineTokens? 

optional maxInlineTokens?: number;

Max total tokens for inline file content after compaction (default: 4000)

guardrails? 

optional guardrails?: GuardrailManagerOptions;

Defined in: agent.ts:464

Guardrail options for pattern-based safety checks.

Guardrails scan tool inputs before execution and can:

  • warn: Log a warning but proceed
  • confirm: Require confirmation (via onTriggered handler)
  • block: Prevent execution entirely

Example 

const agent = new Agent({
  provider,
  guardrails: {
    enabled: true,
    includeDefaults: true, // Include built-in guardrails
    custom: [
      {
        id: 'no-prod',
        name: 'Production Protection',
        description: 'Block operations on production',
        patterns: [/prod/i],
        action: 'block',
        message: 'Production operations are blocked',
      }
    ],
    onTriggered: async (result, context) => {
      // Return true to proceed, false to block
      return await askUser(result.guardrail.message);
    }
  }
});

hooks? 

optional hooks?: HooksConfig;

Defined in: agent.ts:629

Hooks for customizing agent behavior at various lifecycle points.

Hooks provide extension points without subclassing for:

  • Logging and tracing
  • Input/output transformation
  • Custom validation
  • Metrics collection
  • Integration with external systems

Example 

const agent = new Agent({
  provider,
  hooks: {
    beforeTool: [
      async (ctx) => {
        console.log(`Tool ${ctx.toolName} starting...`);
      }
    ],
    afterTool: [
      async (ctx) => {
        console.log(`Tool ${ctx.toolName} completed in ${ctx.durationMs}ms`);
        // Optionally modify result
        return { result: ctx.result };
      }
    ],
    beforeLLM: [
      async (ctx) => {
        // Optionally inject or transform messages
        return { messages: ctx.messages };
      }
    ],
    onError: [
      async (ctx) => {
        console.error(`Error in ${ctx.phase}:`, ctx.error);
      }
    ]
  }
});

iterationLimitBehavior? 

optional iterationLimitBehavior?: "summarize" | "error" | "continue";

Defined in: agent.ts:225

Behavior when max iterations is reached (default: ‘error’).

  • ‘error’: Throw MaxIterationsError immediately
  • ‘summarize’: Generate a final summary response before throwing
  • ‘continue’: Return partial result without throwing (response will be empty)

Note: If onIterationLimitReached callback is provided, it takes precedence.

logger? 

optional logger?: Logger;

Defined in: agent.ts:717

Logger instance for structured diagnostic logging. When omitted, no logging is performed.

Example 

import { createLogger } from '@compilr-dev/logger';
const log = createLogger({ package: 'my-app' });
const agent = new Agent({ provider, logger: log });

maxConsecutiveToolCalls? 

optional maxConsecutiveToolCalls?: number;

Defined in: agent.ts:206

Maximum consecutive identical tool calls (same name + input + result) before the loop detector trips (default: 5). Set to 0 to disable loop detection.

Detection is result-aware: a repeated call only counts when its result is also identical to the previous one, so legitimate polling that returns changing output (e.g. bash_output while a build runs) does not trip.

maxIterations? 

optional maxIterations?: number;

Defined in: agent.ts:196

Maximum iterations for tool use loops (default: 10)

maxToolLoopNudges? 

optional maxToolLoopNudges?: number;

Defined in: agent.ts:215

On a loop trip, how many times to inject a corrective “self-heal” message and let the agent continue before throwing ToolLoopError (default: 1). Set to 0 to throw immediately on the first trip (no self-heal).

Ignored when onToolLoopDetected is provided (that callback takes over).

observationMask? 

optional observationMask?: 
  | false
| Partial<ObservationMaskConfig>;

Defined in: agent.ts:309

Observation masking configuration. Masks old tool results in history to reduce tokens. Enabled by default when contextManager is provided. Set to false to disable.

onEvent? 

optional onEvent?: AgentEventHandler;

Defined in: agent.ts:335

Event handler for monitoring agent execution

onIterationLimitReached? 

optional onIterationLimitReached?: (context) => Promise<number | false>;

Defined in: agent.ts:248

Callback invoked when the agent reaches its iteration limit. Allows the caller to decide whether to continue or stop.

Parameters

Parameter Type Description
context { iteration: number; maxIterations: number; toolCallCount: number; } Information about the current state
context.iteration number -
context.maxIterations number -
context.toolCallCount number -

Returns

Promise<number | false>

Promise resolving to:

  • false to stop the agent gracefully
  • A positive number to continue with that many additional iterations

If this callback is provided and returns a number, the agent will continue running with the extended iteration limit. This takes precedence over iterationLimitBehavior.

Example 

onIterationLimitReached: async ({ iteration, toolCallCount }) => {
  const answer = await askUser(`Agent used ${iteration} iterations. Continue?`);
  return answer === 'yes' ? 50 : false; // Add 50 more or stop
}

onToolLoopDetected? 

optional onToolLoopDetected?: (context) => Promise<boolean>;

Defined in: agent.ts:270

Callback when tool loop is detected (same tool called N times with identical input).

When provided, the agent asks the user instead of throwing ToolLoopError. Return true to continue (reset the counter), false to stop.

When not provided, ToolLoopError is thrown (backwards compatible).

Parameters

Parameter Type
context { consecutiveCalls: number; input: Record<string, unknown>; toolName: string; }
context.consecutiveCalls number
context.input Record<string, unknown>
context.toolName string

Returns

Promise<boolean>

Example 

onToolLoopDetected: async ({ toolName, consecutiveCalls }) => {
  const answer = await askUser(`${toolName} called ${consecutiveCalls} times. Continue?`);
  return answer === 'yes';
}

permissionManager? 

optional permissionManager?: PermissionManager;

Defined in: agent.ts:508

Pre-existing PermissionManager instance.

Use this to share a PermissionManager between agents (e.g., parent and sub-agents). When provided, takes precedence over permissions options.

This is primarily used internally for sub-agent permission inheritance.

permissions? 

optional permissions?: PermissionManagerOptions;

Defined in: agent.ts:498

Permission options for tool-level access control.

Permissions allow fine-grained control over which tools can execute and when user approval is required.

Example 

const agent = new Agent({
  provider,
  permissions: {
    defaultLevel: 'always', // Default: allow all tools
    rules: [
      { toolName: 'bash', level: 'once', description: 'Shell commands' },
      { toolName: 'write_file', level: 'session', description: 'File writes' },
      { toolName: 'delete_*', level: 'deny' }, // Wildcard: block all delete tools
    ],
    onPermissionRequest: async (request) => {
      // Return true to allow, false to deny
      return await showConfirmDialog(
        `Allow ${request.toolName}?`,
        request.preview
      );
    }
  }
});

pins? 

optional pins?: AnchorManagerOptions;

Defined in: agent.ts:422

Pin manager options for critical information that survives context compaction.

Pins are pieces of information that:

  • Never get compacted - Survive all context management
  • Always re-injected - Present in every LLM call
  • Scoped - Session, persistent, or temporary

Example 

const agent = new Agent({
  provider,
  pins: {
    maxAnchors: 20,
    maxTokens: 2000,
    persistPath: '~/.myapp/anchors.json',
    includeDefaults: true, // Include built-in safety anchors
  }
});

projectMemory? 

optional projectMemory?: ProjectMemory;

Defined in: agent.ts:544

Pre-loaded project memory to prepend to system prompt.

Use Agent.createWithMemory() to automatically load from files, or pass a pre-loaded ProjectMemory object.

Example 

// Option 1: Use the factory method (recommended)
const agent = await Agent.createWithMemory({
  provider,
  systemPrompt: 'You are a helpful assistant.',
  projectMemoryOptions: {
    providers: ['claude', 'gemini'],
    includeGeneric: true,
  },
  projectMemoryDir: '/path/to/project',
});

// Option 2: Pre-load memory manually
const loader = new ProjectMemoryLoader({ providers: 'claude' });
const memory = await loader.load('/path/to/project');

const agent = new Agent({
  provider,
  systemPrompt: 'You are a helpful assistant.',
  projectMemory: memory, // Pre-loaded memory
});

provider 

provider: LLMProvider;

Defined in: agent.ts:186

The LLM provider to use

retry? 

optional retry?: LLMRetryConfig;

Defined in: agent.ts:363

Configuration for automatic retry on transient LLM errors. Enabled by default with sensible defaults (10 attempts, exponential backoff).

Retryable errors include:

  • Rate limit (429)
  • Server errors (5xx)
  • Connection/network errors
  • Anthropic overloaded (529)

Example 

const agent = new Agent({
  provider,
  retry: {
    maxAttempts: 5,      // Max 5 retries
    baseDelayMs: 2000,   // Start with 2s delay
    maxDelayMs: 60000,   // Cap at 60s
  }
});

sessionId? 

optional sessionId?: string;

Defined in: agent.ts:379

Session ID for this agent instance. If not provided, a new session ID is generated automatically.

systemPrompt? 

optional systemPrompt?: string;

Defined in: agent.ts:191

System prompt for the agent

toolRegistry? 

optional toolRegistry?: ToolRegistry;

Defined in: agent.ts:284

Custom tool registry (optional, creates new one if not provided)

toolTimeoutMs? 

optional toolTimeoutMs?: number;

Defined in: agent.ts:291

Default timeout for tool execution in milliseconds (default: 30000 = 30s). Set to 0 to disable timeout. Only used when toolRegistry is not provided. Sub-agents inherit this timeout from the parent agent.

usage? 

optional usage?: UsageTrackerOptions;

Defined in: agent.ts:581

Usage tracking options for monitoring token usage.

Note: We track tokens only, not dollar costs. Pricing changes frequently and providing potentially inaccurate cost information would be misleading.

Example 

const agent = new Agent({
  provider,
  usage: {
    enabled: true,
    budget: {
      maxTotalTokens: 100000,  // 100k token limit
      warningThreshold: 0.8,   // Warn at 80%
    },
  },
});

// After runs, check usage
console.log(agent.getUsageStats());
console.log(agent.getTotalTokens());

// Listen for budget events
agent.onEvent((event) => {
  if (event.type === 'usage_budget_warning') {
    console.log('Budget warning!', event.status);
  }
});

windowing? 

optional windowing?: false | Partial<WindowingConfig>;

Defined in: agent.ts:317

Smart windowing configuration. Programmatically compacts old messages when history exceeds a token budget. Three zones: recent (intact), middle (truncated), old (event log). Zero LLM calls. Enabled by default when contextManager is provided. Set to false to disable.