Core Decorators

Core decorators provide the fundamental building blocks for Agent Forge applications. These decorators handle agent configuration, LLM provider setup, and framework initialization.

@agent

Configures agent properties and behavior. Must be applied to classes that extend the Agent base class.

Syntax

@agent(config: AgentConfig)
class MyAgent extends Agent {}

Parameters

AgentConfig

Property	Type	Required	Description
name	string	✅	Unique identifier for the agent
role	string	✅	The agent's role or persona
description	string	✅	Brief description of the agent's purpose
objective	string	✅	Primary goal or objective
model	string	✅	LLM model identifier
temperature	number	❌	Creativity level (0.0-1.0, default: 0.7)
maxTokens	number	❌	Maximum tokens per response

Examples

Basic Agent

@agent({
  name: "ResearchAgent",
  role: "Research Specialist",
  description: "An agent specialized in conducting research",
  objective: "Find accurate and relevant information",
  model: "gpt-4",
  temperature: 0.3
})
class ResearchAgent extends Agent {}

Creative Agent

@agent({
  name: "CreativeWriter",
  role: "Creative Writing Assistant", 
  description: "Helps with creative writing tasks",
  objective: "Generate engaging and original content",
  model: "gpt-4-turbo",
  temperature: 0.9,
  maxTokens: 2000
})
class CreativeAgent extends Agent {}

Best Practices

• Descriptive Names: Use clear, descriptive names that reflect the agent's purpose
• Specific Roles: Define specific roles rather than generic ones
• Clear Objectives: Write clear, actionable objectives
• Appropriate Temperature: Use lower values (0.1-0.3) for factual tasks, higher (0.7-0.9) for creative tasks

---

@llmProvider

Sets the LLM provider and configuration for a class. Required before using most other decorators.

Syntax

@llmProvider(provider: LLMProvider, config: ConfigOptions)
class MyClass {}

Parameters

LLMProvider

Supported providers from Token.js:

• "openai" - OpenAI GPT models
• "anthropic" - Anthropic Claude models
• "google" - Google Gemini models
• "azure" - Azure OpenAI Service
• "groq" - Groq models
• "ollama" - Local Ollama models

ConfigOptions

Configuration varies by provider. Common options:

Property	Type	Description
apiKey	string	API key for the provider
baseUrl	string	Custom base URL (optional)
organizationId	string	Organization ID (OpenAI only)
maxRetries	number	Maximum retry attempts
timeout	number	Request timeout in milliseconds

Examples

OpenAI Configuration

@llmProvider("openai", {
  apiKey: process.env.OPENAI_API_KEY,
  organizationId: process.env.OPENAI_ORG_ID,
  maxRetries: 3,
  timeout: 30000
})
class OpenAIAgent extends Agent {}

Anthropic Configuration

@llmProvider("anthropic", {
  apiKey: process.env.ANTHROPIC_API_KEY,
  maxRetries: 2
})
class ClaudeAgent extends Agent {}

Local Ollama Configuration

@llmProvider("ollama", {
  baseUrl: "http://localhost:11434",
  timeout: 60000
})
class LocalAgent extends Agent {}

Azure OpenAI Configuration

@llmProvider("azure", {
  apiKey: process.env.AZURE_OPENAI_API_KEY,
  baseUrl: process.env.AZURE_OPENAI_ENDPOINT,
  organizationId: process.env.AZURE_OPENAI_DEPLOYMENT
})
class AzureAgent extends Agent {}

Environment Variables

It's recommended to use environment variables for sensitive configuration:

# .env file
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key  
AZURE_OPENAI_API_KEY=your_azure_key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/

---

@forge

Creates an AgentForge instance with automatic LLM provider setup. Must be used after @llmProvider. Optionally accepts configuration for logging and other framework settings.

Syntax

@llmProvider(provider, config)
@forge(config?: ForgeConfig)
class MyForge {
  static forge: AgentForge;
}

Parameters

ForgeConfig

Property	Type	Description
logger	Partial<LoggerConfig>	Optional logger configuration

LoggerConfig

Property	Type	Default	Description
level	LogLevel	LogLevel.INFO	Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
enableConsoleLogging	boolean	true	Show logs in console
enableEventEmission	boolean	true	Emit log events
enablePerformanceLogging	boolean	true	Track performance metrics
enableErrorAggregation	boolean	true	Count error occurrences
maxLogHistory	number	1000	Maximum logs to keep in memory

Features

• Automatic Initialization: Creates AgentForge instance with LLM provider
• Plugin Support: Automatically registers plugins added with @plugin
• Rate Limiting: Applies rate limiting if configured with @RateLimiter
• Lazy Loading: Initializes only when first accessed

Examples

Basic Forge

@llmProvider("openai", { apiKey: process.env.OPENAI_API_KEY })
@forge()
class SimpleForge {
  static forge: AgentForge;
  
  static async run() {
    const agent = new MyAgent();
    await this.forge.registerAgent(agent);
    return this.forge.runAgent("MyAgent", "Hello!");
  }
}

Forge with Logging Configuration

import { LogLevel } from "agent-forge";

@llmProvider("openai", { apiKey: process.env.OPENAI_API_KEY })
@forge({
  logger: {
    level: LogLevel.DEBUG,  // Enable debug logging to see all LLM interactions. Default: LogLevel.INFO
    enableConsoleLogging: true, // Default: true
    enableEventEmission: true, // Default: true
    enablePerformanceLogging: true, // Default: true
    enableErrorAggregation: true, // Default: true
    maxLogHistory: 500 // Default: 1000
  }
})
class VerboseForge {
  static forge: AgentForge;
}

Environment-Specific Configuration

// Development environment - debug everything
@llmProvider("openai", { apiKey: process.env.OPENAI_API_KEY })
@forge({
  logger: {
    level: LogLevel.DEBUG,
    enableConsoleLogging: true,
    enablePerformanceLogging: true,
    maxLogHistory: 1000
  }
})
class DevForge {
  static forge: AgentForge;
}

// Production environment - errors only
@llmProvider("openai", { apiKey: process.env.OPENAI_API_KEY })
@forge({
  logger: {
    level: LogLevel.ERROR,
    enableConsoleLogging: true,
    enablePerformanceLogging: false,  // Disable for performance
    maxLogHistory: 100               // Keep fewer logs
  }
})
class ProdForge {
  static forge: AgentForge;
}

Forge with Plugins

@plugin(new CustomLoggingPlugin())
@plugin(new CustomMetricsPlugin()) 
@llmProvider("openai", { apiKey: process.env.OPENAI_API_KEY })
@forge()
class AdvancedForge {
  static forge: AgentForge;
}

Forge with Rate Limiting

@RateLimiter({ rateLimitPerSecond: 2 })
@llmProvider("openai", { apiKey: process.env.OPENAI_API_KEY })
@forge()
class RateLimitedForge {
  static forge: AgentForge;
}

Usage with readyForge

The readyForge utility function handles async initialization:

@llmProvider("openai", { apiKey: process.env.OPENAI_API_KEY })
@forge()
class MyTeam {
  static forge: AgentForge;
  
  static async run() {
    const agentClasses = [ResearchAgent, WriterAgent];
    await readyForge(MyTeam, agentClasses);
    
    return this.forge.runTeam("Manager", ["Researcher", "Writer"], "task");
  }
}

Best Practices

1. Environment Configuration: Always use environment variables for API keys
2. Error Handling: Wrap forge operations in try-catch blocks
3. Resource Cleanup: Properly shut down forge instances when done
4. Type Safety: Use proper TypeScript types for better development experience

Common Patterns

Team Management

@llmProvider("openai", { apiKey: process.env.OPENAI_API_KEY })
@forge()
class TeamForge {
  static forge: AgentForge;
  
  static async createTeam(managerName: string, agentNames: string[]) {
    return this.forge.createTeam(managerName, "MyTeam", "Team description");
  }
  
  static async runWorkflow(agentNames: string[], input: string) {
    return this.forge.runWorkflow(agentNames, input, { stream: true });
  }
}

Multi-Provider Setup

// Primary provider
@llmProvider("openai", { apiKey: process.env.OPENAI_API_KEY })
@forge()
class PrimaryForge {
  static forge: AgentForge;
}

// Fallback provider  
@llmProvider("anthropic", { apiKey: process.env.ANTHROPIC_API_KEY })
@forge()
class FallbackForge {
  static forge: AgentForge;
}