Skip to content

Backend Framework

The @modernpath/agent-framework package is the server-side runtime for building, composing, and deploying AI agents. It provides the foundational abstractions for agent lifecycle management, tool orchestration, knowledge retrieval, document processing, tracing, and serverless deployment.

Installation

npm install @modernpath/agent-framework

Architecture Overview

The framework is organized into layered modules, each with a clear responsibility:

graph TD
    A[Your Application] --> B[Built-in Agents]
    A --> C[Custom Agents]
    B --> D[Core Runtime]
    C --> D
    D --> E[ToolRegistry]
    D --> F[Gemini Integration]
    D --> G[Knowledge Base]
    D --> H[Tracing]
    E --> I[Tool Decorator]
    E --> J[Dynamic Tools]
    E --> K[MCP Integration]
    F --> L[GeminiClient]
    G --> M[RetrievalService]
    G --> N[Ingestion]
    D --> O[Serverless Adapters]

Modules

Module Description Key Exports
Core Base classes and interfaces for agents, tools, and execution context BaseAgent, ToolRegistry, AgentContext
Built-in Agents Ready-to-use agents for common tasks QAChatAgent, DocumentAnalysisAgent, OrchestratorAgent, WebResearchAgent
Gemini Integration Client wrapper for Google Gemini models GeminiClient, ChatSession
Knowledge Base RAG retrieval and document ingestion via Gemini File Search Stores RetrievalService, IngestionService
Configuration Prompt templates and framework-level settings PromptTemplate, FrameworkConfig
Document Processing Parsing, querying, and attaching documents DocumentParser, DocumentQuery
Tracing Observability with span-level tracing and cost tracking TraceStore, TraceContext, CostCalculator
Conversations Multi-turn conversation persistence ConversationStore
SharePoint Microsoft Graph integration for document access SharePointAuth, AccessValidator
MCP Integration Model Context Protocol tool consumption and exposure registerMcpRemoteTools
Serverless Handler factories and platform adapters for GCP and Azure createAgentHandler, gcpAdapter, azureAdapter
Admin Knowledge base administration KBAdminService

Design Principles

Agent-centric. Every AI capability is encapsulated in an agent that extends BaseAgent. Agents own their execution lifecycle, including timeout management, error handling, statistics tracking, and optional tracing.

Tool-driven composition. Agents interact with external systems exclusively through the ToolRegistry. Tools are registered declaratively (via the @Tool decorator) or programmatically (via registerDynamicTool), and agents discover and invoke them at runtime.

Framework-agnostic. The core runtime has no dependency on Express, NestJS, or any HTTP framework. Serverless adapters translate platform-specific request/response shapes into the framework's AgentContext interface.

Opt-in observability. Tracing is not required. When a TraceStore is attached to an agent via setTraceStore(), every execution automatically produces structured traces with spans, token counts, and cost data.

Quick Example

import {
  BaseAgent,
  ToolRegistry,
  AgentContext,
  AgentResult,
} from "@modernpath/agent-framework";

// 1. Create a tool registry and register tools
const registry = new ToolRegistry();

// 2. Build your agent
class GreetingAgent extends BaseAgent {
  constructor(toolRegistry: ToolRegistry) {
    super("GreetingAgent", "1.0.0", toolRegistry);
  }

  protected async executeInternal(context: AgentContext): Promise<any> {
    return { message: `Hello, ${context.parameters.name}!` };
  }

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

// 3. Execute
const agent = new GreetingAgent(registry);
const result: AgentResult = await agent.execute({
  userId: 1,
  auditingId: 100,
  prompt: "Say hello",
  parameters: { name: "World" },
});

console.log(result.data.message); // "Hello, World!"

Next Steps

  • Core module -- understand BaseAgent, ToolRegistry, and AgentContext
  • Built-in Agents -- use pre-built agents for RAG, document analysis, and orchestration
  • Serverless deployment -- deploy agents to GCP Cloud Functions or Azure Functions