Migrate Dynamic Agents to 8.10

Copy link to this section

Overview

The 8.10 release changes how a dynamic agent stores its configuration. In 8.9, an agent kept its full configuration inside a single config field. In 8.10, that configuration moves onto first-class fields on the agent itself, several built-in tools are renamed, and the config field becomes a deprecated compatibility field.

These changes alter the agent schema, so the standard schema upgrade cannot finish the migration on its own. A dynamic agent depends on its seeded tools, and seeding runs only after the schema upgrade completes. To break this dependency, the Genai.MigrationUtil type provides a one-time migration function that you run manually after the upgrade.

This guide covers an 8.9 to 8.10 upgrade. The same function also migrates legacy agents from a 6.1 to 8.10 upgrade. The procedure is identical for both.

Copy link to this section

How the migration works

The migration does not change existing agent records. Instead, it creates a new agent cloned from each old agent's configuration, then points the deployment at the new agent. The function migrateDeploymentsAndCleanup() performs four actions in order:

1. Hides the renamed legacy tools so they no longer appear in tool lists.
2. Creates a new Genai.Agent.Dynamic.Core agent for each agent that still stores a config value.
3. Swaps the new agent onto each affected deployment.
4. Restarts the engine for each enabled deployment so it picks up the new agent.

While it creates each agent, the migration also applies a set of transforms that flatten the old config value into the new fields, remap tool references to their renamed versions, and apply defaults for fields that did not exist in 8.9.

Copy link to this section

Before you begin

Complete these steps in order. The migration depends on the upgrade and the seed data already being in place.

1. Upgrade your application to 8.10. The schema upgrade runs as part of this step.
2. Confirm that 8.10 seed data is applied. The migration uses the renamed tool seed records, so they must exist first.

Copy link to this section

Run the migration

Call the migration function from a JavaScript console connected to the upgraded application. The function takes no arguments.

Genai.MigrationUtil.migrateDeploymentsAndCleanup();

The function first warms up the Python runtimes on every node, which can take a few minutes, and then runs the four migration actions. It writes progress to the log as it works. After it returns, re-test your deployments to confirm the migrated agents respond as expected.

Copy link to this section

How an agent changes

The migration flattens the old config value onto direct fields and resolves a few values to their 8.10 equivalents. The following table maps the most common 8.9 values to their 8.10 fields.

• config.chatManagerSpec.systemPrompt: Becomes the systemPrompt field.
• config.llmConfigName: Becomes the llmClient field, resolved to a completion client by configuration key.
• config.toolkit.tools: Becomes the tools field.
• config.maxSteps: Becomes the maxSteps field. The default changes from 20 to 100 in 8.10.
• Data model graph: The migration attaches the default data model graph to the new dataModelGraph field.

The migration also applies these behavior defaults for fields that did not exist in 8.9:

• enableStructuredOutput: Set to false. Agents from 8.9 use the XML-tag prompt structure, which does not use structured output.
• nonLlmToolKwargs: Populated with defaults for the retrieval and fuzzy-match tools when those tools are present.
• forceSolutionPrompt: Set to the default prompt when the agent does not already define one.

Copy link to this section

Renamed tools

The migration rewrites tool references to their 8.10 names. The original tool records are not deleted. They are hidden so they no longer appear in tool lists.

• fuzzy_match_string_values: Renamed to fuzzy_match_string_values_v2.
• rag_unified: Renamed to rag_unified_v2.
• structured_data_query: Renamed to structured_data_query_v2.
• unstructured_data_question_answering: Renamed to unstructured_data_question_answering_v2.
• unstructured_di_compatible_qa: Renamed to unstructured_di_compatible_qa_v2.
• execute_retrieval_spec: Renamed to execute_retrieval_spec_tool and changed to a structured tool.

Copy link to this section

Migrated record names

The migration gives each new agent a name derived from the original, so you can find the migrated records and so the function can run again safely. A new agent uses the original ID and name with a version suffix added.

• Agents migrated from a deployed 8.9 agent use the suffix __migrated_v89_v810.
• Agents migrated from a legacy 6.1 agent use the suffix __migrated_v61_v810.

For example, an 8.9 agent with the ID salesAgent becomes a new agent with the ID salesAgent__migrated_v89_v810.

Copy link to this section

Verify the migration

The function does not return a result. To confirm it worked, read the log lines it writes and check the migrated records. The log reports a count for each action, for example the number of agents created, deployments swapped, and engines restarted.

Then confirm the following:

1. New agents exist with the __migrated_v89_v810 suffix.
2. Each enabled deployment points at its migrated agent and has a running engine.
3. The renamed legacy tools are hidden.

Copy link to this section

Recover from a partial migration

The function is safe to run again. It derives each new agent's ID from the source agent, so a repeat run reuses the same IDs and skips agents that already exist. If a run stops partway through, run migrateDeploymentsAndCleanup() again to finish.

A repeat run completes any step that did not finish:

• If agents were created but deployments were not yet swapped, the next run completes the swap.
• If a deployment was swapped but its engine restart failed, the next run finds the deployment by its migrated agent name and restarts the engine.

The migration logs an error for any engine that fails to restart, but it continues with the remaining deployments rather than stopping. Review these errors after the run and re-run the function to retry them.