Environment Variables¶
This page documents every environment variable recognized by @modernpath/agent-framework and the common patterns used in production deployments. Variables are grouped by subsystem.
Core¶
These variables configure the Gemini client and fundamental runtime behavior.
| Variable | Description | Required | Default |
|---|---|---|---|
GOOGLE_AI_STUDIO_KEY | Gemini API key from Google AI Studio. This is the primary authentication mechanism for the Gemini API. | Yes | -- |
GEMINI_API_KEY | Alias for GOOGLE_AI_STUDIO_KEY. The framework checks GOOGLE_AI_STUDIO_KEY first, then falls back to GEMINI_API_KEY. | No | -- |
GEMINI_MODEL | The Gemini model name to use for LLM calls. | No | gemini-3-flash-preview |
GCP_PROJECT_ID | Google Cloud project ID. Enables Firestore-backed TraceStore and ConversationStore. When not set, the framework falls back to in-memory stores. | For Firestore | -- |
PORT | HTTP port for the server to listen on. Used by Cloud Run and local development servers. | No | 8080 |
NODE_ENV | Node.js environment. Set to production in deployed environments. | No | production |
Debug & Logging¶
| Variable | Description | Required | Default |
|---|---|---|---|
DEBUG | Debug logging pattern. Enables verbose logging for framework internals. Supports glob-like patterns. | No | -- |
Debug patterns¶
The DEBUG variable controls which subsystems emit debug logs. Set it to * to enable all debug output, or use specific patterns:
| Pattern | What it enables |
|---|---|
* | All debug output from all subsystems |
gemini-client | Gemini API request/response logging |
retrieval-service | RAG retrieval queries and results |
canonical-grounding | Canonical document grounding decisions |
composition-loader | Document composition bundle loading |
file-search-stores | File Search Store operations |
firestore-trace-store | Firestore trace read/write operations |
firestore-conversation-store | Firestore conversation operations |
qa-chat | QAChatAgent internal flow |
You can combine patterns with commas:
Knowledge Base¶
These variables configure RAG retrieval, canonical grounding, and document composition.
| Variable | Description | Required | Default |
|---|---|---|---|
KB_STORE | Default File Search Store name (e.g., fileSearchStores/my-store). Used when no store is specified in the agent request parameters. | No | -- |
GROUNDING_MODE | Controls which knowledge sources reach the LLM prompt. | No | chunks_only |
CANONICAL_GROUNDING | Enable canonical document grounding. Automatically set to true when GROUNDING_MODE is attachments_only or hybrid. | No | false |
GCS_GROUND_TRUTH_BUCKET | GCS bucket for ground-truth canonical documents. | No | -- |
GCS_GROUND_TRUTH_PREFIX | Key prefix within the GCS bucket. | No | kb |
KB_CANONICAL_SOURCE | Source for canonical documents. Set to gcs to load from GCS. | No | -- |
RAG_QUERY_STRATEGY | Strategy for transforming the user query before RAG retrieval. | No | llm-summary |
Grounding modes¶
The GROUNDING_MODE variable accepts the following values:
| Mode | Behavior |
|---|---|
chunks_only | Only RAG-retrieved chunks are included in the LLM prompt. No canonical documents are attached. This is the default. |
attachments_only | Only canonical attached documents are used. RAG chunks are not included in the prompt. |
hybrid | Both RAG chunks and canonical documents are available to the LLM. |
How grounding mode affects the prompt
The decideGrounding() function in the framework evaluates the grounding mode and returns retrievedTextForPrompt accordingly. In attachments_only mode, this value is an empty string -- RAG chunks are retrieved for tracing purposes but excluded from the synthesis prompt.
RAG query strategies¶
The RAG_QUERY_STRATEGY variable controls how the user's prompt is transformed before being sent to the File Search Store:
| Strategy | Description |
|---|---|
llm-summary | Uses the Gemini model to generate an optimized search query from the user prompt. Best quality, adds one LLM call. |
clean-text | Applies deterministic text cleaning (remove special characters, normalize whitespace). Fast, no LLM call. |
deterministic | Custom deterministic transformation function. |
Tracing & Observability¶
| Variable | Description | Required | Default |
|---|---|---|---|
TRACE_CAPTURE_CONTENT | When true, full prompt text and LLM responses are stored in trace spans. Set to false in production if you need to avoid storing PII. | No | true |
LLM_PRICING_CONFIG_PATH | Path to a JSON file containing custom LLM pricing data for CostCalculator. Overrides built-in pricing. | No | -- |
Composition¶
| Variable | Description | Required | Default |
|---|---|---|---|
COMPOSITION_BUNDLE_PATH | File path to the document composition bundle (JSON). Used by CompositionLoader to assemble multi-file canonical documents. | No | -- |
External Integrations¶
Tavily (Web Search)¶
| Variable | Description | Required | Default |
|---|---|---|---|
TAVILY_API_KEY | API key for Tavily web search. Required when using WebResearchAgent or registering Tavily MCP tools. | No | -- |
SharePoint¶
| Variable | Description | Required | Default |
|---|---|---|---|
SHAREPOINT_TENANT_ID | Azure AD tenant ID for Microsoft Graph authentication. | For SharePoint | -- |
SHAREPOINT_CLIENT_ID | Azure AD application (client) ID. | For SharePoint | -- |
SHAREPOINT_CLIENT_SECRET | Azure AD client secret. | For SharePoint | -- |
SHAREPOINT_SITE_URL | SharePoint site URL. | For SharePoint | -- |
Authentication (Application-Level)¶
These are not framework variables but are commonly used in production deployments for application-level authentication:
| Variable | Description | Required | Default |
|---|---|---|---|
API_KEY | Bearer token for API authentication. | No | -- |
ADMIN_USERNAME | Username for Basic Auth on admin endpoints. | No | -- |
ADMIN_PASSWORD | Password for Basic Auth on admin endpoints. | No | -- |
Use Secret Manager
Never set GOOGLE_AI_STUDIO_KEY, API_KEY, ADMIN_PASSWORD, or other secrets as plain environment variables in your deployment configuration. Use your platform's secret management service:
- GCP: Secret Manager with
--set-secrets - Azure: Key Vault references
Example: Complete .env File¶
For local development, create a .env file in your project root:
# Core
GOOGLE_AI_STUDIO_KEY=your-api-key-here
GEMINI_MODEL=gemini-3-flash-preview
GCP_PROJECT_ID=my-project-id
# Server
PORT=8080
NODE_ENV=development
# Knowledge Base
KB_STORE=fileSearchStores/my-knowledge-base
GROUNDING_MODE=chunks_only
RAG_QUERY_STRATEGY=llm-summary
# Tracing
TRACE_CAPTURE_CONTENT=true
DEBUG=gemini-client,retrieval-service
# External
TAVILY_API_KEY=your-tavily-key
# Auth (optional, for local testing)
ADMIN_USERNAME=admin
ADMIN_PASSWORD=dev-password
Never commit .env files
Add .env and .env.local to your .gitignore. These files contain secrets that must not be stored in version control.
Example: Cloud Run Deployment¶
When deploying to Cloud Run, set environment variables and secrets via the gcloud CLI:
gcloud run deploy my-agent \
--set-env-vars "\
GCP_PROJECT_ID=my-project,\
GEMINI_MODEL=gemini-3-flash-preview,\
GROUNDING_MODE=chunks_only,\
TRACE_CAPTURE_CONTENT=true,\
KB_STORE=fileSearchStores/my-store" \
--set-secrets "\
GOOGLE_AI_STUDIO_KEY=my-gemini-key-secret:latest,\
TAVILY_API_KEY=my-tavily-key-secret:latest,\
API_KEY=my-api-key-secret:latest"
Variable Precedence¶
When using dotenv in your entry point (recommended for local development), variables are loaded in this order, with later sources overriding earlier ones:
<repo-root>/.env<repo-root>/.env.local(override)<app-root>/.env(override)<app-root>/.env.local(override)- Process environment (always wins)
This allows you to set shared defaults at the repo level and override per-application or per-environment.