Migration Guide¶
This guide provides step-by-step instructions for upgrading between versions of the ModernPath Agents Framework. Each section covers breaking changes, deprecated APIs, and the actions required to migrate.
General Upgrade Process¶
Follow this process for any version upgrade:
Step 1 -- Read the Changelog¶
Before upgrading, review the Changelog for all versions between your current version and the target version. Pay special attention to Breaking Changes sections.
Step 2 -- Update Dependencies¶
Or pin to a specific version:
Step 3 -- Run Type Checks¶
TypeScript will surface any API incompatibilities introduced by the upgrade.
Step 4 -- Run Tests¶
Step 5 -- Test Locally¶
Start your development server and verify agent execution, RAG retrieval, streaming, and tracing work as expected.
0.1.26 to 0.1.27¶
Impact: Low
RAG Query Strategy¶
The RetrievalService now supports configurable query strategies. The default strategy changed from direct pass-through to llm-summary, which uses the Gemini model to optimize the search query.
Action required: If you rely on the exact query being passed to the File Search Store, set RAG_QUERY_STRATEGY=deterministic in your environment variables.
Grounding Policy Fix¶
The decideGrounding() function now correctly returns an empty retrievedTextForPrompt in attachments_only mode. Previously, RAG chunks could leak into the synthesis prompt in this mode.
Action required: If your agent manually built the synthesis prompt using raw ragContext instead of synthDecision.retrievedTextForPrompt, update it to use the grounding decision output:
// Before (incorrect in attachments_only mode)
const prompt = buildPrompt(ragContext);
// After (correct)
const synthDecision = decideGrounding({ ragContext, groundingMode });
const prompt = buildPrompt(synthDecision.retrievedTextForPrompt);
0.1.25 to 0.1.26¶
Impact: Low
Firestore Depth Flattening¶
FirestoreTraceStore now automatically flattens deeply nested objects (beyond 15 levels) into JSON strings. This prevents Firestore write failures for complex trace data.
Action required: None. This is a transparent improvement. If you have custom code that reads raw Firestore trace documents, be aware that deeply nested fields may now be JSON strings.
Azure Adapter Body Reading¶
The azureHttp adapter now falls back to request.text() when request.body is null. This fixes an issue where Azure Functions v4 runtimes that require explicit body reading would produce empty bodies.
Action required: None. This is a bug fix.
0.1.24 to 0.1.25¶
Impact: Medium
ConversationStore Interface¶
A new ConversationStore interface was introduced for multi-turn conversation persistence. If you previously managed conversation history manually, consider migrating to the built-in stores.
Action required: Optional migration. No existing APIs were removed.
CostCalculator Integration¶
BaseAgent.setTraceStore() now accepts an optional third parameter for CostCalculator:
// Before
agent.setTraceStore(traceStore);
// After (with cost tracking)
const costCalculator = new CostCalculator({
pricingConfigPath: process.env.LLM_PRICING_CONFIG_PATH,
});
agent.setTraceStore(traceStore, undefined, costCalculator);
Action required: None. The new parameter is optional and backward-compatible.
0.1.23 to 0.1.24¶
Impact: Low
MCP Tool Registration¶
The registerMcpRemoteTools() function was added. The ToolRegistry.register() method now accepts a tags array.
Action required: None. This is a new feature with no changes to existing APIs.
0.1.22 to 0.1.23¶
Impact: Low
SSE Streaming¶
New streaming handler factory createAgentExecuteStreamHandler and platform-specific endpoint factories were added. The existing createAgentExecuteHandler is unchanged.
CORS Header Fix¶
CORS headers returned by gcpHttp and azureHttp are now consistently lowercase. If your client code checks for specific header casing (e.g., Access-Control-Allow-Origin), update it to match lowercase keys.
Action required: If you manually inspect CORS headers from the adapters, use lowercase keys.
0.1.21 to 0.1.22¶
Impact: Medium
Grounding Mode Environment Variable¶
The GROUNDING_MODE environment variable was introduced. The default is chunks_only, which preserves the previous behavior.
Action required: None unless you want to opt into attachments_only or hybrid mode. Set the variable explicitly to change behavior.
Canonical Grounding¶
The CanonicalGroundingService and CompositionLoader are new additions. No existing APIs were changed.
0.1.20 to 0.1.21¶
Impact: Low
Firestore Stores¶
FirestoreTraceStore and FirestoreConversationStore were added as alternatives to the in-memory stores. They are activated by setting the GCP_PROJECT_ID environment variable.
Action required: None. In-memory stores continue to work. To migrate to Firestore, set GCP_PROJECT_ID and ensure the service account has roles/datastore.user.
InMemoryTraceStore Options¶
InMemoryTraceStore now accepts captureContent and defaultTags options in its constructor. The previous parameterless constructor continues to work.
Migrating from Pre-0.1.20¶
If you are upgrading from a version earlier than 0.1.20, we recommend upgrading incrementally through each minor version, running tests at each step. Contact your ModernPath representative for assistance with large-version-gap migrations.
Deprecation Policy¶
During the 0.x pre-release phase:
- Deprecated APIs are marked with
@deprecatedJSDoc tags and produce console warnings when used. - Deprecated APIs are removed in the next minor version.
- Breaking changes are documented in the Changelog and this Migration Guide.
After the 1.0 stable release, deprecated APIs will follow a longer deprecation cycle with at least one minor version of warning before removal.
Getting Help¶
If you encounter issues during migration:
- Check the Changelog for the specific version.
- Run
npx tsc --noEmitto surface type errors. - Search for the error message in the framework source code.
- Contact your ModernPath representative for direct assistance.