Skip to content

Environment Setup

This page documents all environment variables used by the ModernPath Agents Framework, the available Gemini models, and provides a ready-to-use .env.example template.

Environment Variables

Required

Variable Description Example
GOOGLE_AI_STUDIO_KEY API key for Google AI Studio (Gemini API). Passed to GeminiClient as apiKey. AIzaSy...

GCP Integration

Variable Description Example
GCP_PROJECT_ID Google Cloud project ID. Required for Firestore-backed trace and conversation stores, and for File Search Stores. my-project-123
GCP_REGION GCP region for Artifact Registry and Cloud Functions deployment. europe-west1
FIRESTORE_DATABASE Firestore database name (if not using the default (default) database). agents-db

Gemini Configuration

Variable Description Default
GEMINI_MODEL Default model name passed to GeminiClient. Can be overridden per-client instance. gemini-3-flash-preview
GEMINI_MAX_OUTPUT_TOKENS Maximum tokens in generated responses. 8192
GEMINI_TEMPERATURE Sampling temperature (0.0 -- 2.0). Lower values produce more deterministic output. 0.7

Knowledge Base / RAG

Variable Description Default
GROUNDING_MODE Controls grounding policy. Values: rag_and_attachments, attachments_only, rag_only. When set to attachments_only, RAG chunks are excluded from the LLM prompt. rag_and_attachments
KB_DEFAULT_STORE Default File Search Store display name for QAChatAgent. (none)
KB_DEFAULT_TOP_K Default number of chunks to retrieve in RAG queries. 10

SharePoint Integration

Variable Description Example
SHAREPOINT_TENANT_ID Azure AD tenant ID for SharePoint access. a1b2c3d4-...
SHAREPOINT_CLIENT_ID Azure AD application (client) ID. e5f6g7h8-...
SHAREPOINT_CLIENT_SECRET Azure AD client secret. abc123~...
SHAREPOINT_SITE_URL SharePoint site URL for document access. https://contoso.sharepoint.com/sites/docs

Tracing & Observability

Variable Description Default
TRACE_STORE_TYPE Trace store backend. Values: inmemory, firestore. inmemory
TRACE_COLLECTION_PREFIX Firestore collection prefix for trace documents. traces
DEBUG Enable debug logging. Set to * for all, or gemini-client, qa-agent, etc. for targeted output. (none)

Deployment

Variable Description Example
PORT HTTP server port for local development and Cloud Run. 3001
NODE_ENV Runtime environment. production
CORS_ORIGIN Allowed CORS origin for agent endpoints. Use * only in development. https://app.example.com

Available Gemini Models

The framework supports any model available through the @google/genai SDK. Pass the model identifier to GeminiClient via the model configuration option.

Model Identifier Best For
Gemini 2.5 Flash gemini-2.5-flash Production workloads requiring speed and cost efficiency. Strong reasoning with fast response times.
Gemini 2.5 Flash Lite gemini-2.5-flash-lite High-volume, cost-sensitive tasks. Lower latency at reduced capability.
Gemini 3 Flash (Preview) gemini-3-flash-preview Latest generation flash model. Default for the framework. Best balance of capability and speed.
Gemini 3 Pro (Preview) gemini-3-pro-preview Highest capability model for complex reasoning, analysis, and multi-step tasks. Higher latency and cost.

Model availability

Preview models are subject to change and may require allowlisting on your GCP project. Check the Google AI Studio dashboard for current availability.

Selecting a model

Set the model when constructing GeminiClient:

const gemini = new GeminiClient({
  apiKey: process.env.GOOGLE_AI_STUDIO_KEY!,
  model: "gemini-2.5-flash",
});

Individual generateContent calls cannot change the model, but you can create multiple GeminiClient instances for different models:

const flashClient = new GeminiClient({
  apiKey: process.env.GOOGLE_AI_STUDIO_KEY!,
  model: "gemini-2.5-flash",
});

const proClient = new GeminiClient({
  apiKey: process.env.GOOGLE_AI_STUDIO_KEY!,
  model: "gemini-3-pro-preview",
  temperature: 0.3,
});

Use an environment variable for deployment-time flexibility:

const gemini = new GeminiClient({
  apiKey: process.env.GOOGLE_AI_STUDIO_KEY!,
  model: process.env.GEMINI_MODEL || "gemini-3-flash-preview",
});

.env.example Template

Copy this file to .env and fill in your values:

.env.example
# ── Gemini API ────────────────────────────────────────────
GOOGLE_AI_STUDIO_KEY=your-api-key-here
GEMINI_MODEL=gemini-2.5-flash
GEMINI_MAX_OUTPUT_TOKENS=8192
GEMINI_TEMPERATURE=0.7

# ── GCP Project ───────────────────────────────────────────
GCP_PROJECT_ID=your-project-id
GCP_REGION=europe-west1

# ── Knowledge Base / RAG ─────────────────────────────────
GROUNDING_MODE=rag_and_attachments
KB_DEFAULT_STORE=my-knowledge-store
KB_DEFAULT_TOP_K=10

# ── Tracing ───────────────────────────────────────────────
TRACE_STORE_TYPE=inmemory
# TRACE_COLLECTION_PREFIX=traces
# FIRESTORE_DATABASE=agents-db

# ── SharePoint (optional) ────────────────────────────────
# SHAREPOINT_TENANT_ID=
# SHAREPOINT_CLIENT_ID=
# SHAREPOINT_CLIENT_SECRET=
# SHAREPOINT_SITE_URL=

# ── Server ────────────────────────────────────────────────
PORT=3001
NODE_ENV=development
CORS_ORIGIN=*

# ── Debug logging ─────────────────────────────────────────
# DEBUG=*
# DEBUG=gemini-client,qa-agent

Keep your .env out of version control

Add .env to your .gitignore file. Never commit API keys or secrets to a repository.

Framework Configuration (programmatic)

In addition to environment variables, the framework supports a typed FrameworkConfig object validated with Zod:

import { loadFrameworkPrompts, type FrameworkConfig } from "@modernpath/agent-framework";

const config: FrameworkConfig = {
  gemini: {
    apiKey: process.env.GOOGLE_AI_STUDIO_KEY!,
    model: "gemini-2.5-flash",
    temperature: 0.5,
  },
  prompts: {
    path: "./prompts",
    format: "yaml",
  },
  agents: {
    enabled: ["QAChatAgent", "DocumentAnalysisAgent"],
  },
};

const prompts = await loadFrameworkPrompts(config);

The FrameworkConfig schema is defined as:

Field Type Required Description
gemini.apiKey string Yes Gemini API key.
gemini.model string No Model identifier.
gemini.maxOutputTokens number No Max output tokens.
gemini.temperature number No Temperature (0.0 -- 2.0).
prompts.path string Yes Path to prompt template directory.
prompts.format "yaml" \| "json" No Prompt file format. Defaults to yaml.
agents.path string No Path to agent definitions.
agents.enabled string[] No List of agent names to enable.