Skip to content

Core Module

The core module provides the foundational building blocks for the entire framework: the abstract base class for agents, the tool registry, execution context interfaces, and tool definition utilities.

Import

All core exports are available from the package root:

import {
  BaseAgent,
  ToolRegistry,
  AgentContext,
  AgentResult,
  AgentConfig,
  AgentCapability,
  Tool,
  ITool,
  ToolMetadata,
  ToolParameter,
  getToolMetadata,
  isTool,
  validateToolParams,
  createTool,
} from "@modernpath/agent-framework";

Module Map

graph LR
    BA[BaseAgent] -->|uses| TR[ToolRegistry]
    TR -->|stores| TD["@Tool classes"]
    TR -->|stores| DT[Dynamic Tools]
    BA -->|receives| AC[AgentContext]
    BA -->|returns| AR[AgentResult]
    BA -->|configured by| CF[AgentConfig]
    BA -->|declares| CP[AgentCapability]

Components

BaseAgent

The abstract base class that all agents extend. Provides execution lifecycle management with automatic timeout handling, error recovery, statistics tracking, and opt-in tracing. You implement the executeInternal() method; the framework handles everything else.

AgentContext & AgentResult

The interfaces that define how data flows into and out of agents. AgentContext carries the user prompt, parameters, documents, and conversation history. AgentResult carries the response, execution metadata, and token usage.

ToolRegistry

The central registry for managing tools available to agents. Supports registration, lookup, execution, parameter validation, metadata inspection, scoped sub-registries, and search by category or tag.

@Tool Decorator

The class decorator for defining tools declaratively. Attach metadata (name, description, parameter schemas) to a class, and the framework handles validation and registry integration automatically.

Dynamic Tools

A functional API for registering tools at runtime without decorators. Use registerDynamicTool() when tool definitions come from configuration, external APIs, or user input.

How They Work Together

A typical agent setup follows this pattern:

  1. Define tools using @Tool decorators or registerDynamicTool()
  2. Create a ToolRegistry and register your tools
  3. Extend BaseAgent and implement executeInternal()
  4. Call agent.execute(context) with an AgentContext
  5. The framework handles timeout, error wrapping, stats, and returns an AgentResult
import {
  BaseAgent,
  ToolRegistry,
  Tool,
  ITool,
  AgentContext,
} from "@modernpath/agent-framework";

// Step 1: Define a tool
@Tool({
  name: "calculator",
  description: "Performs arithmetic operations",
  parameters: {
    expression: { type: "string", description: "Math expression to evaluate" },
  },
})
class CalculatorTool implements ITool {
  async execute(params: Record<string, any>): Promise<any> {
    return { result: eval(params.expression) }; // simplified example
  }
}

// Step 2: Create registry and register
const registry = new ToolRegistry();
registry.register("calculator", new CalculatorTool());

// Step 3: Extend BaseAgent
class MathAgent extends BaseAgent {
  constructor(toolRegistry: ToolRegistry) {
    super("MathAgent", "1.0.0", toolRegistry);
  }

  protected async executeInternal(context: AgentContext): Promise<any> {
    return await this.useTool("calculator", {
      expression: context.parameters.expression,
    });
  }

  clone(toolRegistry: ToolRegistry): BaseAgent {
    return new MathAgent(toolRegistry);
  }
}

// Step 4: Execute
const agent = new MathAgent(registry);
const result = await agent.execute({
  userId: 1,
  auditingId: 100,
  prompt: "Calculate 2 + 2",
  parameters: { expression: "2 + 2" },
});
// result.data => { result: 4 }