Installation¶

The ModernPath Agents Framework is distributed as two npm packages published to Google Cloud Artifact Registry. This page covers prerequisites, registry configuration, and installation commands.

Prerequisites¶

Requirement	Details
Node.js	Version 20.0 or later. The backend runtime uses Node 20 APIs (`crypto.randomUUID`, native fetch).
React	Version 18.0 or later (only required if you use `@modernpath/agent-ui-react`).
GCP Project	A Google Cloud project with the Gemini API (Generative Language API) enabled. You will need an API key or service account credentials.
TypeScript	Version 5.0+ is recommended. The framework ships with full type declarations.

Configure GCP Artifact Registry¶

Both packages are scoped under @modernpath and hosted in GCP Artifact Registry. You must configure npm to resolve this scope from the registry before installing.

Step 1 -- Authenticate with Artifact Registry¶

Use the Google Cloud CLI to set up credentials:

# Install gcloud CLI if you have not already
# https://cloud.google.com/sdk/docs/install

# Authenticate to Artifact Registry
gcloud auth application-default login

# Configure npm credentials for the registry
npx google-artifactregistry-auth

Step 2 -- Configure .npmrc¶

Create or update the .npmrc file in your project root (or your home directory for global access):

.npmrc

@modernpath:registry=https://europe-west1-npm.pkg.dev/YOUR_GCP_PROJECT_ID/modernpath-npm/
//europe-west1-npm.pkg.dev/YOUR_GCP_PROJECT_ID/modernpath-npm/:always-auth=true

Replace the placeholder

Replace YOUR_GCP_PROJECT_ID with your actual GCP project ID. The region (europe-west1) and repository name (modernpath-npm) should match the registry provided to you during onboarding.

Step 3 -- Verify access¶

npm view @modernpath/agent-framework version

If this prints a version number (e.g. 0.1.27), your registry configuration is working correctly.

Install Packages¶

Backend onlyFull stack (Backend + UI)Monorepo / Workspaces

If you are building a backend service without the React UI:

npm install @modernpath/agent-framework

For projects that include both the agent backend and a React frontend:

npm install @modernpath/agent-framework
npm install @modernpath/agent-ui-react

In a monorepo with separate apps/backend and apps/ui workspaces:

# From the backend workspace
cd apps/backend
npm install @modernpath/agent-framework

# From the UI workspace
cd apps/ui
npm install @modernpath/agent-ui-react

Peer Dependencies¶

@modernpath/agent-framework¶

The backend package has the following peer dependencies:

Package	Version	Notes
`@google/genai`	`^1.0.0`	Google Generative AI SDK. The framework wraps this internally via `GeminiClient`.
`yaml`	`^2.0.0`	Used by `PromptTemplate` to load YAML prompt files.
`zod`	`^3.0.0`	Used by `FrameworkConfig` for configuration validation.

Install them alongside the framework:

npm install @google/genai yaml zod

@modernpath/agent-ui-react¶

The UI package has the following peer dependencies:

Package	Version	Notes
`react`	`^18.0.0`	React runtime.
`react-dom`	`^18.0.0`	React DOM renderer.

These are typically already present in any React project.

Verify Installation¶

Create a quick test file to verify everything is wired up:

verify.ts

import { ToolRegistry } from "@modernpath/agent-framework";

const registry = new ToolRegistry();
console.log("Framework loaded. Tool count:", registry.list().length);

Run it:

npx tsx verify.ts

You should see:

Framework loaded. Tool count: 0

Next step

Your installation is ready. Head to the Quick Start to build your first agent.