Configuration

Configure AgentForge with defineConfig and agentforge.config.ts.

Configuration File

AgentForge uses agentforge.config.ts at the project root. Define it with the defineConfig helper for type safety:

agentforge.config.ts

import { defineConfig } from '@ahzan-agentforge/core';

export default defineConfig({
  // Default LLM provider for all agents
  llm: {
    provider: 'anthropic',
    model: 'claude-sonnet-4-20250514',
    maxTokens: 4096,
  },

  // State store for checkpointing
  state: {
    provider: 'redis',
    url: 'redis://localhost:6379',
  },

  // Memory configuration
  memory: {
    provider: 'pgvector',
    connectionString: 'postgresql://localhost:5432/agentforge',
  },

  // Budget defaults
  budget: {
    maxCostUsd: 1.0,
    maxTokens: 100_000,
    warnThreshold: 0.8,
  },

  // Observability
  observability: {
    enabled: true,
    exporter: 'otlp',
    endpoint: 'http://localhost:4318',
  },
});

Loading Configuration

Use loadConfig() to load the configuration at runtime:

import { loadConfig } from '@ahzan-agentforge/core';

const config = await loadConfig();
// config.llm, config.state, config.memory, etc.

AgentForgeConfig Type

interface AgentForgeConfig {
  llm?: LLMConfig;
  state?: {
    provider: 'memory' | 'redis';
    url?: string;
  };
  memory?: {
    provider: 'memory' | 'pgvector';
    connectionString?: string;
  };
  budget?: BudgetConfig;
  observability?: {
    enabled?: boolean;
    exporter?: string;
    endpoint?: string;
  };
}

Environment Variables

AgentForge reads these environment variables:

Variable	Purpose
`ANTHROPIC_API_KEY`	Anthropic Claude API key
`OPENAI_API_KEY`	OpenAI GPT API key
`GOOGLE_AI_API_KEY`	Google Gemini API key
`REDIS_URL`	Redis connection URL
`DATABASE_URL`	PostgreSQL connection URL

You can use a .env file — AgentForge loads it automatically via dotenv.

Per-Agent Overrides

Configuration values can be overridden per-agent in defineAgent():

const agent = defineAgent({
  name: 'expensive-agent',
  // ...
  llm: createLLM({ provider: 'anthropic', model: 'claude-opus-4-20250514' }),
  budget: { maxCostUsd: 5.0, maxTokens: 500_000 },
});

Next Steps

Concepts — understand the mental model
Agents — full agent configuration