Skip to content

FrameworkConfig

The FrameworkConfig interface defines the top-level framework configuration, validated at runtime by a Zod schema. The loadFrameworkPrompts() function bootstraps prompt loading from a validated configuration object.

Import

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

FrameworkConfig Interface

interface FrameworkConfig {
  gemini?: {
    apiKey: string;
    model?: string;
    maxOutputTokens?: number;
    temperature?: number;
  };
  prompts: {
    path: string;
    format?: "yaml" | "json";
  };
  agents?: {
    path?: string;
    enabled?: string[];
  };
}

Configuration Properties

Property Type Required Description
gemini object No Gemini LLM configuration.
gemini.apiKey string Yes (if gemini) Google AI API key.
gemini.model string No Model identifier (e.g. "gemini-2.5-flash").
gemini.maxOutputTokens number No Maximum output tokens per request.
gemini.temperature number No Sampling temperature (0--2).
prompts object Yes Prompt template configuration.
prompts.path string Yes Path to the directory containing prompt files.
prompts.format "yaml" \| "json" No Prompt file format. Defaults to "yaml".
agents object No Agent discovery configuration.
agents.path string No Path to the directory containing agent modules.
agents.enabled string[] No List of agent names to enable.

frameworkConfigSchema

A Zod schema that validates FrameworkConfig objects at runtime. Use this to validate configuration loaded from files or environment variables.

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

const config = frameworkConfigSchema.parse({
  prompts: { path: "./prompts", format: "yaml" },
  gemini: { apiKey: process.env.GEMINI_API_KEY },
});

The schema applies the following validations:

  • gemini.apiKey must be a non-empty string
  • gemini.model must be a non-empty string (if provided)
  • gemini.maxOutputTokens must be a positive integer (if provided)
  • gemini.temperature must be between 0 and 2 (if provided)
  • prompts.path must be a non-empty string
  • The gemini object uses .passthrough() to allow additional provider-specific fields

loadFrameworkPrompts()

async function loadFrameworkPrompts(config: FrameworkConfig): Promise<PromptTemplate>

Validates the configuration with frameworkConfigSchema, instantiates a PromptTemplate with the configured path and format, loads all prompt files, and returns the populated template instance.

Parameter Type Description
config FrameworkConfig Framework configuration object.

Returns: Promise<PromptTemplate> -- a loaded and ready-to-use prompt template instance.

Throws: Zod validation error if the configuration is invalid.

Code Example

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

// Load configuration (e.g., from a YAML config file or environment)
const config: FrameworkConfig = {
  gemini: {
    apiKey: process.env.GEMINI_API_KEY!,
    model: "gemini-2.5-flash",
    temperature: 0.3,
    maxOutputTokens: 8192,
  },
  prompts: {
    path: "./config/prompts",
    format: "yaml",
  },
  agents: {
    enabled: ["incident-resolver", "qa-chat"],
  },
};

// Bootstrap prompts with validation
const prompts = await loadFrameworkPrompts(config);

// Use the loaded prompts
const systemPrompt = prompts.render("agent.system", {
  agentName: "IncidentResolver",
  version: "2.1.0",
});

Validation Error Handling

import { frameworkConfigSchema } from "@modernpath/agent-framework";
import { ZodError } from "zod";

try {
  const config = frameworkConfigSchema.parse(rawConfig);
} catch (err) {
  if (err instanceof ZodError) {
    console.error("Configuration validation failed:");
    for (const issue of err.issues) {
      console.error(`  ${issue.path.join(".")}: ${issue.message}`);
    }
  }
}