Skip to content

ModernPath Agents Framework

Build production-grade AI agents with a full-stack TypeScript framework powered by Google Gemini.

ModernPath Agents Framework provides everything you need to go from prototype to production: a backend runtime for orchestrating agents, tools, and knowledge retrieval, paired with drop-in React UI components for chat, tracing, and administration. Deploy to GCP Cloud Functions, Azure Functions, or Cloud Run with a single adapter call.

  • Agents

    Extend BaseAgent with a structured lifecycle -- validation, execution, timeout, and tracing are handled for you. Ship faster with built-in agents: QAChatAgent, DocumentAnalysisAgent, OrchestratorAgent, and WebResearchAgent.

    Core Agents

  • Tools

    Define tools with the @Tool decorator or register them dynamically at runtime. Consume remote tools via MCP (Model Context Protocol) and expose your own tools as MCP servers -- all through a unified ToolRegistry.

    Tool System

  • Knowledge Base

    RAG retrieval powered by Gemini File Search Stores. Attach canonical documents for grounding, compose multi-file bundles, and control what reaches the LLM with a declarative grounding policy.

    Knowledge Base

  • Tracing

    Full observability out of the box. Every agent execution produces a trace with spans for LLM calls, tool invocations, and retrieval steps. Track token usage and cost with CostCalculator. Store traces in memory or Firestore.

    Tracing

  • Serverless

    Deploy anywhere with platform adapters. gcpHttp wraps your handler for Cloud Functions, azureHttp targets Azure Functions, and streaming SSE handlers work on Cloud Run. One handler, any platform.

    Serverless

  • React UI

    Drop-in components for agent interfaces: AgentChat with streaming support, TraceExplorer for debugging, KnowledgeBaseManager for admin, and hooks like useAgentChat for custom layouts.

    UI Components

Architecture Overview

The framework follows a layered architecture. The React UI communicates with a serverless backend over HTTP or Server-Sent Events. The backend handler delegates to an agent, which orchestrates tools, Gemini LLM calls, and knowledge base retrieval. Tracing captures every step.

graph LR
    subgraph "Frontend"
        UI["React UI<br/><code>@modernpath/agent-ui-react</code>"]
    end

    subgraph "Serverless Layer"
        Handler["Handler Factory<br/><code>createAgentExecuteHandler</code><br/><code>createAgentExecuteStreamHandler</code>"]
        Adapter["Platform Adapter<br/><code>gcpHttp</code> | <code>azureHttp</code>"]
    end

    subgraph "Agent Runtime"
        Agent["BaseAgent<br/><code>executeInternal()</code>"]
        Tools["ToolRegistry<br/><code>@Tool</code> decorator"]
        Gemini["GeminiClient<br/><code>@google/genai</code>"]
        KB["Knowledge Base<br/>File Search Stores<br/>Canonical Grounding"]
    end

    subgraph "Observability"
        Tracing["TraceStore<br/>InMemory | Firestore"]
    end

    UI -- "HTTP / SSE" --> Adapter
    Adapter --> Handler
    Handler --> Agent
    Agent --> Tools
    Agent --> Gemini
    Agent --> KB
    Agent -. "spans & traces" .-> Tracing
    UI -. "trace queries" .-> Tracing

Packages

Package Description Runtime
@modernpath/agent-framework Backend runtime -- agents, tools, Gemini client, RAG, tracing, serverless handlers Node.js 20+
@modernpath/agent-ui-react React UI components -- chat, traces, admin, hooks, backend factories React 18+

Both packages are published to GCP Artifact Registry under the @modernpath scope.

  • Getting Started

    Install the packages and build your first agent in 10 minutes.

  • Backend Framework

    Deep dive into agents, tools, Gemini integration, and serverless deployment.

  • UI Components

    Explore React components, hooks, and backend factories.

  • Deployment

    Deploy to GCP Cloud Functions, Azure Functions, or Cloud Run.